Tailwind CSS on GitHub

主题配置

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

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

我们提供了一个合理的 默认主题,并提供了一套非常通用的值来让您开始使用,但不要害怕改变或扩展;我们鼓励您根据您的设计目标来定制它。


主题结构

theme 对象包含 screenscolorsspacing 的键,以及每一个可定制的核心插件的键。

请参阅 主题配置参考默认主题 获取完整的主题选项列表。

屏幕

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

      // ...
    }
  }
}

默认情况下,这些颜色会被所有与颜色相关的核心插件继承,比如 backgroundColorborderColortextColor 等。

要了解更多信息,请参见 颜色自定义文档

间距

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

默认情况下,这些值会被 paddingmarginwidthheightmaxHeightgapinsetspace以及 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 对象,它可以被 backgroundPositionobjectPosition 插件引用。

// 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')
  ],
}

由于整个 theme 对象可以通过theme 函数 在您的 CSS 中使用,您也可以添加一个键来在您的 CSS 中引用它。

配置参考

除了 screenscolorsspacingtheme 对象中的所有的键都映射到 Tailwind 的一个 核心插件。由于许多插件负责的 CSS 属性只接受一组静态的值(例如 float),所以请注意,不是每个插件在 theme 对象中都有一个对应的键。

所有这些键在 theme.extend 键下也是可用的,用来启用 扩展默认主题

KeyDescription
screensYour project's responsive breakpoints
colorsYour project's color palette
spacingYour project's spacing scale
animationValues for the animation property
backgroundColorValues for the background-color property
backgroundImageValues for the background-image property
backgroundOpacityValues for the background-opacity property
backgroundPositionValues for the background-position property
backgroundSizeValues for the background-size property
borderColorValues for the border-color property
borderOpacityValues for the border-opacity property
borderRadiusValues for the border-radius property
borderWidthValues for the border-width property
boxShadowValues for the box-shadow property
containerConfiguration for the container plugin
cursorValues for the cursor property
divideColorValues for the divide-color property
divideOpacityValues for the divide-opacity property
divideWidthValues for the divide-width property
fillValues for the fill property
flexValues for the flex property
flexGrowValues for the flex-grow property
flexShrinkValues for the flex-shrink property
fontFamilyValues for the font-family property
fontSizeValues for the font-size property
fontWeightValues for the font-weight property
gapValues for the gap property
gradientColorStopsValues for the gradient-color-stops property
gridAutoColumnsValues for the grid-auto-columns property
gridAutoRowsValues for the grid-auto-rows property
gridColumnValues for the grid-column property
gridColumnEndValues for the grid-column-end property
gridColumnStartValues for the grid-column-start property
gridRowValues for the grid-row property
gridRowStartValues for the grid-row-start property
gridRowEndValues for the grid-row-end property
transformOriginValues for the transform-origin property
gridTemplateColumnsValues for the grid-template-columns property
gridTemplateRowsValues for the grid-template-rows property
heightValues for the height property
insetValues for the top, right, bottom, and left properties
keyframesValues for the keyframes property
letterSpacingValues for the letter-spacing property
lineHeightValues for the line-height property
listStyleTypeValues for the list-style-type property
marginValues for the margin property
maxHeightValues for the max-height property
maxWidthValues for the max-width property
minHeightValues for the min-height property
minWidthValues for the min-width property
objectPositionValues for the object-position property
opacityValues for the opacity property
orderValues for the order property
outlineValues for the outline property
paddingValues for the padding property
placeholderColorValues for the placeholderColor plugin
placeholderOpacityValues for the placeholderOpacity plugin
ringColorValues for the ring-color property
ringOffsetColorValues for the ring-offset-color property
ringOffsetWidthValues for the ring-offset-width property
ringOpacityValues for the ring-opacity property
ringWidthValues for the ring-width property
rotateValues for the rotate plugin
scaleValues for the scale plugin
skewValues for the skew plugin
spaceValues for the space plugin
strokeValues for the stroke property
strokeWidthValues for the stroke-width property
textColorValues for the text-color property
textOpacityValues for the textOpacity plugin
transitionDurationValues for the transition-duration property
transitionDelayValues for the transition-delay property
transitionPropertyValues for the transition-property property
transitionTimingFunctionValues for the transition-timing-function property
translateValues for the translate plugin
widthValues for the width property
zIndexValues for the z-index property