Tailwind CSS - 插件

Tailwind CSS 插件允许使用可复用的第三方插件扩展 Tailwind。插件允许您使用 JavaScript 代码(而非常规 CSS 代码)向 Tailwind 添加新样式。

要创建您的第一个插件，您需要做两件事:

• 导入插件函数: 通过在 Tailwind CSS 配置文件中添加 import { plugin } from 'tailwindcss/plugin' 即可完成。
• 将您的插件添加到插件数组: 您可以通过在插件数组中调用插件函数来执行此操作。在插件函数中，您将编写插件的代码。

const plugin = require('tailwindcss/plugin')

module.exports = {
    plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
        // Add your custom styles here
    }),
    ]
}

插件函数设计得非常灵活。它们接受单个对象作为输入，然后可以将其分解为多个辅助函数，以便于处理。

• addUtilities() 用于注册新的静态实用样式。
• ma​​tchUtilities() 用于注册新的动态实用样式。
• addComponents() 用于注册新的静态组件样式。
• ma​​tchComponents() 用于注册新的动态组件样式。
• addBase() 用于注册新的基础样式。
• addVariant() 用于注册自定义静态变体。
• ma​​tchVariant() 用于注册自定义动态变体。
• theme() 用于在用户主题配置中查找值。
• config() 用于在用户的 Tailwind 配置中查找值。
• corePlugins() 用于检查核心插件是否已启用。
• e() 用于手动转义类名中使用的字符串。

官方插件

Tailwind CSS 有一些官方插件，用于实现核心库中尚未包含的功能。这些插件可以使用 npm 安装，然后添加到 tailwind.config.js 文件中。

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/container-queries'),
  ]
}

排版

Tailwind CSS 排版插件可让您轻松为内容中的文本添加样式。它提供预置的类，可从 Markdown 或 CMS 数据库等位置为内容添加时尚的排版，让您的文本轻松呈现美观效果。

<article class="prose lg:prose-xl">
  <h1>
    Garlic bread with cheese: 
    What the science tells us
  </h1>
  <p>
    For years parents have espoused the health
    benefits of eating garlic bread with cheese to their
    children, with the food earning such an iconic status
    in our culture that kids will often dress
    up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer
    may be linked to a series of rabies cases
    springing up around the country.
  </p>
  <!-- ... -->
</article>

表单

@tailwindcss/forms 插件通过提供一组默认样式，简化了表单的样式设置。这使得创建外观一致的表单更加简单。

宽高比

@tailwindcss/aspect-ratio 插件提供了一种在旧版浏览器中为元素设置宽高比的方法，这些浏览器本身不支持此功能。它添加了新的实用程序类，例如aspect-w-*和aspect-h-*，用于控制元素的宽高比。

容器查询

"@tailwindcss/container-queries"插件允许您使用"@container"指令，根据元素父容器的大小来设置元素的样式。

<div class="@container">
  <div class="@lg:text-sky-400">
     <!-- ... -->
  </div>
</div>

添加实用程序

addUtilities 和 ma​​tchUtilities 函数允许您向 Tailwind CSS 添加自定义样式，就像默认样式一样。但是，这些自定义样式只有在您实际在项目中使用时才会包含在最终的 CSS 中。

静态实用程序

函数用于添加简单、不变的样式(实用程序)，这些样式不支持用户提供的值

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      addUtilities({
        '.content-auto': {
          'content-visibility': 'auto',
        },
        '.content-hidden': {
          'content-visibility': 'hidden',
        },
        '.content-visible': {
          'content-visibility': 'visible',
        },
      })
    })
  ]
}

动态实用程序

"matchUtilities"函数允许您创建使用"主题"配置中值的 CSS 实用程序类。

const plugin = require('tailwindcss/plugin')

module.exports = {
    theme: {
    tabSize: {
        1: '1',
        2: '2',
        4: '4',
        8: '8',
    }
    },
    plugins: [
    plugin(function({ matchUtilities, theme }) {
        matchUtilities(
        {
            tab: (value) => ({
            tabSize: value
            }),
        },
        { values: theme('tabSize') }
        )
    })
    ]
}

您可以在实用程序中使用自定义值，即使它们未在"主题"中定义，也可以通过使用方括号来使用它们。

<div class="tab-[13]">
   <!-- ... -->
</div>

前缀和重要性

插件的工具会自动使用用户的设置，例如"前缀"和"重要"选项。

这意味着给定以下 Tailwind 配置:

/** @type {import('tailwindcss').Config} */
module.exports = {
    prefix: 'tw-',
    important: true,
    // ...
}

上面的示例插件将生成以下 CSS:

.tw-content-auto {
    content-visibility: auto !important;
    }
    .tw-content-hidden {
    content-visibility: hidden !important;
    }
    .tw-content-visible {
    content-visibility: visible !important;
    }

使用修饰符

使用 addUtilities 添加的任何自定义实用程序都可以与其他实用程序类(例如悬停、焦点等)组合使用。

<div class="content-auto lg:content-visible">
<!-- ... -->
</div>

提供默认值

实用程序插件可以通过将配置对象作为插件函数的第二个参数来设置默认值。这些默认值的行为与原始默认设置相同，用户可以更改或添加。

const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ matchUtilities, theme }) {
    matchUtilities(
    {
        tab: (value) => ({
        tabSize: value
        }),
    },
    { values: theme('tabSize') }
    )
}, {
    theme: {
    tabSize: {
        1: '1',
        2: '2',
        4: '4',
        8: '8',
    }
    }
})

添加组件

Tailwind CSS 中的"addComponents"函数允许您创建自定义的预设计组件，例如按钮、表单、警报等。这些组件就像积木一样，您可以在设计中使用，并且可以根据需要使用其他 Tailwind 类修改它们的外观。

要从插件添加新的组件样式，请调用 addComponents，并使用 CSS-in-JS 语法传入您的样式:

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      addComponents({
        '.btn': {
          padding: '.5rem 1rem',
          borderRadius: '.25rem',
          fontWeight: '600',
        },
        '.btn-blue': {
          backgroundColor: '#3490dc',
          color: '#fff',
          '&:hover': {
            backgroundColor: '#2779bd'
          },
        },
        '.btn-red': {
          backgroundColor: '#e3342f',
          color: '#fff',
          '&:hover': {
            backgroundColor: '#cc1f1a'
          },
        },
      })
    })
  ]
}

前缀和重要性

默认情况下，组件类会遵循用户的前缀偏好设置，但会忽略其"重要"偏好设置。

这意味着给定以下 Tailwind 配置:

/** @type {import('tailwindcss').Config} */
module.exports = {
    prefix: 'tw-',
    important: true,
    // ...
}

上面的示例插件将生成以下 CSS:

.tw-btn {
    padding: .5rem 1rem;
    border-radius: .25rem;
    font-weight: 600;
    }
    .tw-btn-blue {
    background-color: #3490dc;
    color: #fff;
    }
    .tw-btn-blue:hover {
    background-color: #2779bd;
    }
    .tw-btn-red {
    background-color: #e3342f;
    color: #fff;
    }
    .tw-btn-red:hover {
    background-color: #cc1f1a;
    }

通常情况下，将组件声明设置为重要不是一个好主意。但是，如果您确实需要这样做，可以手动添加 '!important' 关键字。

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      addComponents({
        '.btn': {
          padding: '.5rem 1rem !important',
          borderRadius: '.25rem !important',
          fontWeight: '600 !important',
        },
        // ...
      })
    })
  ]
}

选择器中的所有类都会默认添加前缀，因此如果您添加更复杂的样式，例如:

const plugin = require('tailwindcss/plugin')

module.exports = {
    prefix: 'tw-',
    plugins: [
    plugin(function({ addComponents }) {
        const components = {
        // ...
        '.navbar-inverse a.nav-link': {
            color: '#fff',
        }
        }

        addComponents(components)
    })
    ]
}

将生成以下 CSS:

.tw-navbar-inverse a.tw-nav-link {
    color: #fff;
}

使用修饰符

使用 addUtilities 添加的任何自定义实用程序都可以与其他实用程序类(例如 hover、focus 等)组合使用。

<div class="btn md:btn-lg">
<!-- ... -->
</div>

添加基本样式

Tailwind CSS 中的 addBase 函数允许您添加全局应用于整个项目的基本样式。这非常适合设置默认字体样式、重置浏览器默认设置或定义自定义字体等。

要从插件添加新的基本样式，请调用 addBase，并使用 CSS-in-JS 语法传入样式:

const plugin = require('tailwindcss/plugin')

module.exports = {
    plugins: [
    plugin(function({ addBase, theme }) {
        addBase({
        'h1': { fontSize: theme('fontSize.2xl') },
        'h2': { fontSize: theme('fontSize.xl') },
        'h3': { fontSize: theme('fontSize.lg') },
        })
    })
    ]
}

添加变体

"addVariant"和"matchVariant"函数允许您创建自定义修饰符，其使用方式与内置变体(例如悬停、焦点或支持)相同。

静态变体

使用 addVariant 函数创建简单的自定义变体。请提供自定义变体的名称以及描述如何修改选择器的格式字符串。

const plugin = require('tailwindcss/plugin')

module.exports = {
    // ...
    plugins: [
    plugin(function({ addVariant }) {
        addVariant('optional', '&:optional')
        addVariant('hocus', ['&:hover', '&:focus'])
        addVariant('inverted-colors', '@media (inverted-colors: inverted)')
    })
    ]
}

第一个参数是用户将在 HTML 中使用的修饰符名称，因此上面的示例可以编写如下类:

<form class="flex inverted-colors:outline ...">
<input class="optional:border-gray-300 ..." />
<button class="bg-blue-500 hocus:bg-blue-600">...</button>
</form>

动态变体

matchVariant 函数允许您创建自定义参数化变体，类似于内置变体，例如 supporting-*、data-* 和 aria-*。

const plugin = require('tailwindcss/plugin')

module.exports = {
    plugins: [
    plugin(function({ matchVariant }) {
        matchVariant(
        'nth',
        (value) => {
            return `&:nth-child(${value})`;
        },
        {
            values: {
            1: '1',
            2: '2',
            3: '3',
            }
        }
        );
    })
    ]
}

使用 matchVariant 定义的变体还支持使用方括号表示法的任意值:

<div class="nth-[3n+1]:bg-blue-500 ...">
  <!-- ... -->
</div>

如果需要，使用 sort 选项来控制生成的 CSS 的源顺序，以避免与来自同一变体的其他值的优先级问题:

matchVariant("min", (value) => `@media (min-width: ${value})`, {
    sort(a, z) {
        return parseInt(a.value) - parseInt(z.value);
    },
    });

父级和同级状态

Tailwind 的特殊功能(例如 group-* 和 peer-*)无法自动与自定义修饰符配合使用。要使它们正常工作，您需要使用 :merge 将自定义修饰符注册为单独的变体。这可确保 group 和 peer 类在最终样式表中仅出现一次，从而确保正确应用。

const plugin = require('tailwindcss/plugin')

module.exports = {
    // ...
    plugins: [
    plugin(function({ addVariant }) {
        addVariant('optional', '&:optional')addComponents([
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
])
        addVariant('group-optional', ':merge(.group):optional &')
        addVariant('peer-optional', ':merge(.peer):optional ~ &')
    })
    ]
}

扩展配置

插件可以通过向插件函数提供一个对象作为第二个参数，将自己的设置添加到用户的"tailwind.config.js"文件中。

const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      tab: (value) => ({
        tabSize: value
      }),
    },
    { values: theme('tabSize') }
  )
}, {
  theme: {
    tabSize: {
      1: '1',
      2: '2',
      4: '4',
      8: '8',
    }
  }
})

Exposing 选项

plugin.withOptions API 允许您使用自定义配置对象配置插件。这使用户能够以不直接与主题设置相关的方式调整插件的行为。例如，您可以使用此 API 让用户指定插件使用的类名。该 API 的工作原理与常规插件 API 类似，但您不是直接传递值，而是定义函数来获取用户的配置选项并返回插件的相应值。

const plugin = require('tailwindcss/plugin')

module.exports = plugin.withOptions(function (options = {}) {
  return function({ addComponents }) {
    const className = options.className ?? 'markdown'

    addComponents({
      [`.${className}`]: {
        // ...
      }
    })
  }
}, function (options) {
  return {
    theme: {
      markdown: {
        // ...
      }
    },
  }
})

用户将调用您的插件，并在其插件配置中注册时传递他们的选项:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('./plugins/markdown.js')({
      className: 'wysiwyg'
    })
  ],
}

如果用户不需要传递任何自定义选项，他们也可以正常注册以这种方式创建的插件而不调用它们:

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('./plugins/markdown.js')
  ],
}

CSS-in-JS 语法

Tailwind 的插件系统使用 JavaScript 对象编写 CSS 规则，类似于 Emotion 等 CSS-in-JS 库的方式。它在底层使用了 postcss-js。

考虑一下这条简单的 CSS 规则:

.card {
    background-color: #fff;
    border-radius: .25rem;
    box-shadow: 0 2px 4px rgba(0,0,0,0.2);
    }

将其转换为 CSS-in-JS 对象如下所示:

addComponents({
    '.card': {
        'background-color': '#fff',
        'border-radius': '.25rem',
        'box-shadow': '0 2px 4px rgba(0,0,0,0.2)',
    }
    })

还支持嵌套(由 postcss-nested 提供支持)，使用您可能熟悉的 Sass 或 Less 的相同语法:

addComponents({
    '.card': {
        backgroundColor: '#fff',
        borderRadius: '.25rem',
        boxShadow: '0 2px 4px rgba(0,0,0,0.2)',
        '&:hover': {
        boxShadow: '0 10px 15px rgba(0,0,0,0.2)',
        },
        '@media (min-width: 500px)': {
        borderRadius: '.5rem',
        }
    }
    })

可以在同一个对象中定义多个规则:

addComponents({
    '.btn': {
        padding: '.5rem 1rem',
        borderRadius: '.25rem',
        fontWeight: '600',
    },
    '.btn-blue': {
        backgroundColor: '#3490dc',
        color: '#fff',
        '&:hover': {
        backgroundColor: '#2779bd'
        },
    },
    '.btn-red': {
        backgroundColor: '#e3342f',
        color: '#fff',
        '&:hover': {
        backgroundColor: '#cc1f1a'
        },
    },
    })

或者作为对象数组，以防您需要重复相同的键:

addComponents([
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
])