组件故事格式 3 来了

故事可视化展示组件在不同场景下的行为。组件故事格式 (CSF) 是故事的通用文件格式。

组件故事格式 3 标志着故事的演进，它减少了样板代码并提高了人体工程学。这使得故事更简洁，编写速度更快。

我很高兴地宣布 CSF3 正式发布。在 18 个月的beta 版期间，社区帮助我们发现了问题并完善了格式。从 Storybook 7 开始，CSF3 将成为编写故事的默认方式。

改进包括

• ♻️ 可扩展的故事对象，轻松扩展故事
• 🌈 默认渲染函数，简洁明了
• 📓 自动标题，方便快捷
• ▶️ 播放函数，用于脚本化交互和测试
• ✅ 与 CSF 2 完全向后兼容

继续阅读以了解更多关于格式的信息，自最初公告以来的变化，以及如何在 Storybook 7 中充分利用它。

等等，为什么？

在应用程序外部开发 UI 组件是创建高质量组件的最佳方式。Storybook 开创了这种组件驱动开发 (CDD) 样式。

故事现在用于设计师和产品经理的视觉评审，以及设计系统文档、自动测试，甚至从生产组件生成设计资产。

毫不奇怪，Storybook 被用于构建 Shopify、IBM 和 Salesforce 等许多世界上最流行的 UI。

CSF3 是故事的下一个演进——更易于编写和维护

与它的前身一样，CSF3 基于 ESM。默认导出包含有关组件的信息，以及一个或多个命名导出——故事——捕获不同的组件状态。主要区别在于故事现在是对象，并且您可以为每个故事附加一个播放函数来模拟用户交互。

CSF3 与 CSF2 完全向后兼容，CSF2 仍在 Storybook 7 中受支持。我们甚至将播放函数移植到了 CSF2。

我们建议迁移，因为 CSF3 更具表现力和可维护性，所需的样板代码更少。在大多数情况下，您可以使用代码模块自动从 CSF 2 迁移到 3。

CSF3 功能回顾

大型项目可能包含数百个组件和数千个故事。当您编写如此多的故事时，人体工程学的改进会导致明显的体验提升。我们的目标是简化故事格式，使编写、阅读和维护故事变得更容易。

让我们看看 CSF3 在一个假设的 RegistrationForm 组件中是什么样的。

默认导出声明您正在为其编写故事的组件

// RegistrationForm.stories.js

import { RegistrationForm } from './forms/RegistrationForm';

export default {
  title: 'forms/RegistrationForm',
  component: RegistrationForm,
};

而故事现在是对象

export const EmptyForm = {
  render: (args) => <RegistrationForm {...args} />,
  args: { /* ... */ },
  parameters: {  /* ... */ },
};

默认渲染函数，简洁明了。 90% 的时间，编写故事只是以标准方式将一些输入传递给您的组件。

在 CSF3 中，如果您没有指定渲染函数，每个故事都会渲染组件并传入所有参数。这极大地简化了您的代码。

在我们的 RegistrationForm 示例中，渲染函数是样板代码

export const EmptyForm = {
  // render: (args) => <RegistrationForm {...args} />, -- now optional!
  args: { /* ... */ },
  parameters: {  /* ... */ },
};

可扩展的故事对象，方便复用。 当您尝试模拟复杂状态时，能够扩展现有故事而不是重新编写它们非常有用。假设您想显示已填写的表单，但在不同的视口中

export const FilledForm = {
  args: {
    email: '[email protected]',
    password: 'j1287asbj2yi394jd',
  }
};

export const FilledFormMobile = {
  ...FilledForm,
  parameters: {
    viewports: { default: 'mobile' }
  },
};

播放函数，用于脚本化交互。 一些 UI 状态如果没有用户交互是不可能捕获的。播放函数在故事渲染后运行，并使用 testing-library 模拟用户交互。例如

// RegistrationForm.stories.ts|tsx
import { userEvent, within } from '@storybook/testing-library';

// ...

export const FilledForm = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    const emailInput = canvas.getByLabelText('email', { 
        selector: 'input' 
    });
    await userEvent.type(emailInput, '[email protected]', { 
        delay: 100 
    });

    const passwordInput = canvas.getByLabelText('password', { 
        selector: 'input' 
    });
    await userEvent.type(passwordInput, 'ExamplePassword', { 
        delay: 100 
    });

    const submitButton = canvas.getByRole('button');
    await userEvent.click(submitButton);
  },
};

自动标题，方便快捷。 在 CSF 中，故事的标题决定了它在 UI 中导航层次结构中的显示位置。在 CSF3 中，可以根据文件相对于根目录的位置自动生成标题。输入更少，如果重新排序文件，则无需更新。

export default {
  // title: 'forms/RegistrationForm' -- optional
  component: RegistrationForm,
};

有关 CSF3 功能和原理的详细说明，以及它与 CSF2 的确切区别，请参阅原始 CSF3 文章。

与原始版本的变化

在过去一年半的时间里，用户一直在他们的项目中测试 CSF3。根据反馈，我们对原始版本进行了一些更改。

更好的 TypeScript 类型。 我们已在 7.0 中更新了 Meta/Story 类型，以支持故事的类型安全性和自动完成功能。敬请关注未来几周内关于此内容的专门文章。

更新的自动标题启发式方法。 Autotitle 根据 CSF 文件的磁盘位置生成“标题”（Storybook 侧边栏中的路径）。例如，如果 /project/path/src 是故事根目录，则 /project/path/src/atoms/Button.stories.js 将获得标题 atoms/Button。但是，简单的启发式方法无法处理 atoms/Button/Button.stories.js 或 atoms/Button/index.stories.js 等常见模式。我们更新了启发式方法以解决此问题。有关完整的迁移说明和其他一些自动标题改进（包括更好的前缀处理和大小写），请参阅MIGRATION.md。

升级的文档和 CLI 模板。 最后但并非最不重要的是，我们使用 CSF3 源代码片段升级了 7.0 的官方文档。我们还更新了 CLI 以生成新项目的 CSF3。

立即升级到 CSF3

CSF3 与之前版本完全向后兼容，因此您现有的 CSF 故事无需修改即可正常工作。我们不会很快弃用旧格式。但是，CSF3 是一个巨大的进步，我们建议您在升级到 Storybook 7.0 (SB7) 时将其作为故事升级的一部分。

要升级到 SB7，请参阅我们的SB7 迁移指南。项目升级后，您可以选择使用以下代码模块将 CSF 故事迁移到 CSF3。请务必更新 glob 以包含您要更新的文件。

npx storybook@next migrate csf-2-to-3 --glob="**/*.stories.js"

如果您无法使用代码模块，我们还有升级说明可用。

参与进来

组件故事格式 (CSF) 可帮助您独立开发、测试和记录组件。CSF3 带来了改进的人体工程学，可帮助您更轻松地编写更多故事。

CSF3 由Michael Shilman（我！）、Kasper Peulen、Tom Coleman 和Pavan Sunkara开发，并得到了整个 Storybook 社区的测试和反馈。

Storybook 是超过1600 位社区贡献者的成果。加入我们，在GitHub上与我们联系，或在Discord上与我们聊天。最后，关注 Twitter 上的@storybookjs，获取最新消息。