配置和定制 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 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' },
  },
}

如果您想在生成 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

在 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',
      }
    }
  }
}

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

!important这个属性可以让浏览器优选执行这个语句，加上!importanrt可以覆盖父级的样式。

要生成 !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>

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

如果您使用 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 中引用配置的值往往非常有用。例如，在 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)'

为您的项目定制默认主题。

在tailwind.config.js 文件的 theme 部分，您可以定义您项目的调色板、类型比例、字体、断点、边框半径值等。

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

module.exports = {
  theme: {
    screens: {
      sm: '480px',
      md: '768px',
      lg: '976px',
      xl: '1440px',
    },
    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',
      }
    }
  }
}

screens 键允许您自定义项目中的响应断点。

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      'sm': '640px',
      'md': '768px',
      'lg': '1024px',
      'xl': '1280px',
      '2xl': '1536px',
    }
  }
}

colors 键允许您为您的项目定制全局调色板。

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      black: '#000',
      white: '#fff',
      gray: {
        100: '#f7fafc',
        // ...
        900: '#1a202c',
      },

      // ...
    }
  }
}

默认情况下，这些颜色会被所有与颜色相关的核心插件继承，比如 backgroundColor、borderColor、textColor 等。

spacing 键允许您为您的项目定制全局的间距和大小比例。

// tailwind.config.js
module.exports = {
  theme: {
    spacing: {
      px: '1px',
      0: '0',
      0.5: '0.125rem',
      1: '0.25rem',
      1.5: '0.375rem',
      2: '0.5rem',
      2.5: '0.625rem',
      3: '0.75rem',
      3.5: '0.875rem',
      4: '1rem',
      5: '1.25rem',
      6: '1.5rem',
      7: '1.75rem',
      8: '2rem',
      9: '2.25rem',
      10: '2.5rem',
      11: '2.75rem',
      12: '3rem',
      14: '3.5rem',
      16: '4rem',
      20: '5rem',
      24: '6rem',
      28: '7rem',
      32: '8rem',
      36: '9rem',
      40: '10rem',
      44: '11rem',
      48: '12rem',
      52: '13rem',
      56: '14rem',
      60: '15rem',
      64: '16rem',
      72: '18rem',
      80: '20rem',
      96: '24rem',
    },
  }
}

默认情况下，这些值会被 padding、 margin、 width、 height、 maxHeight、 gap、 inset、 space以及 translate 核心插件继承。

其余的 theme 部分用于配置每个核心插件的可用值。

例如， borderRadius 键可以让您自定义将生成哪些边框半径功能类。

module.exports = {
  theme: {
    borderRadius: {
      'none': '0',
      'sm': '.125rem',
      DEFAULT: '.25rem',
      'lg': '.5rem',
      'full': '9999px',
    },
  }
}

键决定了生成类的后缀，值决定了实际 CSS 声明的值。

上面的 borderRadius 配置示例将生成以下 CSS 类：

.rounded-none { border-radius: 0 }
.rounded-sm   { border-radius: .125rem }
.rounded      { border-radius: .25rem }
.rounded-lg   { border-radius: .5rem }
.rounded-full { border-radius: 9999px }

您会注意到，在主题配置中使用 DEFAULT 键创建了一个没有后缀的 rounded 类。这是一个常见的惯例，在 Tailwind 中，所有的核心插件都支持这样的用法。

要了解更多关于定制特定核心插件的信息，请访问该插件的文档。

如果您想保留一个主题选项的默认值，但也要添加新的值，在配置文件的 theme 部分的 extend 键下添加您的扩展。

例如，如果您想增加一个额外的断点，但保留现有的断点，您可以扩展 screens 属性。

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      // Adds a new breakpoint in addition to the default breakpoints
      screens: {
        '3xl': '1600px',
      }
    }
  }
}

要覆盖默认主题中的一个选项，直接在您的 tailwind.config.js 文件的 theme部分添加您的覆盖。

// tailwind.config.js
module.exports = {
  theme: {
    // Replaces all of the default `opacity` values
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    }
  }
}

这将完全替换 Tailwind 中该键的默认配置，所以在上面的例子中，没有一个默认的透明度类将被生成。

任何您没有提供的键都将从默认主题中继承，所以在上面的例子中，默认的主题配置，如颜色，间距，边框半径，背景位置等将被保留。

当然，在同一配置下，您既可以覆盖默认主题的一部分，也可以扩展默认主题的另一部分。

// tailwind.config.js
module.exports = {
  theme: {
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    },
    extend: {
      screens: {
        '3xl': '1600px',
      }
    }
  }
}

如果您需要在您的主题中引用另一个值，您可以通过提供一个闭包而不是一个静态值来实现。该闭包将收到一个 theme() 函数，您可以使用点符号来查找您主题中的其他值。

例如，您可以通过在您的 fill 配置中引用 theme('colors') 来为您的调色板中的每一种颜色生成 fill 功能类。

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      // ...
    },
    fill: theme => theme('colors')
  }
}

theme() 函数试图从完全合并的主题对象中找到您正在寻找的值，因此它可以引用您自己的定制以及默认的主题值。它也是递归工作的，所以只要在链的最后有一个静态值，它就能解析出您要找的值。

如果您出于任何原因想在默认主题中引用一个值，您可以从 tailwindcss/defaultTheme 中导入它。

一个有用的例子是，如果您想添加一个字体家族到 Tailwind 的默认字体堆栈中：

// tailwind.config.js
const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: [
          'Lato',
          ...defaultTheme.fontFamily.sans,
        ]
      }
    }
  }
}

如果您不想为某个核心插件生成任何类，最好在您的 corePlugins 配置中把该插件设置为 false，而不是在您的 theme 配置中为该键提供一个空对象。

不要在您的主题配置中赋值一个空对象。

// tailwind.config.js
module.exports = {
  theme: {
    opacity: {},
  }
}

请在您的 corePlugins 配置中禁用该插件。

// tailwind.config.js
module.exports = {
  corePlugins: {
    opacity: false,
  }
}

最终的结果是一样的，但既然很多核心插件没有暴露配置，只能用 corePlugins 来禁用，所以最好保持一致。

在一些情况下，向 theme 对象添加自己的键是有用的。

其中一个例子是添加新的键，为多个核心插件之间的共同值创建一个单一的真实来源。例如，您可以提取一个共享的 positions 对象，它可以被 backgroundPosition 和 objectPosition 插件引用。

// tailwind.config.js
module.exports = {
  theme: {
    positions: {
      bottom: 'bottom',
      center: 'center',
      left: 'left',
      'left-bottom': 'left bottom',
      'left-top': 'left top',
      right: 'right',
      'right-bottom': 'right bottom',
      'right-top': 'right top',
      top: 'top',
    },
    backgroundPosition: theme => theme('positions'),
    objectPosition: theme => theme('positions'),
  }
}

另一个例子是在自定义插件内部添加一个新的键来引用。例如，如果您为您的项目编写了一个 filters 插件，您可以在您的 theme 对象中添加一个 filters 键，让插件引用。

// tailwind.config.js
module.exports = {
  theme: {
    filters: {
      none: 'none',
      grayscale: 'grayscale(1)',
      invert: 'invert(1)',
      sepia: 'sepia(1)',
    }
  },
  plugins: [
    require('./plugins/filters')
  ],
}