Just-in-Time: The Next Generation of Tailwind CSS
Tailwind CSS on GitHub

配置

配置和定制 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 库且这些库会为您的元素添加内联样式的时候,设置 importanttrue 会引入一些问题。在这种情况下,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 选项可以让您自定义应该使用什么字符或字符串来分隔变体前缀(屏幕大小、hoverfocus等)和类名(text-centeritems-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 PluginDescription
preflightTailwind's base/reset styles
containerThe container component
accessibilityThe sr-only and not-sr-only utilities
alignContentThe align-content utilities like content-end
alignItemsThe align-items utilities like items-center
alignSelfThe align-self utilities like self-end
animationThe animation utilities like
appearanceThe appearance utilities like appearance-none
backdropBlurThe backdrop-blur utilities like
backdropBrightnessThe backdrop-brightness utilities like
backdropContrastThe backdrop-contrast utilities like
backdropFilterThe backdrop-filter utilities like backdrop-filter
backdropGrayscaleThe backdrop-grayscale utilities like
backdropHueRotateThe backdrop-hue-rotate utilities like
backdropInvertThe backdrop-invert utilities like
backdropOpacityThe backdrop-opacity utilities like
backdropSaturateThe backdrop-saturate utilities like
backdropSepiaThe backdrop-sepia utilities like
backgroundAttachmentThe background-attachment utilities like bg-local
backgroundBlendModeThe background-blend-mode utilities like bg-blend-color-burn
backgroundClipThe background-clip utilities like bg-clip-padding
backgroundColorThe background-color utilities like
backgroundImageThe background-image utilities like
backgroundOpacityThe background-color opacity utilities like bg-opacity-25
backgroundOriginThe background-origin utilities like bg-origin-padding
backgroundPositionThe background-position utilities like
backgroundRepeatThe background-repeat utilities like bg-repeat-x
backgroundSizeThe background-size utilities like
blurThe blur utilities like
borderCollapseThe border-collapse utilities like border-collapse
borderColorThe border-color utilities like
borderOpacityThe border-color opacity utilities like border-opacity-25
borderRadiusThe border-radius utilities like
borderStyleThe border-style utilities like border-dotted
borderWidthThe border-width utilities like
boxDecorationBreakThe box-decoration-break utilities like decoration-slice
boxShadowThe box-shadow utilities like ,
boxSizingThe box-sizing utilities like box-border
brightnessThe brightness utilities like
caretColorThe caret-color utilities like
clearThe clear utilities like clear-right
contentThe content utilities like
contrastThe contrast utilities like
cursorThe cursor utilities like
displayThe display utilities like table-column-group
divideColorThe between elements border-color utilities like divide-gray-500
divideOpacityThe divide-opacity utilities like
divideStyleThe divide-style utilities like divide-dotted
divideWidthThe between elements border-width utilities like divide-x-2
dropShadowThe drop-shadow utilities like drop-shadow-lg
fillThe fill utilities like
filterThe filter utilities like filter
flexThe flex utilities like
flexDirectionThe flex-direction utilities like flex-row-reverse
flexGrowThe flex-grow utilities like
flexShrinkThe flex-shrink utilities like
flexWrapThe flex-wrap utilities like flex-wrap-reverse
floatThe float utilities like float-left
fontFamilyThe font-family utilities like
fontSizeThe font-size utilities like
fontSmoothingThe font-smoothing utilities like antialiased
fontStyleThe font-style utilities like italic
fontVariantNumericThe font-variant-numeric utilities like lining-nums
fontWeightThe font-weight utilities like
gapThe gap utilities like
gradientColorStopsThe gradient-color-stops utilities like
grayscaleThe grayscale utilities like
gridAutoColumnsThe grid-auto-columns utilities like
gridAutoFlowThe grid-auto-flow utilities like grid-flow-col
gridAutoRowsThe grid-auto-rows utilities like
gridColumnThe grid-column utilities like
gridColumnEndThe grid-column-end utilities like
gridColumnStartThe grid-column-start utilities like
gridRowThe grid-row utilities like
gridRowEndThe grid-row-end utilities like
gridRowStartThe grid-row-start utilities like
gridTemplateColumnsThe grid-template-columns utilities like
gridTemplateRowsThe grid-template-rows utilities like
heightThe height utilities like
hueRotateThe hue-rotate utilities like
insetThe inset utilities like
invertThe invert utilities like
isolationThe isolation utilities like isolate
justifyContentThe justify-content utilities like justify-center
justifyItemsThe justify-items utilities like justify-items-end
justifySelfThe justify-self utilities like justify-self-end
letterSpacingThe letter-spacing utilities like
lineHeightThe line-height utilities like
listStylePositionThe list-style-position utilities like list-inside
listStyleTypeThe list-style-type utilities like
marginThe margin utilities like
maxHeightThe max-height utilities like
maxWidthThe max-width utilities like
minHeightThe min-height utilities like
minWidthThe min-width utilities like
mixBlendModeThe mix-blend-mode utilities like mix-blend-color-burn
objectFitThe object-fit utilities like object-fill
objectPositionThe object-position utilities like
opacityThe opacity utilities like
orderThe order utilities like
outlineThe outline utilities like
overflowThe overflow utilities like overflow-y-auto
overscrollBehaviorThe overscroll-behavior utilities like overscroll-y-contain
paddingThe padding utilities like
placeContentThe place-content utilities like place-content-between
placeholderColorThe placeholder color utilities like placeholder-red-600
placeholderOpacityThe placeholder color opacity utilities like placeholder-opacity-25
placeItemsThe place-items utilities like place-items-end
placeSelfThe place-self utilities like place-self-end
pointerEventsThe pointer-events utilities like pointer-events-none
positionThe position utilities like absolute
resizeThe resize utilities like resize-y
ringColorThe ring-color utilities like
ringOffsetColorThe ring-offset-color utilities like
ringOffsetWidthThe ring-offset-width utilities like
ringOpacityThe ring-opacity utilities like
ringWidthThe ring-width utilities like ,
rotateThe rotate utilities like
saturateThe saturate utilities like
scaleThe scale utilities like
sepiaThe sepia utilities like
skewThe skew utilities like
spaceThe "space-between" utilities like space-x-4
strokeThe stroke utilities like
strokeWidthThe stroke-width utilities like
tableLayoutThe table-layout utilities like table-auto
textAlignThe text-align utilities like text-center
textColorThe text-color utilities like
textDecorationThe text-decoration utilities like line-through
textOpacityThe text-opacity utilities like
textOverflowThe text-overflow utilities like overflow-ellipsis
textTransformThe text-transform utilities like lowercase
transformThe transform utility (for enabling transform features)
transformOriginThe transform-origin utilities like
transitionDelayThe transition-delay utilities like
transitionDurationThe transition-duration utilities like
transitionPropertyThe transition-property utilities like
transitionTimingFunctionThe transition-timing-function utilities like
translateThe translate utilities like
userSelectThe user-select utilities like select-text
verticalAlignThe vertical-align utilities like align-middle
visibilityThe visibility utilities like visible
whitespaceThe whitespace utilities like whitespace-pre
widthThe width utilities like
wordBreakThe word-break utilities like break-words
zIndexThe 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.