Storybook 7 文档

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

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

Storybook 7 从头重塑了文档功能，以提供更简洁的 API 和改进的开发者体验。

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

为什么要重塑 Storybook 文档？

Storybook 文档最初于 2019 年发布。我们通过几次迭代快速添加了功能，包括

• 自动文档（Autodocs）：一个自动模板，包含单个组件的描述和故事。
• MDX 支持：使用一组“Doc Blocks”对给定组件显示的内容进行更多控制。
• 自动参数类型推断：显示一个包含组件 props 的表格，甚至可以在文档中直接与故事进行交互。
• 源码片段：有用且动态的代码片段，显示如何使用组件来生成当前显示的故事。

在此过程中，我们学到了很多东西并收到了大量用户反馈。Storybook 7.0 给了我们重新设计文档功能并应用这些经验的机会。这也使我们能够为 Storybook 和生态系统的未来迭代做好准备。

自动文档以组件为中心

Storybook 7 文档功能的主要变化是，您正在文档化组件而不是故事。 现在，每个组件都有一个单独的文档入口，显示在该组件的故事列表上方。这取代了在“文档”视图模式下查看每个故事的方式。

文档页面现在作为一级入口显示在侧边栏中，将它们置于 Storybook 的显眼位置，并让您对哪些组件进行文档化有更大的控制权。

通过参数配置自动文档

在自动文档模板中，我们展示组件的名称和描述、主要故事以及用于更改其参数的控制区块，然后是该组件所有故事及其描述的静态列表

您可以通过参数控制自动文档如何渲染每个故事。我们重做了参数，使其更加一致和强大，并且还改进了它们的文档。

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 编写组件和故事描述

为了控制组件和故事的描述，我们将 JSDoc 作为首选方法——这样您的文档和代码无需额外努力即可保持同步。

自动文档现在是选择性开启的

自动文档的另一个重要变化是，您必须选择是否为组件启用文档页面。在 Storybook 7 中，您必须为组件添加 autodocs 标签才能生成其自动文档页面。这默认不启用。

// Button.stories.js|ts

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

如果您想将 autodocs 应用于所有故事，请在 ./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）时，会为该文件创建一个新的侧边栏入口。默认情况下，这是一个独立的文档页面。要将入口附加到组件并使其像自动文档一样出现在故事上方，请使用 <Meta of={}> 区块。

Doc Blocks API 强大而简单

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

您会注意到 Doc Blocks 的主要变化是，故事和组件现在是通过引用来引用的，而不是通过它们的 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

文档重塑的目标之一是保持 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 文件中定义故事已被弃用，作为 mdx-to-csf 迁移的一部分，我们将任何现有定义故事的 MDX 文件转换为一个 MDX 文件和一个 CSF 文件。我们从许多用户那里得知，他们不确定是否应该在 MDX 文件中编写故事（他们其实不必如此），以及这样做有什么好处（好处并不明显）。为了缩小范围并支持未来的用例，我们决定弃用该功能。上述迁移会将此类文件转换为新的 MDX 文件和单独的 CSF 文件。

Storybook 文档的未来

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

便携式文档：允许您在非 Storybook 环境中重用 Storybook 区块甚至整个 MDX 文件。我们的目标是允许建立一个完全定制的文档网站（使用您选择的技术），该网站可以原生嵌入来自 CSF 和 MDX 文件的故事和其他元数据。

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

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