Tailwind CSS - 插件

上一页
下一页

Tailwind CSS 插件允许使用可重用的第三方插件扩展 Tailwind。插件允许你使用 JavaScript 而不是常规 CSS 代码向 Tailwind 添加新的样式。

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

  • 导入插件函数：这是通过在你的 Tailwind CSS 配置文件中添加 `import { plugin } from 'tailwindcss/plugin'` 来完成的。
  • 将你的插件添加到 plugins 数组： 你可以通过在你的 plugins 数组中调用 plugin 函数来实现这一点。在 plugin 函数内部，你将编写你的插件代码。
const plugin = require('tailwindcss/plugin')

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

插件函数的设计非常灵活。它们接受一个单一的对象作为输入，可以将其分解成多个辅助函数以简化处理。

  • addUtilities() 用于注册新的静态实用程序样式。
  • matchUtilities() 用于注册新的动态实用程序样式。
  • addComponents() 用于注册新的静态组件样式。
  • matchComponents() 用于注册新的动态组件样式。
  • addBase() 用于注册新的基础样式。
  • addVariant() 用于注册自定义静态变体。
  • matchVariant() 用于注册自定义动态变体。
  • 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 和 matchUtilities 函数允许你向 Tailwind CSS 添加自定义样式，就像默认样式一样。但是，只有当你实际在项目中使用这些自定义样式时，它们才会包含在最终 CSS 中。

静态实用程序

`addUtilities` 函数用于添加简单的、不变的样式（实用程序），不支持用户提供的值。

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` 添加的任何自定义实用程序都可以与其他实用程序类（如 `hover`、`focus` 等）组合使用。

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

前缀和重要性

默认情况下，组件类遵循用户的 `prefix` 首选项，但忽略它们的“重要”首选项。

这意味着，给定此 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` 函数允许你创建你自己的自定义修饰符，这些修饰符可以像 `hover`、`focus` 或 `supports` 等内置变体一样使用。

静态变体

使用 `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` 函数允许你创建自定义参数化变体，类似于内置变体，如 `supports-*`、`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',
    }
  }
})

公开选项

`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)': {
      // ...
    }
  },
])
打印页面
上一页
下一页
广告