Loaders

Loaders 是非同步函數，用於為 story 及其裝飾器載入資料。Story 的 loaders 會在 story 渲染之前執行，並且載入的資料會透過其渲染上下文注入到 story 中。

Loaders 可用於載入任何資源、延遲載入元件，或從遠端 API 取得資料。此功能設計為效能優化，以處理大型 story 導入。然而，建議使用 args 來管理 story 資料。我們正在圍繞 Args 建構工具和技術生態系統，這些工具和技術可能與載入的資料不相容。

它們是一項進階功能（即，緊急出口），我們僅建議在您有其他方法無法滿足的特定需求時使用它們。

取得 API 資料

Stories 是隔離的元件範例，會渲染定義為 story 一部分或與 story 並列為 args 的內部資料。

當您需要從外部載入 story 資料時（例如，從遠端 API），Loaders 非常有用。請考慮以下範例，該範例取得一個 todo 項目以顯示在 todo 清單中

MyComponent.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { TodoItem } from './TodoItem';
 
/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.dev.org.tw/docs/api/csf
 * to learn how to use render functions.
 */
const meta: Meta<typeof TodoItem> = {
  component: TodoItem,
  render: (args, { loaded: { todo } }) => <TodoItem {...args} {...todo} />,
};
 
export default meta;
type Story = StoryObj<typeof TodoItem>;
 
export const Primary: Story = {
  loaders: [
    async () => ({
      todo: await (await fetch('https://jsonplaceholder.typicode.com/todos/1')).json(),
    }),
  ],
};

從遠端 API 呼叫取得的回應會合併到 story 上下文的 loaded 欄位中，這是 story 函數的第二個引數。例如，在 React 中，story 的 args 會先展開，以優先於 loader 提供的靜態資料。對於其他框架（例如，Angular），您可以像平常一樣撰寫 stories。

全域 loaders

我們也可以透過您的 .storybook/preview.js 檔案的 loaders 匯出設定所有 stories 的 loader（這是您設定所有 stories 的檔案）

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  loaders: [
    async () => ({
      currentUser: await (await fetch('https://jsonplaceholder.typicode.com/users/1')).json(),
    }),
  ],
};
 
export default preview;

在此範例中，我們載入一個「目前使用者」，所有 stories 都可以使用 loaded.currentUser 來存取。

Loader 繼承

與參數類似，loaders 可以全域定義、在元件層級定義，以及針對單個 story 定義（如我們所見）。

適用於 story 的所有層級定義的所有 loaders，都會在 storybook 的畫布中渲染 story 之前執行。

所有 loaders 並行執行
所有結果都是 story 上下文中的 loaded 欄位
如果存在重疊的鍵，「較晚」的 loaders 優先（從最低到最高）：
- 全域 loaders，依定義順序排列
- 元件 loaders，依定義順序排列
- Story loaders，依定義順序排列