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: []
}

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

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