使用 Storybook 记录 React 组件 Storybook 是什么？设置 Let's Document 主题

2025-05-24

使用 Storybook 记录 React 组件

Storybook 是什么？

设置

让我们记录

主题

Storybook 是什么？

Storybook 将自己定位为 UI 组件的游乐场，其主要重点是“编写故事”。

Storybook 使用故事的概念来记录组件。

一个故事通常包含一个组件的单一状态，类似于一个可视化测试用例。从技术上讲，故事是一个返回可渲染到屏幕内容的函数。

您的组件故事书将包含许多不同组件的许多不同故事。

我们撰写的每个故事都包含一个状态，例如：

Button
  ├── primary
  ├── secondary
  └── tertiary
Enter fullscreen mode Exit fullscreen mode

Storybook 的优点在于它可以与许多流行的前端框架和库兼容，例如 React、Vue、React Native、Angular 等。

设置

在本教程中，我将 Storybook 添加到我于 2019 年 5 月在伦敦 ReactJS Girls 大会上发表的“使用 React 构建设计系统”演讲中。欢迎您使用自己的代码进行学习，或者在我的代码库中查看最终代码。

  1. 进入你的项目目录并安装依赖项（如果需要的话）。我忘了，花了十分钟才弄清楚为什么什么都没起作用……

然后，安装 Storybook 的样板文件。（下载需要一小会儿。这段时间，你或许想泡杯新鲜的咖啡。）

cd my-project
npx -p @storybook/cli sb init
Enter fullscreen mode Exit fullscreen mode

此工具将检查你的 package.json 文件，以确定你正在使用的框架或库（视图层）。如果自动检测失败，或者你想使用 Storybook for HTML，请使用以下命令：

npx -p @storybook/cli sb init --type html | <other-type>
Enter fullscreen mode Exit fullscreen mode
  1. 安装完成后，让我们使用以下命令启动 Storybook：
npm run storybook
Enter fullscreen mode Exit fullscreen mode

运行后，localhost我的浏览器中弹出一个窗口，我看到了以下屏幕：

故事书

  1. 现在，我们要将 Storybook 添加为项目中的开发依赖项。我们可以通过运行以下命令来实现：
npm install @storybook/react --save-dev
Enter fullscreen mode Exit fullscreen mode
  1. Storybook 有一些对等依赖项，我们也需要安装它们。react并且react-dom应该保存为普通依赖项。@babel/core并且babel-loader应该保存为开发依赖项。
npm install react react-dom --save
npm install babel-loader @babel/core --save-dev
Enter fullscreen mode Exit fullscreen mode
  1. 我们需要添加一个 npm 脚本，以便轻松启动 Storybook。在我们的package.json文件中，添加一个 Storybook 脚本。
{
  "scripts": {
    "storybook": "start-storybook"
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. 最后，让我们创建 Storybook 配置文件，它将简单地告诉 Storybook 我们将在哪里编写我们的故事。

您很可能已经按照前面的步骤创建了此文件，但如果没有，请在文件夹config.js内创建一个新文件storybook/。

我的config.js文件包含以下内容：

import { configure } from "@storybook/react";

function loadStories() {
  require("../src/stories");
}

configure(loadStories, module);
Enter fullscreen mode Exit fullscreen mode

这告诉 Storybook 在文件夹内查找src/stories我们的故事。

让我们记录

  1. 确保您的开发服务器正在使用 npm run storybook 运行。
  2. 首先，我们要删除 里面的样板文件src/stories/index.js。我的文件如下所示：
import React from "react";
import { storiesOf } from "@storybook/react";
import { action } from "@storybook/addon-actions";
Enter fullscreen mode Exit fullscreen mode
  1. 现在，让我们导入第一个组件。在我的项目中，我将导入 Button 组件。它直接位于 src/ 文件夹中。
import Button from '../Button';
Enter fullscreen mode Exit fullscreen mode

我使用枚举来描述我的按钮类型，所以我也会导入它们。

import { ButtonTypes } from "../buttonTypes";
Enter fullscreen mode Exit fullscreen mode
  1. 现在我们要storiesOf为按钮编写第一个状态。我们将从三个状态开始：主要状态、次要状态和第三状态。

我们需要使用.add()函数来添加每个状态。它接受两个参数：我们要添加的状态的名称和一个返回组件的函数。

我的文件如下所示index.js：

import React from "react";

import { storiesOf } from "@storybook/react";
import { action } from "@storybook/addon-actions";

import Button from "../Button";
import { ButtonTypes } from "../buttonTypes";

storiesOf("Button", module)
  .add("primary", () => (
    <Button
      type={ButtonTypes.PRIMARY}
      onClick={action("clicked")}
      label="Primary"
    />
  ))
  .add("secondary", () => (
    <Button
      type={ButtonTypes.SECONDARY}
      onClick={action("clicked")}
      label="Secondary"
    />
  ))
  .add("tertiary", () => (
    <Button
      type={ButtonTypes.TERTIARY}
      onClick={action("clicked")}
      label="Tertiary"
    />
));
Enter fullscreen mode Exit fullscreen mode

当我们在 UI 中检查这一点时，我们应该看到一个故事，按钮，具有三种状态：主要、次要和第三。

故事书

  1. 现在一切正常了，我想更好地模块化我的故事。如果我要为企业应用程序或完整的设计系统做这件事，我会把故事添加到组件旁边。但是，由于这只是一个概念验证，所以我会把它们添加到 stories/ 文件夹中。

我将buttonStories.js在里面创建一个文件src/stories/。

接下来，我将把文件中的所有代码复制并粘贴index.js到这个新文件中。

最后，我将更新index.js以导入buttonStories.js文件。

import "./buttonStories";
Enter fullscreen mode Exit fullscreen mode

就这样！现在你可以创建 Storybook 故事来记录组件的状态了。

主题

您可以为您的 Storybook 文档选择不同的主题。

黑暗主题

  1. 导入addParameters和主题：
import { addParameters } from '@storybook/react';
import { themes } from '@storybook/theming';
Enter fullscreen mode Exit fullscreen mode
  1. 接下来，将主题键添加到参数选项中：
import { addParameters } from '@storybook/react';
import { themes } from '@storybook/theming';

// Option defaults.
addParameters({
  options: {
    theme: themes.dark,
  },
});
Enter fullscreen mode Exit fullscreen mode

瞧，黑暗主题！

深色主题

自定义主题

您可以使用 create() 函数生成自定义主题。

  1. 在 .storybook 文件夹中创建一个新文件，并根据你的主题命名。我将我的命名为purpleDream.js

  2. 粘贴以下代码并更新值以满足您的主题需求。

import { create } from "@storybook/theming";

export default create({
  base: "dark",

  colorPrimary: "mistyrose",
  colorSecondary: "purple",

  // UI
  appBg: "#9f84bd",
  appContentBg: "#ede3e9",
  appBorderColor: "grey",
  appBorderRadius: 4,

  // Typography
  fontBase: '"Open Sans", sans-serif',
  fontCode: "monospace",

  // Text colors
  textColor: "white",
  textInverseColor: "rgba(255,255,255,0.9)",

  // Toolbar default and active colors
  barTextColor: "white",
  barSelectedColor: "white",
  barBg: "#ca7df9",

  // Form colors
  inputBg: "white",
  inputBorder: "silver",
  inputTextColor: "white",
  inputBorderRadius: 4,

  brandTitle: "My custom storybook",
  brandUrl: "https://example.com",
  brandImage: "https://placehold.it/350x150"
});
Enter fullscreen mode Exit fullscreen mode
  1. 更新您的config.js文件以使用您的新主题。
import { configure } from "@storybook/react";
import { addParameters } from "@storybook/react";
import purpleDream from "./purpleDream";

function loadStories() {
  require("../src/stories");
}

addParameters({
  options: {
    theme: purpleDream
  }
});

configure(loadStories, module);
Enter fullscreen mode Exit fullscreen mode

好了，现在你有了一个自定义主题（希望不要像我的那么丑）。

紫色的梦

希望你喜欢这篇 Storybook 和 React 入门教程。欢迎在GitHub上查看我的代码。

文章来源：https://dev.to/emmabostian/documenting-react-components-with-storybook-4h3b
Devto 翻译
PREV
我如何在一年内获得 65,000 名 Twitter 粉丝 2018 年 9 月 2018 年 10 月 2018 年 11 月 2018 年 12 月 2019 年 1 月 2019 年 2 月 2019 年 3 月 2019 年 4 月 2019 年 5 月 2019 年 6 月 2019 年 7 月 2019 年 8 月 2019 年 9 月 获得粉丝的技巧 社交媒体增长的负面影响 结论
NEXT
设计系统（第二部分：设计语言）什么是设计语言？如何构建设计语言？