85,947
文档
Storybook 文档

代码片段贡献

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

已记录的框架

Storybook 为各种框架维护代码片段。我们 চেষ্টা করে API 演变时保持代码片段的更新。但是，跟踪每个框架中的每个 API 更改是很棘手的。

我们欢迎社区为代码片段做出贡献。这是一个我们提供代码片段的框架矩阵。帮助我们为您最喜欢的框架添加代码片段。

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

代码片段语法

在整个 Storybook 文档中引用的代码片段位于 docs/_snippets 目录中的各个 Markdown 文件内，其中包含支持的框架、功能和语言（即 JavaScript、MDX、TypeScript）。

示例

以下代码块演示了如何在 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';
 
import ButtonGroup from './ButtonGroup.vue';
 
//👇 Imports the Button stories
import * as ButtonStories from './Button.stories';
 
const meta: Meta<typeof ButtonGroup> = {
  component: ButtonGroup,
};
 
export default meta;
type Story = StoryObj<typeof ButtonGroup>;
 
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、TypeScript 4.9、MDX）。

docs/_snippets/button-stories.md
```ts filename="Button.stories.ts" language="js|ts|ts-4-9|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-4-9"
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 网站。出现提示时，提供您本地 fork 的 Storybook monorepo 的路径以及您正在处理的文档版本。

npm run sync-docs

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

npm run dev

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

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

提交您的贡献

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

故障排除

代码片段未显示

如果您正在记录包含 packageManager 属性以及另一个示例的示例，则文档可能无法正确显示代码片段。为避免这种情况，您可以将示例分成单独的文件并在文档中引用它们。

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

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