Tailwind CSS 配置

配置

配置和定制 Tailwind 安装的指南。

---

因为 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>

使用选择器策略时，请确保包含根选择器的模板文件包含在 purge configuration 中，否则在构建生产环境时将删除所有 CSS。

分隔符

​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)'

请注意，这将传递大量我们的构建时依赖项，从而导致更大的捆绑客户端大小。为避免这种情况，我们建议使用类似 babel-plugin-preval 的工具在构建时生成配置的静态版本。