元件故事格式 3 登場

故事以視覺化方式呈現元件在不同情境下的行為。元件故事格式 (CSF) 是故事的通用檔案格式。

元件故事格式 3 標誌著故事的演進，它減少了樣板程式碼並提高了人體工學。這使得故事更加簡潔且撰寫速度更快。

我很興奮地宣布 CSF3 的完整發布。在 18 個月的 測試期間，社群幫助我們發現問題並改進格式。從 Storybook 7 開始，CSF3 將成為撰寫故事的預設方式。

改進之處包括

• ♻️ 可擴展的故事物件，方便輕鬆擴展故事
• 🌈 簡潔的預設渲染函數
• 📓 方便的自動標題
• ▶️ 用於腳本化互動和測試的播放函數
• ✅ 100% 向後相容於 CSF 2

繼續閱讀以了解更多關於此格式、自最初公告以來發生的變更，以及如何在 Storybook 7 中充分利用它。

等等，為什麼？

在應用程式之外開發 UI 元件是建立高品質元件的最佳方法。Storybook 開創了這種元件驅動開發 (CDD) 的風格。

現在，故事不僅用於設計師和產品經理的視覺檢閱，還用於設計系統文件、自動化測試，甚至可以從生產元件產生設計資產。

難怪 Storybook 被用於在 Shopify、IBM 和 Salesforce 建立世界上許多最受歡迎的 UI。

CSF3 是故事的下一個演進階段，它更容易撰寫和維護

與其前身非常相似，CSF3 也基於 ESM。預設匯出包含有關元件的資訊，而一個或多個具名匯出 (故事) 則捕捉不同的元件狀態。主要區別在於故事現在是物件，您可以將播放函數附加到每個故事以模擬使用者互動。

CSF3 完全向後相容於 CSF2，Storybook 7 仍然支援 CSF2。我們甚至將播放函數反向移植到 CSF2。

我們建議您遷移，因為 CSF3 更具表達性和可維護性，而且您所需的樣板程式碼更少。在大多數情況下，您可以使用程式碼修改工具自動從 CSF 2 遷移到 3。

CSF3 功能回顧

大型專案可能包含數百個元件和數千個故事。當您撰寫這麼多故事時，人體工學的改進會帶來明顯的生活品質改善。我們的目標是簡化故事格式，使撰寫、閱讀和維護故事更容易。

讓我們看看 CSF3 在假設的 RegistrationForm 元件中的樣子。

預設匯出聲明您正在為其撰寫故事的元件

// RegistrationForm.stories.js

import { RegistrationForm } from './forms/RegistrationForm';

export default {
  title: 'forms/RegistrationForm',
  component: RegistrationForm,
};

故事現在是物件

export const EmptyForm = {
  render: (args) => <RegistrationForm {...args} />,
  args: { /* ... */ },
  parameters: {  /* ... */ },
};

簡潔的預設渲染函數。 90% 的時間，撰寫故事只是以標準方式將一些輸入傳遞給您的元件。

在 CSF3 中，如果您沒有指定渲染函數，則每個故事都會渲染元件並傳入所有參數。這大大簡化了您的程式碼。

在我們的 RegistrationForm 範例中，渲染函數是樣板程式碼

export const EmptyForm = {
  // render: (args) => <RegistrationForm {...args} />, -- now optional!
  args: { /* ... */ },
  parameters: {  /* ... */ },
};

可重複使用的故事物件。 當您嘗試對複雜狀態建模時，能夠擴展現有故事而不是重新撰寫它們非常有用。假設您想要顯示填寫完成的表單，但在不同的視窗中顯示

export const FilledForm = {
  args: {
    email: 'marcus@acme.com',
    password: 'j1287asbj2yi394jd',
  }
};

export const FilledFormMobile = {
  ...FilledForm,
  parameters: {
    viewports: { default: 'mobile' }
  },
};

用於腳本化互動的播放函數。 有些 UI 狀態在沒有使用者互動的情況下無法捕捉。播放函數會在故事渲染後執行，並使用 testing-library 來模擬使用者互動。例如

// RegistrationForm.stories.ts|tsx
import { userEvent, within } from '@storybook/testing-library';

// ...

export const FilledForm = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    const emailInput = canvas.getByLabelText('email', { 
        selector: 'input' 
    });
    await userEvent.type(emailInput, 'example-email@email.com', { 
        delay: 100 
    });

    const passwordInput = canvas.getByLabelText('password', { 
        selector: 'input' 
    });
    await userEvent.type(passwordInput, 'ExamplePassword', { 
        delay: 100 
    });

    const submitButton = canvas.getByRole('button');
    await userEvent.click(submitButton);
  },
};

方便的自動標題。 在 CSF 中，故事的標題決定它在 UI 中導覽階層中的顯示位置。在 CSF3 中，標題可以根據檔案相對於根目錄的位置自動產生。減少了輸入，並且如果您重新排序檔案，則無需更新任何內容。

export default {
  // title: 'forms/RegistrationForm' -- optional
  component: RegistrationForm,
};

如需深入了解 CSF3 的功能和原理，以及它與 CSF2 的確切差異，請參閱原始 CSF3 文章。

對原始版本的變更

在過去的一年半中，使用者一直在他們的專案中測試 CSF3。根據回饋，我們對原始版本進行了一些變更。

更好的 TypeScript 類型。 我們已在 7.0 中更新了 Meta/Story 類型，以支援故事的類型安全和自動完成。請繼續關注未來幾週有關此內容的專題文章。

更新的自動標題啟發法。 自動標題會根據 CSF 檔案的磁碟位置產生「標題」(Storybook 側邊欄中的路徑)。例如，如果 /project/path/src 是故事根目錄，則 /project/path/src/atoms/Button.stories.js 的標題會是 atoms/Button。但是，簡單的啟發法無法處理像 atoms/Button/Button.stories.js 或 atoms/Button/index.stories.js 這樣的常見模式。我們更新了啟發法以解決此問題。如需完整的遷移說明和多項其他自動標題改進，包括更好的首碼處理和大小寫，請參閱 MIGRATION.md。

升級的文件和 CLI 範本。 最後但同樣重要的是，我們已使用 CSF3 原始碼程式碼片段升級了 7.0 的官方文件。我們也已更新 CLI，以產生新專案的 CSF3。

立即升級到 CSF3

CSF3 完全向後相容，因此您現有的 CSF 故事仍然可以正常運作，無需修改。我們不會很快棄用舊格式。但是，CSF3 是向前邁進的一大步，我們建議您升級到 Storybook 7.0 (SB7) 時升級您的故事。

如需升級到 SB7，請參閱我們的SB7 遷移指南。升級專案後，您可以選擇使用下列程式碼修改工具將 CSF 故事遷移到 CSF3。請務必更新 glob，以包含您要更新的檔案。

npx storybook@next migrate csf-2-to-3 --glob="**/*.stories.js"

如果您無法使用程式碼修改工具，我們也有可用的升級說明。

參與其中

元件故事格式 (CSF) 可協助您獨立開發、測試和記錄您的元件。CSF3 帶來了改進的人體工學，可幫助您更輕鬆地撰寫更多故事。

CSF3 由Michael Shilman（我！）、Kasper Peulen、Tom Coleman 和Pavan Sunkara 開發，並由整個 Storybook 社群提供測試和回饋。

Storybook 是超過 1600 位社群提交者的產品。請加入我們的 GitHub 或在 Discord 上與我們聊天。最後，請在 Twitter 上追蹤 @storybookjs 以取得最新消息。