Storybook 7 文档

Stories (故事) 是一种描述组件使用方式的强大方法。它们可以用于开发、测试，当然还有组件文档。

我们构建了 Storybook 文档，以帮助团队记录他们的组件库和设计系统。它使用 stories 和其他相关的元数据，为每个组件自动生成文档页面 (DocsPage)，其中包含 API 表格和实时示例。

Storybook 7 从底层重构文档功能，提供更简洁的 API 和改进的开发者体验。

• 🏛️ 以组件为中心的新信息架构
• ⬆️ 升级以支持 MDX2
• 🧱 更强大且一致的文档块 API

为什么要重构 Storybook 文档？

Storybook 文档最初于 2019 年 发布。我们快速迭代了几个版本，添加了以下功能，包括

• 自动文档：一个自动模板，包括单个组件的描述和 stories。
• MDX 支持： 使用一组“文档块”更灵活地控制给定组件的显示内容。
• 自动参数类型推断： 显示组件的 props 表格，甚至可以在文档中内联操作 stories。
• 源代码片段：实用且动态的代码片段，展示如何使用组件来生成当前显示的 story。

在此过程中，我们吸取了很多教训，并收到了大量用户反馈。Storybook 7.0 让我们有机会重新架构文档功能并应用这些经验。这也使我们能够为 Storybook 和生态系统的未来迭代做好准备。

自动文档以组件为中心

Storybook 7 文档功能的主要变化是您正在记录组件而不是 stories。  现在，我们每个组件都有一个文档条目，显示在该组件的 stories 列表上方。这取代了在“文档”视图模式下查看每个 story。

文档页面现在作为一级条目显示在侧边栏中，使其在 Storybook 中占据中心位置，并使您可以更好地控制要记录哪些组件。

通过参数配置自动文档

在自动文档模板中，我们显示组件的名称和描述、主要 story 以及用于更改其 args 的控件块，然后是组件的所有 stories 的静态列表及其描述

您可以通过参数控制自动文档如何渲染每个 story。我们重新设计了参数，使其更一致、更强大，并且我们还改进了它们的文档。

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
  parameters: {
    docs: {
      story: { inline: true }, // render the story in an iframe
      canvas: { sourceState: 'shown' }, // start with the source open
      source: { type: 'code' }, // forces the raw source code (rather than the rendered JSX).
    },
  },
};

使用 JSDoc 进行组件和 story 描述

为了控制组件和 stories 的描述，我们倾向于使用 JSDoc 作为首选方法 —— 这样您的文档和代码可以保持同步，而无需您付出额外的努力。

自动文档现在是可选的

自动文档的另一个重要变化是，您必须选择为组件启用文档页面。在 Storybook 7 中，您必须将 autodocs 标签添加到您的组件，才能生成其自动文档页面。默认情况下，此功能未启用。

// Button.stories.js|ts

export default {
  component: Button,
  tags: ['autodocs'], // enable automatic documentation page
};

如果您希望将 autodocs 应用于所有 stories，请在 ./storybook/main.js 中设置它。更多选项请点击此处。

//.storybook/main.js

module.exports = {
  docs: {
    autodocs: true
  }
};

自动文档保留了 Storybook 以其闻名的令人难以置信的参数类型检测功能。此外，7.0 架构为新的、更高效的检测架构奠定了基础，该架构将为更广泛的框架提供更一致的支持。

改进的 MDX 2 手动文档

您可以使用 MDX 完全自定义组件的文档页面，或创建独立的（未附加的）文档页面。Storybook 7 包含一个简单、一致的 API，使手动文档更易于维护。此外，它现在支持 MDX 2。

MDX 2 是 MDX 编译器的最新主要版本。这是一个值得关注的版本，它带来了广泛的优势和重大更改列表。Storybook 将在 7.x 时间范围内保留对 MDX 1 的可选支持。

当您编写 .mdx 文件（以前是 .stories.mdx）时，将为该文件创建一个新的侧边栏条目。默认情况下，这是一个未附加的文档页面。要附加一个条目到组件并使其像自动文档一样显示在 stories 之上，请使用 <Meta of={}> 块。

文档块 API 功能强大且简单

文档块是我们的一组组件，使您能够在 MDX 文件中渲染 stories 和其他关于组件的元数据。Storybook 7 文档的一个主要重点是重新思考文档块，以便使 MDX 文件更易于维护，并启用自动完成和 linting。

您将注意到的文档块的主要变化是，现在通过引用而不是 Storybook ID（一个内部概念）来引用 stories 和组件。

import * as ButtonStories from './Button.stories';

{/* Attach this MDX file to the Button component */}
<Meta of={ButtonStories} />

{/* Render the Primary story */}
<Story of={ButtonStories.Primary} />

这个新的 API 解锁了未来的功能，这些功能将允许您在 Storybook 之外重用 MDX 文件（敬请期待）。我们还提供了一个 codemod 来帮助您将现有文件迁移到这种新格式（见下文！）。

此外，我们还借此机会使每个块的 API 更加一致和精简。具体来说，我们已将每个块的 props 与用于控制自动文档模板中该块实例的参数对齐。

作为 Storybook 7 发布的一部分，我们发布了所有文档块的全面修订文档。如果您还不熟悉，这应该可以帮助您编写自己的 MDX 文档文件。

我们甚至包含了一个 useOf hook，以帮助您编写自己的可以使用 of={} 语法的自定义文档块！

迁移：你需要知道的

Storybook 7 现已发布！要立即在现有项目中试用，请运行

npx storybook@latest upgrade

文档重构的目标是保持 7.x 系列版本的向后兼容性，因此您不需要立即迁移现有的文档代码。

为 MDX 2 做好准备

使用 MDX 2，引入了一些语法更改。查看 Storybook 7 迁移指南，了解在升级到 Storybook 7 之前将 .stories.mdx 文件迁移到使用 MDX 2 语法的技巧。

如果您在使用 MDX 2 时遇到问题并想恢复使用 MDX 1，您可以添加旧的编译器：

yarn add @storybook/mdx1-csf

// .storybook/main.js
export default {
  features: {
    legacyMdx1: true
  }
}

自动迁移

然而，未来在等待着我们，如果您想获得最新和最棒的功能，首先升级到 Storybook 7，然后您可以使用以下迁移将现有的 .stories.mdx 文件迁移到 Storybook 7 原生 .mdx 文件：

npx storybook@latest migrate mdx-to-csf --glob "**/*.stories.mdx"

特别注意，在 Storybook 7 中，在 MDX 文件中定义 stories 已被弃用，并且作为 mdx-to-csf 迁移的一部分，我们将任何定义 stories 的现有 MDX 文件转换为一个 MDX 文件和一个 CSF 文件。我们从许多用户那里听说，他们不确定是否应该在 MDX 文件中编写 stories（如果他们要记录它们）（他们不必这样做），以及有什么好处（不清楚好处有多少）。为了缩小范围并支持未来的用例，我们决定弃用该功能。上面的迁移会将此类文件转换为新的 MDX 文件和单独的 CSF 文件。

Storybook 文档的未来

Storybook 7 中文档重构的一大部分是为我们 Storybook 文档的未来方向奠定基础。除了总体改进之外，以下是我们正在考虑在未来 7.x 版本中推出的一些领域：

可移植文档：允许您在非 Storybook 上下文中重用 Storybook 块，甚至整个 MDX 文件。我们的目标是允许一个完全自定义的文档站点（使用您选择的技术），它可以原生嵌入来自您的 CSF 和 MDX 文件的 stories 和其他元数据。

注解服务器：我们正在努力从 Storybook 的运行时中提取参数类型推断机制，并改为运行按需服务器。这意味着在开发中，我们仅为正在开发的组件生成注解（例如参数类型）；在构建的 storybooks 中，所有成本将在构建时支付。

改进的推断： 当您考虑到 Storybook 支持的所有框架 时，参数类型推断是一项繁重的工作。作为注解服务器工作的一部分，我们希望改进我们围绕推断的工具和测试套件，以便贡献者更容易改进所有框架的注解。如果您渴望在您选择的框架中获得更好的检测，请关注此空间，了解您帮助的机会！