加入直播：美东时间周四上午 11 点，Storybook 9 发布会及 AMA
86,718
文档
Storybook Docs

代码片段贡献

添加或更新文档中的代码片段。本页概述了代码片段的结构。

已记录的框架

Storybook 为多种框架维护代码片段。我们努力随着框架 API 的演变保持其最新状态。但是跟踪每个框架中的每个 API 变更非常棘手。

我们欢迎社区对代码片段做出贡献。以下是我们拥有代码片段的框架列表。请帮助我们为您喜爱的框架添加片段。

ReactVue 3AngularWeb ComponentsSvelteSolidEmberHTMLPreactQwik
✅✅✅✅✅✅❌❌❌❌

代码片段语法

Storybook 文档中引用的代码片段位于 docs/_snippets 目录下，包含支持的框架、特性和语言（即 JavaScript、MDX、TypeScript）的单独 Markdown 文件中。

示例

以下代码块演示了如何在 Storybook 文档中构建代码片段以及可用于为代码片段提供额外上下文的属性。

docs/_snippets/button-group-story.md
```ts filename="ButtonGroup.stories.ts" renderer="vue" language="ts" tabTitle="3"
import type { Meta, StoryObj } from '@storybook/vue3-vite';
 
import ButtonGroup from './ButtonGroup.vue';
 
//👇 Imports the Button stories
import * as ButtonStories from './Button.stories';
 
const meta = {
  component: ButtonGroup,
}} satisfies Meta<typeof ButtonGroup>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Pair: Story = {
  render: (args) => ({
    components: { ButtonGroup },
    setup() {
      return { args };
    },
    template: '<ButtonGroup v-bind="args" />',
  }),
  args: {
    buttons: [{ ...ButtonStories.Primary.args }, { ...ButtonStories.Secondary.args }],
    orientation: 'horizontal',
  },
};
```

代码片段常用属性

以下是您在 Storybook 文档代码片段中最常使用的属性，以及简要说明，帮助您理解其使用情境。

文件名称作为标题

大多数代码示例应包含文件名，以便读者了解其关联的文件以及将其粘贴到项目中的位置。对于代码示例，使用引号包裹 filename 属性来指明文件名。如果示例与终端命令相关，则不需要此属性。

docs/_snippets/button-stories.md
```ts filename="Button.stories.ts"
```

语言配置

使用 language 属性定义代码片段适用的语言。文档使用此属性来确定显示哪种变体（例如，JavaScript、TypeScript、MDX）。

docs/_snippets/button-stories.md
```ts filename="Button.stories.ts" language="js|ts|mdx"
```

框架特定代码

使用 renderer 属性指示代码片段属于支持的框架中的哪一个。

docs/_snippets/button-stories.md
```ts filename="Button.stories.ts" language="ts" renderer="react|vue|angular|web-components|ember|html|svelte|preact|qwik|solid"
```

或者，如果您要记录适用于多个框架的示例，请使用 renderer 属性并将其值设置为 common，以表明该代码片段是框架无关的。

docs/_snippets/button-stories.md
```ts filename="Button.stories.ts" language="ts" renderer="common"
```

包管理器配置

使用 packageManager 属性配置示例中使用的包管理器，可选值包括：npm、yarn 或 pnpm。

docs/_snippets/storybook-run-dev.md
```shell renderer="common" language="js" packageManager="npm|yarn|pnpm"
```

处理多个代码片段

使用 tabTitle 属性指示代码片段将显示在哪个选项卡标题中。此属性仅在单个代码片段文件中有多个示例时使用。

docs/_snippets/component-decorator.md
```ts filename="YourComponent.stories.ts" language="ts" renderer="common" tabTitle="Story"
```
```ts filename=".storybook/preview.ts" language="ts" renderer="common" tabTitle="Storybook configuration"
```

贡献代码片段

熟悉了 Storybook 文档的组织方式、代码片段的结构以及可用选项后，您就可以开始贡献了。假设您已经设置好了本地开发环境并准备好贡献，以下步骤将指导您向 Storybook 文档贡献代码片段。

首先在您的本地 Storybook monorepo 上使用以下命令创建一个新分支

git checkout -b code-snippets-for-framework

浏览文档并查找您想要贡献的代码片段。例如，在设置页面上，您应该会看到以下内容

docs/get-started/setup.mdx
{/* prettier-ignore-start */}
 
<CodeSnippets path="your-component.md" usesCsf3 />
 
{/* prettier-ignore-end */}

打开 docs/_snippets 目录内的文件，并调整内容以匹配您想要贡献的代码片段。例如

docs/_snippets/your-component.md
```ts filename="YourComponent.stories.ts" renderer="qwik" language="ts"
import type { Meta, StoryObj } from 'storybook-framework-qwik';
 
import type { YourComponentProps } from './YourComponent';
 
import { YourComponent } from './YourComponent';
 
//👇 This default export determines where your story goes in the story list
const meta = {
  component: YourComponent,
} satisfies Meta<YourComponentProps>;
 
export default meta;
type Story = StoryObj<YourComponentProps>;
 
export const FirstStory: Story = {
  args: {
  //👇 The args you need here will depend on your component
  },
};
```

浏览文档的其余部分并重复该过程。

预览您的工作

在提交您的贡献之前，我们鼓励您对照 Storybook 网站检查您的工作。这样做可以避免文档出现最后一分钟的问题，也是维护者在您提交拉取请求后更快合并的好方法。但是，如果您未能这样做，将导致其中一位维护者通知您您的贡献存在问题。

首先 fork Storybook 网站仓库并将其克隆到本地。

git clone https://github.com/your-username/web.git

导航到 web 目录并安装所需的依赖项。

npm install

我们建议您首先生成网站构建，以确保您可以在本地预览您的更改并验证一切是否按预期工作。为此，运行以下命令

npm run build:frontpage

执行此命令时，它将检索成功构建 Storybook 网站所需的必要文件，包括当前文档版本（例如，6.5、7.6、8.x），并将它们复制到按版本号组织的 apps/frontpage/docs/ 目录中。

运行 sync-docs 命令将 Storybook monorepo 中的文档连接到 Storybook 网站。当提示时，提供您的 Storybook monorepo 本地 fork 的路径以及您正在处理的文档版本。

npm run sync-docs

最后，打开一个新的终端窗口并运行 dev 命令启动 Storybook 网站。

npm run dev

如果一切顺利，您应该会看到 Storybook 网站正在运行。打开浏览器窗口访问 http://localhost:3000，点击 Docs 链接打开文档，然后从下拉菜单中选择您的框架。

浏览文档并检查您的工作。

提交您的贡献

验证您的更改按预期工作后，您就可以创建“拉取请求”了。这将让 Storybook 的维护者知道您有要提出的更改。此时，我们可以为您提供反馈并请求更改。为了帮助审查过程，我们鼓励您为您的工作添加清晰的标题和描述。

故障排除

代码片段未显示

如果您记录的示例中包含 packageManager 属性并与另一个示例组合使用，文档可能无法正确显示代码片段。为避免此问题，您可以将示例分成单独的文件并在文档中引用它们。

了解更多关于贡献 Storybook 的信息

  • 用于撰写功能请求的RFC 流程
  • 用于实现功能和修复错误的代码
  • 用于开始使用新框架的框架
  • 用于改进文档、修正错别字和澄清的文档
  • 新代码片段示例
本页是否有用？
✍️ 在 Github 上编辑