集成Tailwind CSS与 Storybook

Tailwind CSS 是一个原子类优先的 CSS 框架，内置了大量的类，可以直接在你的标记中构建任何设计。

先决条件

本教程假设你有一个使用 Tailwind CSS 的 React 应用，并且刚刚使用入门指南设置了 Storybook >=7.0。还没有吗？请先按照 Tailwind 的设置说明进行配置，然后运行

# Add Storybook:
npm create storybook@latest

1. 配置 PostCSS

开始之前

Tailwind 使用 PostCSS 来编译你的 CSS。如果你正在使用

vite
@storybook/nextjs
@storybook/preset-create-react-app 配合 react-scripts@2.0.0
@storybook/angular

那么你可以跳到下一步。

对于 Webpack 用户，你需要安装 @storybook/addon-styling-webpack 插件。

运行以下脚本来安装并注册该插件

npx storybook@latest add @storybook/addon-styling-webpack

这将运行一个配置脚本，引导你完成插件的设置。如果出现提示，请从配置选项中选择 PostCSS。

配置脚本失败了吗？

该命令在后台运行 npx @storybook/auto-config styling，负责读取你的项目并尝试为你所需的工具配置 Storybook Webpack。如果直接运行该命令未能解决你的问题，请考虑在 @storybook/auto-config 仓库中提交一个 bug 报告，以便我们进一步改进。有关 PostCSS 的手动配置说明，你可以参考此处的文档。

2. 为 Story 提供 Tailwind

现在你可以将 tailwind.css 文件导入到你的 .storybook/preview.js 文件中。这将使 Tailwind 的样式类对你所有的 Story 都可用。

// .storybook/preview.js
 
import '../src/tailwind.css'; // replace with the name of your tailwind css file

2.1. Angular

如果你使用 Angular，你需要将 tailwind.css 文件添加到你的 angular.json 文件中。这将确保你的样式使用 PostCSS 处理，并注入到渲染 Story 的预览 iframe 中。

// angular.json
{
 "storybook": {
    "builder": "@storybook/angular:start-storybook",
    "options": {
      "browserTarget": "my-default-project:build",
      "styles": ["src/tailwind.css"]
    }
  } 
}

3. 添加主题切换器

Tailwind 开箱即用地提供了亮色和暗色主题。你可以覆盖这些主题并添加更多。为了充分利用你的 Story，你应该有一种切换所有主题的方式。

Finished example of Tailwind CSS in Storybook with a theme switcher

首先，更新你的 tailwind.config.js 文件，以基于类名或 data-attribute 更改主题。本示例使用 data-attribute。

// tailwind.config.js
 
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  // Toggle dark-mode based on .dark class or data-mode="dark"
  darkMode: ['class', '[data-mode="dark"]'],
  theme: {
    extend: {},
  },
  plugins: [],
};

接下来，安装 @storybook/addon-themes 插件来提供切换器工具。

运行以下脚本来安装并注册该插件

npx storybook@latest add @storybook/addon-themes

这将运行一个配置脚本，引导你完成插件的设置。

配置脚本失败了吗？

在后台，这会运行 npx @storybook/auto-config themes，它会读取您的项目并尝试使用正确的装饰器配置您的 Storybook。如果直接运行该命令不能解决您的问题，请在 @storybook/auto-config 仓库中提交 bug，以便我们进一步改进。要手动添加此插件，请先安装它，然后在您 .storybook/main.ts 的插件数组中添加它。

3.1. 通过类名切换主题

将 withThemeByClassName 装饰器添加到你的 Storybook 中，来自 @storybook/addon-themes。

// .storybook/preview.js
import { withThemeByClassName } from '@storybook/addon-themes';
 
/* snipped for brevity */
 
export const decorators = [
  withThemeByClassName({
    themes: {
      light: 'light',
      dark: 'dark',
    },
    defaultTheme: 'light',
  }),
];

3.2. 通过 data-attribute 切换主题

将 withThemeByDataAttribute 装饰器添加到你的 Storybook 中，来自 @storybook/addon-themes。

// .storybook/preview.js
import { withThemeByDataAttribute } from '@storybook/addon-themes';
 
/* snipped for brevity */
 
export const decorators = [
  withThemeByDataAttribute({
    themes: {
      light: 'light',
      dark: 'dark',
    },
    defaultTheme: 'light',
    attributeName: 'data-mode',
  }),
];

这段代码将创建一个新的工具栏菜单，用于选择你 Story 所需的主题。

参与进来

现在你已准备好在 Storybook 中使用 Tailwind 了。🎉

如果你在工作中也使用 Tailwind，我们非常希望能得到你的帮助，让这个设置变得更加容易。请加入我们在 Discord 上的社群，参与进来，或者浏览插件文档。