主题配置

tailwind.config.js 文件的 theme 部分是你定义项目的调色板、类型比例、字体、断点、边框半径值等的地方。

¥The theme section of your tailwind.config.js file is where you define your project’s color palette, type scale, fonts, breakpoints, border radius values, and more.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    screens: {
      sm: '480px',
      md: '768px',
      lg: '976px',
      xl: '1440px',
    },
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

我们为明智的 默认主题 提供了一组非常慷慨的观来帮助你入门，但不要害怕更改或扩展它；我们鼓励你尽可能多地自定义它以满足你的设计目标。

¥We provide a sensible default theme with a very generous set of values to get you started, but don’t be afraid to change it or extend it; you’re encouraged to customize it as much as you need to fit the goals of your design.

​主题结构

¥Theme structure

theme 对象包含 screens、colors 和 spacing 的键，以及每个可自定义的 核心插件 的键。

¥The theme object contains keys for screens, colors, and spacing, as well as a key for each customizable core plugin.

有关主题选项的完整列表，请参阅 主题配置参考 或 默认主题。

¥See the theme configuration reference or the default theme for a complete list of theme options.

​屏幕

¥Screens

screens 键允许你自定义项目中的响应式断点。

¥The screens key allows you to customize the responsive breakpoints in your project.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    screens: {
      'sm': '640px',
      'md': '768px',
      'lg': '1024px',
      'xl': '1280px',
      '2xl': '1536px',
    }
  }
}

要了解更多信息，请参阅 断点定制文档。

¥To learn more, see the breakpoint customization documentation.

​颜色

¥Colors

colors 键允许你为项目自定义全局调色板。

¥The colors key allows you to customize the global color palette for your project.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      black: '#000',
      white: '#fff',
      gray: {
        100: '#f7fafc',
        // ...
        900: '#1a202c',
      },

      // ...
    }
  }
}

默认情况下，这些颜色由所有与颜色相关的核心插件继承，如 backgroundColor、borderColor、textColor 等。

¥By default, these colors are inherited by all color-related core plugins, like backgroundColor, borderColor, textColor, and others.

要了解更多信息，请参阅 颜色定制文档。

¥To learn more, see the color customization documentation.

​间距

¥Spacing

spacing 键允许你为项目自定义全局间距和大小比例。

¥The spacing key allows you to customize the global spacing and sizing scale for your project.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    spacing: {
      px: '1px',
      0: '0',
      0.5: '0.125rem',
      1: '0.25rem',
      1.5: '0.375rem',
      2: '0.5rem',
      2.5: '0.625rem',
      3: '0.75rem',
      3.5: '0.875rem',
      4: '1rem',
      5: '1.25rem',
      6: '1.5rem',
      7: '1.75rem',
      8: '2rem',
      9: '2.25rem',
      10: '2.5rem',
      11: '2.75rem',
      12: '3rem',
      14: '3.5rem',
      16: '4rem',
      20: '5rem',
      24: '6rem',
      28: '7rem',
      32: '8rem',
      36: '9rem',
      40: '10rem',
      44: '11rem',
      48: '12rem',
      52: '13rem',
      56: '14rem',
      60: '15rem',
      64: '16rem',
      72: '18rem',
      80: '20rem',
      96: '24rem',
    },
  }
}

默认情况下，这些值由 padding、margin、width、height、maxHeight、flex-basis、gap、inset、space、translate、scrollMargin、scrollPadding 和 textIndent 核心插件继承。

¥By default, these values are inherited by the padding, margin, width, height, maxHeight, flex-basis, gap, inset, space, translate, scrollMargin, scrollPadding, and textIndent core plugins.

要了解更多信息，请参阅 间距定制文档。

¥To learn more, see the spacing customization documentation.

​核心插件

¥Core plugins

theme 部分的其余部分用于配置哪些值可用于每个单独的核心插件。

¥The rest of the theme section is used to configure which values are available for each individual core plugin.

例如，borderRadius 键可让你自定义将生成哪些边框半径工具：

¥For example, the borderRadius key lets you customize which border radius utilities will be generated:

module.exports = {
  theme: {
    borderRadius: {
      'none': '0',
      'sm': '.125rem',
      DEFAULT: '.25rem',
      'lg': '.5rem',
      'full': '9999px',
    },
  }
}

键确定生成类的后缀，值确定实际 CSS 声明的值。

¥The keys determine the suffix for the generated classes, and the values determine the value of the actual CSS declaration.

上面的示例 borderRadius 配置将生成以下 CSS 类：

¥The example borderRadius configuration above would generate the following CSS classes:

.rounded-none { border-radius: 0 }
.rounded-sm   { border-radius: .125rem }
.rounded      { border-radius: .25rem }
.rounded-lg   { border-radius: .5rem }
.rounded-full { border-radius: 9999px }

你会注意到在主题配置中使用 DEFAULT 键创建了没有后缀的类 rounded。这是 Tailwind 中的常见约定，所有核心插件都支持。

¥You’ll notice that using a key of DEFAULT in the theme configuration created the class rounded with no suffix. This is a common convention in Tailwind and is supported by all core plugins.

要了解有关自定义特定核心插件的更多信息，请访问该插件的文档。

¥To learn more about customizing a specific core plugin, visit the documentation for that plugin.

有关可用主题属性及其默认值的完整参考，查看默认主题配置。

¥For a complete reference of available theme properties and their default values, see the default theme configuration.

​自定义默认主题

¥Customizing the default theme

开箱即用，你的项目将自动继承 默认主题配置 的值。如果你想自定义默认主题，根据你的目标，你有几个不同的选择。

¥Out of the box, your project will automatically inherit the values from the default theme configuration. If you would like to customize the default theme, you have a few different options depending on your goals.

​扩展默认主题

¥Extending the default theme

如果你想保留主题选项的默认值，但还想添加新值，请在配置文件中的 theme.extend 键下添加扩展。该键下的值将与现有的 theme 值合并，并自动成为可供你使用的新类。

¥If you’d like to preserve the default values for a theme option but also add new values, add your extensions under the theme.extend key in your configuration file. Values under this key are merged with existing theme values and automatically become available as new classes that you can use.

例如，这里我们扩展 fontFamily 属性以添加 font-display 类，该类可以更改元素上使用的字体：

¥As an example, here we extend the fontFamily property to add the font-display class that can change the font used on an element:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        display: 'Oswald, ui-serif', // Adds a new `font-display` class
      }
    }
  }
}

将其添加到主题后，你可以像任何其他字体系列工具一样使用它：

¥After adding this to your theme you can use it just like any other font family utility:

<h1 class="font-display">
  This uses the Oswald font
</h1>

在某些情况下，属性映射到 variants，可以将其放置在工具前面以有条件地应用其样式。例如，要添加与现有响应式屏幕一样工作的 3xl 屏幕尺寸，请在 screens 键下添加一个属性：

¥In some cases, properties map to variants that can be placed in front of a utility to conditionally apply its styles. For example, to add a 3xl screen size that works just like the existing responsive screens, add a property under the screens key:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      screens: {
        '3xl': '1600px', // Adds a new `3xl:` screen variant
      }
    }
  }
}

通过此添加，新的 3xl 屏幕尺寸与现有的响应式变体（如 sm、md、lg 等）一起提供。你可以通过将其放置在工具类之前来使用此新变体：

¥With this addition, a new 3xl screen size is made available alongside the existing responsive variants like sm, md, lg, etc. You can use this new variant by placing it before a utility class:

<blockquote class="text-base md:text-md 3xl:text-lg">
  Oh I gotta get on that internet, I'm late on everything!
</blockquote>

​覆盖默认主题

¥Overriding the default theme

要覆盖默认主题中的选项，请直接在 tailwind.config.js 的 theme 部分下添加你的覆盖：

¥To override an option in the default theme, add your overrides directly under the theme section of your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // Replaces all of the default `opacity` values
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    }
  }
}

这将完全替换 Tailwind 对该键的默认配置，因此在上面的示例中，不会生成任何默认的透明度工具。

¥This will completely replace Tailwind’s default configuration for that key, so in the example above none of the default opacity utilities would be generated.

你未提供的任何键都将从默认主题继承，因此在上面的示例中，将保留颜色、间距、边框半径、背景位置等默认主题配置。

¥Any keys you do not provide will be inherited from the default theme, so in the above example, the default theme configuration for things like colors, spacing, border-radius, background-position, etc. would be preserved.

你当然可以覆盖默认主题的某些部分并在同一配置中扩展默认主题的其他部分：

¥You can of course both override some parts of the default theme and extend other parts of the default theme within the same configuration:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    },
    extend: {
      screens: {
        '3xl': '1600px',
      }
    }
  }
}

​引用其他值

¥Referencing other values

如果你需要在主题中引用另一个值，你可以通过提供闭包而不是静态值来实现。闭包将接收一个包含 theme() 函数的对象，你可以使用该函数使用点表示法查找主题中的其他值。

¥If you need to reference another value in your theme, you can do so by providing a closure instead of a static value. The closure will receive an object that includes a theme() function that you can use to look up other values in your theme using dot notation.

例如，你可以通过在 backgroundSize 配置中引用 theme('spacing') 为间距比例中的每个值生成 background-size 工具：

¥For example, you could generate background-size utilities for every value in your spacing scale by referencing theme('spacing') in your backgroundSize configuration:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    spacing: {
      // ...
    },
    backgroundSize: ({ theme }) => ({
      auto: 'auto',
      cover: 'cover',
      contain: 'contain',
      ...theme('spacing')
    })
  }
}

theme() 函数尝试从完全合并的主题对象中找到你要查找的值，因此它可以引用你自己的自定义项以及默认主题值。它还以递归方式工作，因此只要链的末尾有一个静态值，它就能够解析你正在寻找的值。

¥The theme() function attempts to find the value you are looking for from the fully merged theme object, so it can reference your own customizations as well as the default theme values. It also works recursively, so as long as there is a static value at the end of the chain it will be able to resolve the value you are looking for.

请注意，你只能将这种闭包与顶层主题键一起使用，而不是每个部分内部的键。

¥Note that you can only use this kind of closure with top-level theme keys, not the keys inside of each section.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    fill: {
      gray: ({ theme }) => theme('colors.gray')
    }
  }
}

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    fill: ({ theme }) => ({
      gray: theme('colors.gray')
    })
  }
}

​引用默认主题

¥Referencing the default theme

如果你出于任何原因想要在默认主题中引用一个值，你可以从 tailwindcss/defaultTheme 导入它。

¥If you’d like to reference a value in the default theme for any reason, you can import it from tailwindcss/defaultTheme.

一个有用的示例是，如果你想将字体系列添加到 Tailwind 的默认字体堆栈之一：

¥One example of where this is useful is if you’d like to add a font family to one of Tailwind’s default font stacks:

const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: [
          'Lato',
          ...defaultTheme.fontFamily.sans,
        ]
      }
    }
  }
}

​禁用整个核心插件

¥Disabling an entire core plugin

如果你不想为某个核心插件生成任何类，最好在 corePlugins 配置中将该插件设置为 false，而不是在 theme 配置中为该键提供一个空对象。

¥If you don’t want to generate any classes for a certain core plugin, it’s better to set that plugin to false in your corePlugins configuration than to provide an empty object for that key in your theme configuration.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    opacity: {},
  }
}

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: {
    opacity: false,
  }
}

最终结果是一样的，但由于许多核心插件不公开任何配置，因此无论如何只能使用 corePlugins 禁用它们，因此最好保持一致。

¥The end result is the same, but since many core plugins expose no configuration they can only be disabled using corePlugins anyways, so it’s better to be consistent.

​配置参考

¥Configuration reference

除了 screens、colors 和 spacing，theme 对象中的所有键都映射到 Tailwind 的 核心插件 之一。由于许多插件负责只接受一组静态值的 CSS 属性（例如 float），请注意并非每个插件在 theme 对象中都有相应的键。

¥Except for screens, colors, and spacing, all of the keys in the theme object map to one of Tailwind’s core plugins. Since many plugins are responsible for CSS properties that only accept a static set of values (like float for example), note that not every plugin has a corresponding key in the theme object.

所有这些键也可以在 theme.extend 键下使用以启用 扩展默认主题。

¥All of these keys are also available under the theme.extend key to enable extending the default theme.