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>

分隔符

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 animate-none
appearanceThe appearance utilities like appearance-none
backgroundAttachmentThe background-attachment utilities like bg-local
backgroundClipThe background-clip utilities like bg-clip-padding
backgroundColorThe background-color utilities like bg-green-700
backgroundImageThe background-image utilities like bg-gradient-to-br
backgroundOpacityThe background-color opacity utilities like bg-opacity-25
backgroundPositionThe background-position utilities like bg-left-top
backgroundRepeatThe background-repeat utilities like bg-repeat-x
backgroundSizeThe background-size utilities like bg-cover
borderCollapseThe border-collapse utilities like border-collapse
borderColorThe border-color utilities like border-green-700
borderOpacityThe border-color opacity utilities like border-opacity-25
borderRadiusThe border-radius utilities like rounded-l-3xl
borderStyleThe border-style utilities like border-dotted
borderWidthThe border-width utilities like border-l-2
boxShadowThe box-shadow utilities like shadow-lg
boxSizingThe box-sizing utilities like box-border
clearThe clear utilities like clear-right
cursorThe cursor utilities like cursor-wait
displayThe display utilities like table-column-group
divideColorThe between elements border-color utilities like divide-gray-500
divideOpacityThe divide-opacity utilities like divide-opacity-50
divideStyleThe divide-style utilities like divide-dotted
divideWidthThe between elements border-width utilities like divide-x-2
fillThe fill utilities like fill-current
flexThe flex utilities like flex-auto
flexDirectionThe flex-direction utilities like flex-row-reverse
flexGrowThe flex-grow utilities like flex-grow-0
flexShrinkThe flex-shrink utilities like flex-shrink-0
flexWrapThe flex-wrap utilities like flex-wrap-reverse
floatThe float utilities like float-left
fontFamilyThe font-family utilities like font-serif
fontSizeThe font-size utilities like text-3xl
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 font-medium
gapThe gap utilities like gap-x-28
gradientColorStopsThe gradient-color-stops utilities like via-green-700
gridAutoColumnsThe grid-auto-columns utilities like auto-cols-min
gridAutoFlowThe grid-auto-flow utilities like grid-flow-col
gridAutoRowsThe grid-auto-rows utilities like auto-rows-min
gridColumnThe grid-column utilities like col-span-6
gridColumnEndThe grid-column-end utilities like col-end-7
gridColumnStartThe grid-column-start utilities like col-start-7
gridRowThe grid-row utilities like row-span-3
gridRowEndThe grid-row-end utilities like row-end-4
gridRowStartThe grid-row-start utilities like row-start-4
gridTemplateColumnsThe grid-template-columns utilities like grid-cols-7
gridTemplateRowsThe grid-template-rows utilities like grid-rows-4
heightThe height utilities like h-64
insetThe inset utilities like bottom-10
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 tracking-normal
lineHeightThe line-height utilities like leading-9
listStylePositionThe list-style-position utilities like list-inside
listStyleTypeThe list-style-type utilities like list-disc
marginThe margin utilities like ml-8
maxHeightThe max-height utilities like max-h-32
maxWidthThe max-width utilities like max-w-5xl
minHeightThe min-height utilities like min-h-full
minWidthThe min-width utilities like min-w-full
objectFitThe object-fit utilities like object-fill
objectPositionThe object-position utilities like object-left-top
opacityThe opacity utilities like opacity-50
orderThe order utilities like order-8
outlineThe outline utilities like outline-white
overflowThe overflow utilities like overflow-y-auto
overscrollBehaviorThe overscroll-behavior utilities like overscroll-y-contain
paddingThe padding utilities like pr-4
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 ring-green-700
ringOffsetColorThe ring-offset-color utilities like ring-offset-green-700
ringOffsetWidthThe ring-offset-width utilities like ring-offset-2
ringOpacityThe ring-opacity utilities like ring-opacity-50
ringWidthThe ring-width utilities like ring-2
rotateThe rotate utilities like rotate-180
scaleThe scale utilities like scale-x-95
skewThe skew utilities like -skew-x-1
spaceThe "space-between" utilities like space-x-4
strokeThe stroke utilities like stroke-current
strokeWidthThe stroke-width utilities like stroke-1
tableLayoutThe table-layout utilities like table-auto
textAlignThe text-align utilities like text-center
textColorThe text-color utilities like text-green-700
textDecorationThe text-decoration utilities like line-through
textOpacityThe text-opacity utilities like text-opacity-50
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 origin-bottom-right
transitionDelayThe transition-delay utilities like delay-200
transitionDurationThe transition-duration utilities like duration-200
transitionPropertyThe transition-property utilities like transition-colors
transitionTimingFunctionThe transition-timing-function utilities like ease-in
translateThe translate utilities like -translate-x-full
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 w-0.5
wordBreakThe word-break utilities like break-words
zIndexThe z-index utilities like z-30

在 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 之类的工具在构建时生成一个配置的静态版本。