立即开始
Docs
Storybook Docs

代码片段贡献

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

¥Add or update the code snippets in the documentation. This page outlines how the code snippets are structured.

文档框架

¥Documented frameworks

Storybook 维护 各种框架 的代码片段。随着框架 API 的发展，我们会尝试使它们保持最新状态。但是，跟踪每个框架中的每个 API 更改非常棘手。

¥Storybook maintains code snippets for a variety of frameworks. We try to keep them up to date as framework APIs evolve. But keeping track of every API change in every framework is tricky.

我们欢迎社区对代码片段做出贡献。以下是我们提供代码片段的框架矩阵。帮助我们为你最喜欢的框架添加代码片段。

¥We welcome community contributions to the code snippets. Here's a matrix of the frameworks for which we have snippets. Help us add snippets for your favorite framework.

ReactVue 3AngularWeb 组件SvelteSolidEmberHTMLPreactQwik
✅✅✅✅✅✅❌❌❌❌

代码片段语法

¥Snippet syntax

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

¥The code snippets referenced throughout the Storybook documentation are located in the docs/_snippets directory inside individual Markdown files, containing the supported frameworks, features and languages (i.e., JavaScript, MDX, TypeScript).

示例

¥Example

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

¥The following code block demonstrates how to structure a code snippet in the Storybook documentation and the attributes you can use to provide additional context to the code snippet.

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',
  },
};
```

代码片段的常用属性

¥Common attributes for code snippets

以下是你在 Storybook 文档代码片段中最常用的属性，以及每个属性的简要说明，以帮助你了解它们的使用环境。

¥Following are the attributes you'll use most often in the Storybook documentation code snippets, as well as a brief explanation of each to help you understand the context in which they are used.

文件名作为标题

¥File name as title

大多数代码示例都应包含文件名，以便读者了解它们与哪个文件相关，以及将其粘贴到项目中的哪个位置。代码示例请包含 filename 属性，并用引号括起来以指示文件名。如果示例与终端命令相关，则无需执行此操作。

¥Most code examples should include a file name so readers can understand which file they relate to and where to paste it into their project. For code examples, include the filename attribute wrapped with quotation marks to indicate the file name. This is not required if the example relates to a terminal command.

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

语言配置

¥Language configuration

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

¥Use the language attribute to define the language to which the code snippet applies. The documentation uses this attribute to determine which variant to display (e.g., JavaScript, TypeScript, MDX).

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

框架特定代码

¥Framework-specific code

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

¥Use the renderer attribute to indicate which of the supported frameworks the code snippet belongs to.

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 值来指示代码片段与框架无关。

¥Alternatively, if you're documenting examples that apply to multiple frameworks, use the renderer attribute with the common value to indicate that the code snippet is framework-agnostic.

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

软件包管理器配置

¥Package manager configuration

使用 packageManager 属性从以下选项中配置示例中使用的包管理器：npm、yarn 或 pnpm。

¥Use the packageManager attribute to configure the package manager used in the example from the following options: npm, yarn, or pnpm.

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

使用多个代码片段

¥Working with multiple snippets

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

¥Use the tabTitle attribute to indicate the tab title in which the code snippet will be displayed. This attribute should only be used when multiple examples are in a single code snippet file.

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"
```

贡献代码片段

¥Contributing code snippets

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

¥You can start contributing to the Storybook documentation by now that you're familiar with how the documentation is organized, the code snippet's structure, and available options. Assuming that you have already set up your local development environment and are ready to contribute, the following steps will guide you through contributing code snippets to the Storybook documentation.

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

¥Start by creating a new branch on your local Storybook monorepo with the following command:

git checkout -b code-snippets-for-framework

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

¥Browse the documentation and look for the code snippets you want to contribute. For example, on the setup page you should see the following:

YourComponent.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { YourComponent } from './YourComponent';
 
//👇 This default export determines where your story goes in the story list
const meta = {
  component: YourComponent,
} satisfies Meta<typeof YourComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const FirstStory: Story = {
  args: {
    //👇 The args you need here will depend on your component
  },
};

打开 docs/_snippets 目录中的文件，并调整内容以匹配你愿意贡献的代码片段。例如：

¥Open the file inside the docs/_snippets directory and adjust the content to match the code snippet you're willing to contribute. For example:

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
  },
};
```

查看其余文档并重复该过程。

¥Go through the rest of the documentation and repeat the process.

预览你的工作

¥Preview your work

在提交你的贡献之前，我们建议你对照 Storybook 网站检查你的工作。这样做可以防止文档在最后一刻出现问题，也是维护人员在提交拉取请求后更快地合并的好方法。但是，如果不这样做，维护者之一将通知你你的贡献存在问题。

¥Before submitting your contribution, we encourage you to check your work against the Storybook website. Doing this prevents last-minute issues with the documentation and is also an excellent way for the maintainers to merge faster once you submit the pull request. However, failing to do so will lead one of the maintainers to notify you that your contribution has an issue.

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

¥Start by forking the Storybook website repository and cloning it locally.

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

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

¥Navigate to the web directory and install the required dependencies.

npm install

我们建议你首先生成一个网站版本，以确保你可以在本地预览更改并验证一切是否按预期运行。为此，请运行以下命令：

¥We recommend that you generate a website build first to ensure you can preview your changes locally and verify that everything is working as expected. To do so, run the following command:

npm run build:frontpage

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

¥When executed, this command will retrieve the required files needed to successfully build the Storybook website, including current documentation versions (e.g., 6.5, 7.6, 8.x), and copy them to the apps/frontpage/docs/ directory, organized by version number.

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

¥Run the sync-docs command to connect the documentation from the Storybook monorepo to the Storybook website. When prompted, provide the path to your local fork of the Storybook monorepo and the documentation version you're working on.

npm run sync-docs

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

¥Finally, open a new terminal window and run the dev command to start the Storybook website.

npm run dev

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

¥If all goes well, you should see the Storybook website running. Open a browser window to http://localhost:3000, click the Docs link to open the documentation, and select your framework from the dropdown.

查看文档并检查你的工作。

¥Go through the documentation and check your work.

提交你的贡献

¥Submit your contribution

验证更改是否按预期工作后，即可创建 "拉取请求"。这将让 Storybook 维护人员知道你有一些更改要提出。此时，我们可以向你提供反馈并请求更改。为了帮助审核流程，我们建议你为你的工作添加清晰的标题和描述。

¥Once you have verified that your changes are working as expected, you're ready to create a "Pull Request". This will let the Storybook maintainers know you have some changes to propose. At this point, we can give you feedback and request changes. To help with the review process, we encourage you to add a clear title and description of your work.

故障排除

¥Troubleshooting

代码片段不显示

¥Code snippets not displaying

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

¥If you're documenting an example that includes the packageManager attribute combined with another example, the documentation might not display the code snippets correctly. To avoid this, you can divide the examples into separate files and reference them in the documentation.

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

¥Learn more about contributing to Storybook

  • RFC 流程 用于编写功能请求

    ¥RFC process for authoring feature requests

  • 代码 用于功能和错误修复

    ¥Code for features and bug fixes

  • 框架 用于开始使用新框架

    ¥Frameworks to get started with a new framework

  • 文档 用于文档改进、拼写错误和澄清

    ¥Documentation for documentation improvements, typos, and clarifications

  • 新代码片段示例

    ¥Examples for new snippets