88,244
文档
Storybook Docs

代码片段贡献

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

已记录的框架

Storybook 为各种框架维护代码片段。我们尽量使它们与框架 API 的演变保持同步。但要跟踪每个框架中的每个 API 更改是很棘手的。

我们欢迎社区为代码片段做出贡献。这是一个我们拥有片段的框架矩阵。请帮助我们为你们喜欢的框架添加代码片段。

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

片段语法

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

示例

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

docs/_snippets/button-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 网站正在运行。打开浏览器窗口访问 https://:3000，点击 Docs 链接打开文档，然后从下拉菜单中选择你的框架。

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

提交你的贡献

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

故障排除

代码片段未显示

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

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

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