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 網站。出現提示時，提供 Storybook monorepo 本機 fork 的路徑以及您正在處理的文件版本。

npm run sync-docs

最後，開啟一個新的終端機視窗並執行 dev 命令以啟動 Storybook 網站。

npm run dev

如果一切順利，您應該會看到 Storybook 網站正在運行。開啟瀏覽器視窗至 http://localhost:3000，點擊「文件」連結以開啟文件，然後從下拉選單中選取您的框架。

瀏覽文件並檢查您的工作。

提交您的貢獻

一旦您驗證您的變更如預期般運作，您就可以建立「提取請求」。這將讓 Storybook 維護人員知道您有一些變更要提出。此時，我們可以給您回饋並要求變更。為了協助審查流程，我們鼓勵您新增清晰的標題和工作描述。

疑難排解

程式碼片段未顯示

如果您要記錄的範例包含 packageManager 屬性，並與另一個範例結合使用，則文件可能無法正確顯示程式碼片段。為了避免這種情況，您可以將範例分成不同的檔案，並在文件中引用它們。

深入了解如何貢獻 Storybook

  • RFC 流程，用於撰寫功能請求
  • 程式碼，用於功能和錯誤修復
  • 框架，開始使用新的框架
  • 文件，用於文件改進、錯字和澄清
  • 新程式碼片段的範例
此頁面是否實用？
✍️ 在 Github 上編輯