Frontend Academy · 课时

Storybook：故事、控件与文档

为每种组件状态编写故事，使用 Controls 交互式调整属性，并根据 JSDoc 和 argTypes 生成文档页面。

Storybook：故事、控件与文档 是 CoddyKit 上的免费 Frontend Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。

什么是 Storybook

Storybook 是一个与应用隔离的 UI 组件工作台。您可以编写“故事”——展示每个组件在各种状态下的使用示例——并在开发服务器中浏览它们。对于设计系统来说，它不可或缺。

为什么使用 Storybook

1）无需搭建应用上下文即可隔离开发组件。2）以可视化方式查看所有状态（加载中、错误、空）。3）设计师和产品经理可以浏览组件目录。4）生成文档。5）自动执行视觉回归测试。

安装 Storybook

使用官方初始化程序——它会检测您的框架并完成所有配置。

npx storybook@latest init

# Adds:
#  .storybook/        config
#  src/stories/       example stories
#  scripts: 'storybook' and 'build-storybook'

npm run storybook   # opens http://localhost:6006

编写故事（CSF 3.0）

组件故事格式 3：默认导出表示元数据，具名导出表示故事。

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Atoms/Button',
  component: Button,
  tags: ['autodocs']
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { label: 'Save', variant: 'primary' }
};

export const Disabled: Story = {
  args: { label: 'Save', variant: 'primary', disabled: true }
};

每个组件编写多个故事

为每个重要状态编写一个故事：默认、悬停、加载中、错误、空、已填充。评审者可以逐个点击查看，一眼看到所有变体。

export const Loading: Story = { args: { state: 'loading' } };
export const Error: Story    = { args: { state: 'error', message: 'Network failed' } };
export const Empty: Story    = { args: { items: [] } };
export const Populated: Story = { args: { items: mockItems } };

控件（参数表）

Storybook 的 Controls 插件会将 args 对象转换为交互式表单控件。直接在 UI 中实时调整属性值，以测试边界情况。

const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger']
    },
    onClick: { action: 'clicked' }
  }
};

Actions 插件

使用 action() 在 Actions 面板中记录事件处理程序的调用。无需连接真实状态，就能很好地测试回调。

argTypes: {
  onClick: { action: 'clicked' },
  onChange: { action: 'changed' }
}

Autodocs——自动生成的文档

将 tags: ['autodocs'] 添加到元数据中；Storybook 会生成一个 Docs 页面，其中包含组件属性表、说明和可渲染示例。

使用 MDX 编写丰富文档

使用 MDX 编写组件文档——它结合了 Markdown 和嵌入式 JSX。您可以将说明文字与实时组件示例混合在一起。

{/* Button.mdx */}
import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

The primary action element.

## Variants
<Canvas of={ButtonStories.Primary} />
<Canvas of={ButtonStories.Secondary} />

装饰器——为故事包装上下文

使用 decorators 为故事包装 provider（主题、路由器、Redux）。

export const decorators = [
  (Story) => (
    <ThemeProvider theme={lightTheme}>
      <Story />
    </ThemeProvider>
  )
];

视觉回归测试

Chromatic（由 Storybook 团队开发）会在每次提交时为每个故事截取屏幕截图，并与基准进行差异比较。它可以自动捕获视觉回归。

部署 Storybook

npm run build-storybook 会在 storybook-static/ 中生成静态网站。将其部署到 Netlify、Vercel 或 GitHub Pages，即可让非开发人员浏览组件目录。

快速检查

将 tags: ['autodocs'] 添加到组件的 Storybook 元数据后，会产生什么效果？

回顾：Storybook

用于 UI 组件的隔离式工作台。CSF 3.0：默认导出表示 meta，具名导出表示 stories。使用 argTypes 配置 Controls。使用 action() 记录回调调用。使用 tags: ['autodocs'] 自动生成文档。使用 MDX 编写丰富的说明文字和 JSX。装饰器用于注入 provider。使用 Chromatic 进行视觉回归测试。使用 build-storybook 进行静态托管。

常见问题解答

「Storybook：故事、控件与文档」课时是免费的吗？

是的 — 「Storybook：故事、控件与文档」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。

「Storybook：故事、控件与文档」这节课中我会学到什么？

为每种组件状态编写故事，使用 Controls 交互式调整属性，并根据 JSDoc 和 argTypes 生成文档页面。你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Frontend Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「Storybook：故事、控件与文档」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Frontend Academy 课中编写并运行代码吗？

能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Frontend Academy