配置 - Tailwind CSS 中文文档

因为 Tailwind 是一个构建定制用户界面的框架，所以从开始设计时便考虑了定制。

默认情况下，Tailwind 将在项目的根目录中查找一个可选的 tailwind.config.js 的文件，您可以在其中定义任何自定义选项。

// Example `tailwind.config.js` file
const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    colors: {
      gray: colors.coolGray,
      blue: colors.lightBlue,
      red: colors.rose,
      pink: colors.fuchsia,
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  },
  variants: {
    extend: {
      borderColor: ['focus-visible'],
      opacity: ['disabled'],
    }
  }
}

配置文件的每个部分都是可选的，因此您只需指定要更改的内容即可。任何缺少的部分将会使用 Tailwind 的默认配置。

创建配置文件

使用 Tailwind CLI 功能生成 Tailwind 配置文件，Tailwind CLI 在您安装 tailwindcss npm 软件包时已经附带安装过。

npx tailwindcss init

这将在项目的根目录下创建一个最小文件 tailwind.config.js：

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

使用其它文件名

要使用 tailwind.config.js 之外的文件名，请在命令行中将其做为参数传入：

npx tailwindcss init tailwindcss-config.js

如果使用自定义文件名，则在 PostCSS 配置中将 Tailwind 做为插件引入时，也需要指定它：

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: { config: './tailwindcss-config.js' },
  },
}

创建 PostCSS 配置文件

如果您想在生成 tailwind.config.js 文件的同时也生成一个基础的 postcss.config.js 文件，请使用 -p 标志。

npx tailwindcss init -p

这将在您的项目中生成一个 postcss.config.js 文件，如下所示：

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

生成全部默认配置

对于大多数用户，我们建议您尽量减少配置文件，只指定您想自定义的内容。

如果您希望构建一个完整的配置文件，其中包括 Tailwind的所有默认配置，请使用以下 --full 选项：

npx tailwindcss init --full

您将得到一个与 Tailwind 内部使用的默认配置文件一致的文件。

主题

在 theme 部分中，您可以定义调色板、字体、类型比例、边框大小、断点等任何与您网站视觉设计有关的东西。

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      gray: colors.coolGray,
      blue: colors.lightBlue,
      red: colors.rose,
      pink: colors.fuchsia,
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

了解更多关于默认主题及如何对其定制的信息，参考主题配置指南。

变体

variants 部分允许您控制为每个核心功能插件生成哪些变体。

// tailwind.config.js
module.exports = {
  variants: {
    fill: [],
    extend: {
      borderColor: ['focus-visible'],
      opacity: ['disabled'],
    }
  },
}

查看变体配置指南了解更多信息。

插件

plugins 部分允许您向 Tailwind 注册插件，这些插件可用于生成额外功能类、组件、基本样式或自定义变体。

// tailwind.config.js
module.exports = {
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/typography'),
    require('tailwindcss-children'),
  ],
}

了解更多关于编写插件的信息，请查看插件编写指南。

预设

presets 部分允许您指定自己的自定义基本配置，来替代 Tailwind 的默认基本配置。

// tailwind.config.js
module.exports = {
  presets: [
    require('@acmecorp/base-tailwind-config')
  ],

  // Project-specific customizations
  theme: {
    //...
  },
  // ...
}

查看预设文档了解更多关于预设的信息。

前缀

prefix 选项允许您为所有 Tailwind 生成的功能类添加一个自定义前缀。当 Tailwind 和一个已有的 CSS 存在命名冲突时，这个功能会非常有用。

例如，您可以通过这样设置来添加 tw- 前缀：

// tailwind.config.js
module.exports = {
  prefix: 'tw-',
}

现在，将使用配置的前缀生成每个类。

.tw-text-left {
  text-align: left;
}
.tw-text-center {
  text-align: center;
}
.tw-text-right {
  text-align: right;
}
/* etc. */

请一定要理解，这个前缀是在任何变体前缀之后添加的。这意味着，带有响应式或者状态前缀（如 sm: or hover:）的类仍然会最先出现，自定义前缀要写在冒号后面。

<div class="tw-text-lg md:tw-text-xl tw-bg-red-500 hover:tw-bg-blue-500">
  <!-- -->
</div>

前缀仅会被添加到 Tailwind 生成的类中；您自己的自定义类中将不会被添加前缀。

这意味着，如果您像这样添加自己的响应式功能类：

@variants hover {
  .bg-brand-gradient { /* ... */ }
}

… 生成的响应式类将不会带有您配置的前缀：

.bg-brand-gradient { /* ... */ }
.hover\:bg-brand-gradient:hover { /* ... */ }

如果您也想给您自己的功能类添加前缀，只需要把前缀添加到类定义中即可：

@variants hover {
  .tw-bg-brand-gradient { /* ... */ }
}

Important

important 选项允许您控制是否将 Tailwind 的功能类标记为 !important。当您将 Tailwind 与已存在的具有非常特殊的选择器的 CSS 一起使用时，这可能会非常有用。

要生成 !important 的功能类，在您的配置选项中把 important 键设置为 true：

// tailwind.config.js
module.exports = {
  important: true,
}

现在，所有的 Tailwind 功能类都将被生成 !important：

.leading-none {
  line-height: 1 !important;
}
.leading-tight {
  line-height: 1.25 !important;
}
.leading-snug {
  line-height: 1.375 !important;
}
/* etc. */

注意：启用此选项不会将您的任何自定义功能类标记为 !important。

如果您想把自己的功能也标记为 !important，只需要自己在每个声明末尾添加 !important：

@responsive {
  .bg-brand-gradient {
    background-image: linear-gradient(#3490dc, #6574cd) !important;
  }
}

选择器策略

在合并第三方 JS 库且这些库会为您的元素添加内联样式的时候，设置 important 为 true 会引入一些问题。在这种情况下，Tailwind 的 !important 功能会覆盖内联样式，这会破坏您的预期设计。

为了解决这个问题，您可以为一个 ID 选择器设置 important，比如 #app：

// tailwind.config.js
module.exports = {
  important: '#app',
}

这个配置将在您所有的功能类前加上给定的选择器，有效地增加它们的特殊性，而实际上并没有使它们变得 !important。

当您指定了 important 选择器后，您需要确保您的网站的根元素与之匹配。使用上面的例子，我们需要将根元素的 id 属性设置为 app，以使样式正常工作。

当您的配置都设置好，且您的根元素与 Tailwind 配置中的选择器相匹配后，Tailwind 的所有功能类将有足够高的特异性来击败您的项目中使用的其他类，但并不干扰内联样式。

<html>
<!-- ... -->
<style>
  .high-specificity .nested .selector {
    color: blue;
  }
</style>
<body id="app">
  <div class="high-specificity">
    <div class="nested">
      <!-- Will be red-500 -->
      <div class="selector text-red-500"><!-- ... --></div>
    </div>
  </div>

  <!-- Will be #bada55 -->
  <div class="text-red-500" style="color: #bada55;"><!-- ... --></div>
</body>
</html>

When using the selector strategy, be sure that the template file that includes your root selector is included in your purge configuration, otherwise all of your CSS will be removed when building for production.

分隔符

separator 选项可以让您自定义应该使用什么字符或字符串来分隔变体前缀（屏幕大小、hover、focus等）和类名（text-center、items-end等）。

我们默认使用冒号(:)，但是如果您使用的是像 Pug 这样的模板语言，不支持在类名中使用特殊字符，那么改变这个冒号就会很有用。

// tailwind.config.js
module.exports = {
  separator: '_',
}

变体顺序

如果您使用 extend 功能启用额外的变体，这些变体会自动排序，以遵守合理的默认变体顺序。

如果有必要，您可以在 variantOrder 键下面自定义变体顺序：

// tailwind.config.js
module.exports = {
  // ...
  variantOrder: [
    'first',
    'last',
    'odd',
    'even',
    'visited',
    'checked',
    'group-hover',
    'group-focus',
    'focus-within',
    'hover',
    'focus',
    'focus-visible',
    'active',
    'disabled',
  ]
}

核心插件

corePlugins 部分允许您完全禁用掉那些 Tailwind 默认生成的类，如果您的项目不需要。

如果您没有提供任何 corePlugins 配置，则默认情况下将启用所有的核心插件。

// tailwind.config.js
module.exports = {
  // ...
}

如果您想禁用特定的核心插件，为 corePlugins 提供一个对象，将这些插件设置为false。

// tailwind.config.js
module.exports = {
  corePlugins: {
    float: false,
    objectFit: false,
    objectPosition: false,
  }
}

如果您想安全地列出哪些核心插件应该被启用，请提供一个数组，其中包括您想使用的核心插件的列表。

// tailwind.config.js
module.exports = {
  corePlugins: [
    'margin',
    'padding',
    'backgroundColor',
    // ...
  ]
}

如果您想禁用所有 Tailwind 的核心插件，并简单地使用 Tailwind 作为处理您自己的自定义插件的工具，那么只需提供一个空数组。

// tailwind.config.js
module.exports = {
  corePlugins: []
}

下面是每个核心插件的列表，供参考：

Core Plugin	Description
`preflight`	Tailwind's base/reset styles
`container`	The `container` component
`accessibility`	The `sr-only` and `not-sr-only` utilities
`alignContent`	The `align-content` utilities like `content-end`
`alignItems`	The `align-items` utilities like `items-center`
`alignSelf`	The `align-self` utilities like `self-end`
`animation`	The `animation` utilities like
`appearance`	The `appearance` utilities like `appearance-none`
`backdropBlur`	The `backdrop-blur` utilities like
`backdropBrightness`	The `backdrop-brightness` utilities like
`backdropContrast`	The `backdrop-contrast` utilities like
`backdropFilter`	The `backdrop-filter` utilities like `backdrop-filter`
`backdropGrayscale`	The `backdrop-grayscale` utilities like
`backdropHueRotate`	The `backdrop-hue-rotate` utilities like
`backdropInvert`	The `backdrop-invert` utilities like
`backdropOpacity`	The `backdrop-opacity` utilities like
`backdropSaturate`	The `backdrop-saturate` utilities like
`backdropSepia`	The `backdrop-sepia` utilities like
`backgroundAttachment`	The `background-attachment` utilities like `bg-local`
`backgroundBlendMode`	The `background-blend-mode` utilities like `bg-blend-color-burn`
`backgroundClip`	The `background-clip` utilities like `bg-clip-padding`
`backgroundColor`	The `background-color` utilities like
`backgroundImage`	The `background-image` utilities like
`backgroundOpacity`	The `background-color` opacity utilities like `bg-opacity-25`
`backgroundOrigin`	The `background-origin` utilities like `bg-origin-padding`
`backgroundPosition`	The `background-position` utilities like
`backgroundRepeat`	The `background-repeat` utilities like `bg-repeat-x`
`backgroundSize`	The `background-size` utilities like
`blur`	The `blur` utilities like
`borderCollapse`	The `border-collapse` utilities like `border-collapse`
`borderColor`	The `border-color` utilities like
`borderOpacity`	The `border-color` opacity utilities like `border-opacity-25`
`borderRadius`	The `border-radius` utilities like
`borderStyle`	The `border-style` utilities like `border-dotted`
`borderWidth`	The `border-width` utilities like
`boxDecorationBreak`	The `box-decoration-break` utilities like `decoration-slice`
`boxShadow`	The `box-shadow` utilities like `,`
`boxSizing`	The `box-sizing` utilities like `box-border`
`brightness`	The `brightness` utilities like
`caretColor`	The `caret-color` utilities like
`clear`	The `clear` utilities like `clear-right`
`content`	The `content` utilities like
`contrast`	The `contrast` utilities like
`cursor`	The `cursor` utilities like
`display`	The `display` utilities like `table-column-group`
`divideColor`	The between elements `border-color` utilities like `divide-gray-500`
`divideOpacity`	The `divide-opacity` utilities like
`divideStyle`	The `divide-style` utilities like `divide-dotted`
`divideWidth`	The between elements `border-width` utilities like `divide-x-2`
`dropShadow`	The `drop-shadow` utilities like `drop-shadow-lg`
`fill`	The `fill` utilities like
`filter`	The `filter` utilities like `filter`
`flex`	The `flex` utilities like
`flexDirection`	The `flex-direction` utilities like `flex-row-reverse`
`flexGrow`	The `flex-grow` utilities like
`flexShrink`	The `flex-shrink` utilities like
`flexWrap`	The `flex-wrap` utilities like `flex-wrap-reverse`
`float`	The `float` utilities like `float-left`
`fontFamily`	The `font-family` utilities like
`fontSize`	The `font-size` utilities like
`fontSmoothing`	The `font-smoothing` utilities like `antialiased`
`fontStyle`	The `font-style` utilities like `italic`
`fontVariantNumeric`	The `font-variant-numeric` utilities like `lining-nums`
`fontWeight`	The `font-weight` utilities like
`gap`	The `gap` utilities like
`gradientColorStops`	The `gradient-color-stops` utilities like
`grayscale`	The `grayscale` utilities like
`gridAutoColumns`	The `grid-auto-columns` utilities like
`gridAutoFlow`	The `grid-auto-flow` utilities like `grid-flow-col`
`gridAutoRows`	The `grid-auto-rows` utilities like
`gridColumn`	The `grid-column` utilities like
`gridColumnEnd`	The `grid-column-end` utilities like
`gridColumnStart`	The `grid-column-start` utilities like
`gridRow`	The `grid-row` utilities like
`gridRowEnd`	The `grid-row-end` utilities like
`gridRowStart`	The `grid-row-start` utilities like
`gridTemplateColumns`	The `grid-template-columns` utilities like
`gridTemplateRows`	The `grid-template-rows` utilities like
`height`	The `height` utilities like
`hueRotate`	The `hue-rotate` utilities like
`inset`	The `inset` utilities like
`invert`	The `invert` utilities like
`isolation`	The `isolation` utilities like `isolate`
`justifyContent`	The `justify-content` utilities like `justify-center`
`justifyItems`	The `justify-items` utilities like `justify-items-end`
`justifySelf`	The `justify-self` utilities like `justify-self-end`
`letterSpacing`	The `letter-spacing` utilities like
`lineHeight`	The `line-height` utilities like
`listStylePosition`	The `list-style-position` utilities like `list-inside`
`listStyleType`	The `list-style-type` utilities like
`margin`	The `margin` utilities like
`maxHeight`	The `max-height` utilities like
`maxWidth`	The `max-width` utilities like
`minHeight`	The `min-height` utilities like
`minWidth`	The `min-width` utilities like
`mixBlendMode`	The `mix-blend-mode` utilities like `mix-blend-color-burn`
`objectFit`	The `object-fit` utilities like `object-fill`
`objectPosition`	The `object-position` utilities like
`opacity`	The `opacity` utilities like
`order`	The `order` utilities like
`outline`	The `outline` utilities like
`overflow`	The `overflow` utilities like `overflow-y-auto`
`overscrollBehavior`	The `overscroll-behavior` utilities like `overscroll-y-contain`
`padding`	The `padding` utilities like
`placeContent`	The `place-content` utilities like `place-content-between`
`placeholderColor`	The placeholder `color` utilities like `placeholder-red-600`
`placeholderOpacity`	The placeholder `color` opacity utilities like `placeholder-opacity-25`
`placeItems`	The `place-items` utilities like `place-items-end`
`placeSelf`	The `place-self` utilities like `place-self-end`
`pointerEvents`	The `pointer-events` utilities like `pointer-events-none`
`position`	The `position` utilities like `absolute`
`resize`	The `resize` utilities like `resize-y`
`ringColor`	The `ring-color` utilities like
`ringOffsetColor`	The `ring-offset-color` utilities like
`ringOffsetWidth`	The `ring-offset-width` utilities like
`ringOpacity`	The `ring-opacity` utilities like
`ringWidth`	The `ring-width` utilities like `,`
`rotate`	The `rotate` utilities like
`saturate`	The `saturate` utilities like
`scale`	The `scale` utilities like
`sepia`	The `sepia` utilities like
`skew`	The `skew` utilities like
`space`	The "space-between" utilities like `space-x-4`
`stroke`	The `stroke` utilities like
`strokeWidth`	The `stroke-width` utilities like
`tableLayout`	The `table-layout` utilities like `table-auto`
`textAlign`	The `text-align` utilities like `text-center`
`textColor`	The `text-color` utilities like
`textDecoration`	The `text-decoration` utilities like `line-through`
`textOpacity`	The `text-opacity` utilities like
`textOverflow`	The `text-overflow` utilities like `overflow-ellipsis`
`textTransform`	The `text-transform` utilities like `lowercase`
`transform`	The `transform` utility (for enabling transform features)
`transformOrigin`	The `transform-origin` utilities like
`transitionDelay`	The `transition-delay` utilities like
`transitionDuration`	The `transition-duration` utilities like
`transitionProperty`	The `transition-property` utilities like
`transitionTimingFunction`	The `transition-timing-function` utilities like
`translate`	The `translate` utilities like
`userSelect`	The `user-select` utilities like `select-text`
`verticalAlign`	The `vertical-align` utilities like `align-middle`
`visibility`	The `visibility` utilities like `visible`
`whitespace`	The `whitespace` utilities like `whitespace-pre`
`width`	The `width` utilities like
`wordBreak`	The `word-break` utilities like `break-words`
`zIndex`	The `z-index` utilities like

在 JavaScript 中引用

在您的客户端 JavaScript 中引用配置的值往往非常有用。例如，在 React 或者 Vue 组件中动态应用内联样式的时候需要获取您的主题的配置值。

为了简化此操作，Tailwind 提供了一个 resolveConfig 助手函数，可以用来生成一个配置对象的完全合并的版本：

import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from './tailwind.config.js'

const fullConfig = resolveConfig(tailwindConfig)

fullConfig.theme.width[4]
// => '1rem'

fullConfig.theme.screens.md
// => '768px'

fullConfig.theme.boxShadow['2xl']
// => '0 25px 50px -12px rgba(0, 0, 0, 0.25)'

Note that this will transitively pull in a lot of our build-time dependencies, resulting in bigger bundle client-side size. To avoid this, we recommend using a tool like babel-plugin-preval to generate a static version of your configuration at build-time.

配置