Storybook 7 文档

Stories（故事）是描述组件使用方式的强大方法。它们可用于开发、测试，当然还有文档记录组件。

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

Storybook 7 从头开始重构了 Docs，提供了更精简的 API 和改进的开发者体验。

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

为什么重构 Storybook Docs？

Storybook Docs 最初发布于 2019 年。在随后的几个版本中，我们迅速迭代，添加了包括以下功能：

• 自动文档 (Autodocs)：一个自动模板，包含单个组件的描述和 stories。
• MDX 支持：使用一组“文档块”（Doc Blocks），可以更精细地控制给定组件的显示内容。
• 自动参数类型推断：显示一个包含组件 props 的表格，甚至可以在文档中内联尝试 stories。
• 源代码片段：显示如何使用组件来生成当前显示的故事的有用且动态的代码片段。

在此过程中，我们学到了很多经验，并获得了大量用户反馈。Storybook 7.0 使我们有机会重新设计 Docs 功能并应用这些经验。这还使我们能够为 Storybook 及其生态系统的未来迭代做好准备。

自动文档以组件为中心

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

Docs 页面现在显示为侧边栏中的一级条目，将它们置于 Storybook 的最前方，并让你更精细地控制要记录哪些组件。

通过参数配置自动文档

在自动文档模板中，我们显示组件的名称和描述、主 story 以及用于更改其参数的 controls 块，然后是组件所有 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={}> 块。

Doc Blocks API 功能强大且简单

Doc Blocks 是我们的一组组件，可让你在 MDX 文件中渲染 stories 和组件的其他元数据。Storybook 7 Docs 的一个主要重点是重新思考 Doc Blocks，以使 MDX 文件更易于维护，并支持自动完成和 linting。

你将注意到的 Doc Blocks 的主要变化是，stories 和组件现在按引用而不是按它们的 Storybook ID（内部概念）进行引用。

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 版本的一部分，我们发布了所有 Doc Blocks 的全面文档。如果你还没有编写自己的 MDX 文档文件，这应该可以帮助你。

我们甚至包含了一个useOf hook 来帮助你编写自己的自定义 Doc Block，它可以支持 of={} 语法！

迁移：你需要知道什么

Storybook 7 现已推出！要为现有项目立即试用，请运行

npx storybook@latest upgrade

Docs 重构的目标是保持 7.x 系列版本向后兼容，所以你现在不需要迁移现有的 Docs 代码。

为 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 Docs 的未来

Storybook 7 中 Docs 重构的一个重要部分是为 Storybook Docs 的未来方向奠定基础。除了普遍改进之外，以下是一些我们正在为未来的 7.x 版本考虑的领域：

可移植文档 (Portable Docs)：允许你在非 Storybook 上下文中重用 Storybook blocks 甚至整个 MDX 文件。我们的目标是允许使用你选择的技术构建完全自定义的文档站点，该站点可以原生嵌入来自你的 CSF 和 MDX 文件的 stories 和其他元数据。

注解服务器 (Annotations Server)：我们正致力于将 Storybook 的参数类型推断机制从其运行时中提取出来，转而运行一个按需服务器。这意味着在开发中，我们只会为正在处理的组件生成注解（例如参数类型）；而在已构建的故事书中，所有成本将在构建时支付。

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