Storybook Docs 配方實戰(zhàn)指南CSF 與 MDX 組合模式、文檔頁定制與關鍵參數(shù)詳解【免費下載鏈接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation項目地址: https://gitcode.com/GitHub_Trending/st/storybook本文基于 Storybook 倉庫中 Docs 插件自帶的官方配方文檔 recipes.md系統(tǒng)講解在 Storybook Docs 體系下如何組合 CSFComponent Story Format與 MDX 兩種故事描述機制以及如何通過docs參數(shù)族docs.disable、docs.container、docs.source.transform、viewMode等定制文檔頁的呈現(xiàn)方式。讀完本文你可以為項目選擇合適的故事/文檔組織模式并掌握文檔頁級別的描述提取、源碼展示轉換與容器覆蓋等進階配置。Docs 插件的兩套基礎機制Docs 插件 由兩個基礎機制構成DocsPage零配置自動生成文檔頁和 MDX用富文本語法書寫文檔與故事。核心問題在于它們各自適合什么場景又該如何組合官方配方文檔給出的答案是——存在多種合法組合且每種組合有明確的適用邊界。配方一CSF DocsPage推薦主用法Component Story Format 是一種便捷、可移植的故事寫法而 DocsPage 是零配置即可為 CSF 故事生成富文檔頁面的機制。兩者結合是 Storybook Docs 的首要使用場景你只需按標準 CSF 編寫.stories.js文件文檔頁包含 Canvas、Args 表格、Source 代碼塊、故事列表即自動生成無需任何額外配置。如果你想在 Storybook 中穿插長篇文檔例如在故事列表開頭放置一頁設計系統(tǒng)介紹和安裝說明官方建議單獨編寫 Documentation-only 的 MDX 文件而不是硬塞進組件故事文件。配方二純 MDX StoriesMDX 是 CSF 之外的另一種故事語法允許把故事和文檔寫在同一個文件里。配方文檔明確指出凡是 CSF 能做的事MDX 都能做并且兩者在構建層面暴露的是相同的模塊接口文件可以互相替換。一些團隊選擇用 MDX 編寫全部 Storybook 內容。組合模式CSF 故事 MDX 文檔如果你希望故事邏輯用 CSF 寫、文檔用 MDX 寫標準做法是讓 MDX 文件成為該組件的真正“故事文件”。Button.stories.jsimport React from react; import { Button } from ./Button; // 注意不再有 default export因為 Button.stories.mdx 現(xiàn)在是 Button 的故事文件 // // export default { // title: Demo/Button, // component: Button, // }; export const basic () ButtonBasic/Button; basic.parameters { foo: bar, };Button.stories.mdximport { Meta, Story } from storybook/addon-docs; import * as stories from ./Button.stories.js; import { Button } from ./Button; import { SomeComponent } from path/to/SomeComponent; Meta titleDemo/Button component{Button} / # Button 我可以用從 CSF 導入的函數(shù)來定義故事 Story story{stories.basic} / 并且可以在這個文件中嵌入任意的 markdown 與 JSX。 SomeComponent prop1val1 /這套組合的工作機制如下故事定義在 CSF 文件中但由于同名的Button.stories.mdx存在CSF 文件不再被直接注冊為獨立的故事列表原文檔以includeStories: []機制解釋這一點故事實際經(jīng)由 MDX 中的Story story{}塊呈現(xiàn)CSF 中命名導出的故事保留其故事級 decorators、parameters、args 標注且Story story{}構造會尊重這些標注例如basic.parameters中定義的foo: bar仍然生效原本掛在Button.stories.jsdefault export 上的組件級 decorators、parameters 等不會自動繼承如需要必須手動拷貝到 MDX 的Meta中。組合模式CSF 任意 MDX官方推薦上面的“CSF MDX Docs”作為標注 CSF 故事的最優(yōu)方式但如果只是想引用任意 markdown 文件作為文檔頁還有第二種選擇。Button.mdximport { Story } from storybook/addon-docs; import { SomeComponent } from somewhere; # Button 我可以嵌入一個已有的故事但不能定義新故事因為這個文件里不應該有 Meta Story idsome--id / 并且可以嵌入任意 markdown 與 JSX。 SomeComponent prop1val1 /Button.stories.jsimport React from react; import { Button } from ./Button; import mdx from ./Button.mdx; export default { title: Demo/Button, parameters: { docs: { page: mdx, }, }, component: Button, }; export const basic () ButtonBasic/Button;這里有一個與上文截然不同的關鍵點MDX 文件后綴是.mdx而非.stories.mdx。這個區(qū)別意味著該文件走的是默認 MDX loader而不是 Storybook 的 CSF loader由此帶來三條約束文件中不應提供Meta聲明只能引用已有故事Story id...不能定義新故事不能用Story name...文檔以 MDX 的 default export 形式導出并通過docs.page參數(shù)掛載而不是像 CSF 那樣作為 default export 參數(shù)的一部分。這一點在插件的類型定義中有直接印證docs.page被聲明為“用你自己的組件替換 Storybook 默認文檔模板”的選項類型為ComponentType見 types.ts?；旌?storiesOf 與 CSF/MDX如果項目中還有一批使用storiesOf舊 API 的故事或者存在只能用storiesOf實現(xiàn)的故事例如動態(tài)生成的故事需要與 CSF/MDX 共存。configure的第一個參數(shù)可以是require.context返回的req、req數(shù)組或者一個 loader 函數(shù)loader 函數(shù)要么返回 null要么返回一個“全部包含 default export”的模塊導出數(shù)組configure依據(jù) default export 來識別并加載 CSF/MDX 文件。一個假設“storiesOf 文件都不含 default export”的樸素實現(xiàn)如下const loadFn () { const req require.context(../src, true, /\.stories\.js$/); return req .keys() .map((fname) req(fname)) .filter((exp) !!exp.default); }; configure(loadFn, module);官方說明他們可以把這個啟發(fā)式邏輯內置進 Storybook但無法假設你的storiesOf文件沒有 default export。如果確實有需要用別的方式比如按文件名過濾。若不過濾會看到顯式報錯Loader function passed to configure should return void or an array of module exports that all contain a default export官方特意讓這個報錯顯式化以提醒你正在混合storiesOf與 CSF/MDX。從 notes/info 插件遷移自定義描述提取如果項目此前使用 notes/info 插件給每個組件掛了notes參數(shù)markdown 文本遷移到 Docs 插件時可以自定義docs.extractComponentDescription參數(shù)把notes內容提取到文檔頁頂部的 Description 區(qū)域。假設你希望notes顯示在Description插槽頂部可以在.storybook/preview.js中加入import { addParameters } from storybook/preview-api; addParameters({ docs: { extractComponentDescription: (component, { notes }) { if (notes) { return typeof notes string ? notes : notes.markdown || notes.text; } return null; }, }, });從源碼看Description 塊的渲染邏輯正是調用這個可插拔函數(shù)在 Description.tsx 中組件描述和故事描述均通過parameters.docs?.extractComponentDescription?.(component, { ... })動態(tài)計算參數(shù)為可選鏈調用未提供時回退到默認行為。docs preset 的默認extractComponentDescription從組件源碼中提取 JSDoc 注釋作為描述并忽略第二個參數(shù)當前選中故事的故事 parameters而上例則相反——忽略注釋、改用該故事的notes參數(shù)。倉庫中自帶的文檔故事也演示了最簡單的形式見 extract-description.stories.ts直接extractComponentDescription: () component description返回固定字符串。導出純文檔站點Storybook 的 UI 是“組件開發(fā)工作臺”而 Docs 是“文檔展示櫥窗”。開發(fā)時兩種模式并排查看很有用但導出靜態(tài)站點時可能希望只保留文檔頁以減少冗余。為此 Storybook 提供了 CLI 標志yarn storybook build --docs注意原始配方文檔寫作于 Storybook 5.2 時期當時該標志被標記為實驗特性5.3 中行為可能不受 semver 約束地變化。在當前倉庫所處的版本線中它已成為 docs 構建的常規(guī)選項適用前提是你的文檔頁由 docs 插件DocsPage 或 MDX驅動。禁用文檔中的故事docs.disable有兩類場景需要把某些故事從文檔頁中排除。DocsPage 場景故事用 CSF 定義、用 DocsPage 渲染文檔但希望排除部分故事以減少頁面噪音export const foo () Buttonfoo/Button; foo.parameters { docs: { disable: true } };MDX 場景在單個 MDX 文件中并排寫文檔與故事希望故事出現(xiàn)在 Canvas 中但不進入文檔頁相當于“CSF stories with MDX docs”的純 MDX 版本Story namefoo parameters{{ docs: { disable: true } }} Buttonfoo/Button /Story參數(shù)類型上docs.disable被聲明為boolean語義是“移除該插件面板并禁用其行為”見 types.ts?？刂乒适碌囊晥D模式viewModeStorybook 默認的導航行為是保持當前視圖模式用戶處于 docs 模式時點擊另一個故事仍以 docs 模式打開處于 story 模式UI 中的 canvas時則保持 story 模式例外docs-only 頁面永遠以 docs 模式顯示。基于用戶反饋可以用viewMode故事參數(shù)控制單個故事進入時強制切換的視圖模式。以下示例保證導航到該故事時視圖模式重置為 storyexport const Foo () Component /; Foo.parameters { // 用戶導航到該故事時始終把視圖模式重置為 story viewMode: story, };也可以在.storybook/preview.js中全局生效// 用戶導航時始終把視圖模式重置為 docs export const parameters { viewMode: docs, };調整 Docs 標簽頁順序previewTabs用previewTabs故事參數(shù)可以配置 preview 區(qū)域的標簽頁順序。把Docs標簽排到最前面export const Foo () Component /; Foo.parameters { previewTabs: { storybook/docs/panel: { index: -1 } }, };同樣可全局寫在.storybook/preview.js中。定制源碼展示docs.source.code 與 docs.source.transform從 SB 6.0 起定制 Docs 源碼展示有兩條互補的路徑覆蓋docs.source.codeSource 塊直接渲染你提供的字符串適合故事級的精確控制const Example () Button /; Example.parameters { docs: { source: { code: some arbitrary string } }, };提供docs.source.transform函數(shù)適合全局格式化。以下示例全局剝掉“返回字符串的箭頭函數(shù)”外殼() \...const SOURCE_REGEX /^\(\) (.*)$/; export const parameters { docs: { source: { transform: (src, storyContext) { const match SOURCE_REGEX.exec(src); return match ? match[1] : src; }, }, }, };插件的源類型定義明確了 transform 的簽名(code: string, storyContext: any) string | Promisestring即允許同步或異步轉換見 types.ts。同一配置塊中還支持typeauto | code | dynamic默認auto、formattrue/dedent或任意 prettier parser 名、language等選項詳見 types.ts。兩種方法互補前者適合故事級覆蓋后者適合全局格式化處理。覆蓋文檔容器docs.container當你想給 MDX 頁面包一層 wrapper 或注入 React context例如styled-components的ThemeProvider時需要注意decorator 只作用于故事而 MDX 中Story塊之外的任意 JSX 不受 decorator 影響此時必須使用docs.container參數(shù)。container是 Docs 體系中與 decorator 最接近的概念——一個包裹在被渲染頁面外圍的元素。官方示例給頁面加一圈紅色實線邊框。它復用了 Storybook 默認的頁面容器負責搭建各類 context 與內部機制然后在該容器與頁面內容之間插入自定義邏輯import { Meta, DocsContainer } from storybook/addon-docs; Meta titleAddons/Docs/container-override parameters{{ docs: { container: ({ children, context }) ( DocsContainer context{context} div style{{ border: 5px solid red }}{children}/div /DocsContainer ), }, }} / # Title 文件的其余部分...styled-components主題場景下的典型用法import { Meta, DocsContainer } from storybook/addon-docs; import { ThemeProvider } from styled-components; import { theme } from ../path/to/theme; Meta titleAddons/Docs/container-override parameters{{ docs: { container: ({ children, context }) ( DocsContainer context{context} ThemeProvider theme{theme} {children} /ThemeProvider /DocsContainer ), }, }} / # Title 文件的其余部分...實現(xiàn)層面自定義容器的類型為ComponentTypeDocsContainerProps見 types.ts默認容器實現(xiàn)位于 DocsContainer.tsx。自定義container的推薦模式是包裹默認DocsContainer以保留其提供的上下文與內部邏輯而不是完全替換它。為單個故事添加描述docs.description.story在docs.description參數(shù)中加入story字段即可為單個故事添加描述支持 markdown 語法const Example () Button /; Example.parameters { docs: { description: { story: Individual story description, may contain markdown markup, }, }, };配方文檔還提到存在第三方 webpack loaderstory-description-loader可從 JSDoc 注釋中提取描述屬于原文檔時代的生態(tài)補充當前使用時需自行確認其對新版本 Storybook 的兼容性。延伸閱讀參考文檔本倉庫內README / DocsPage / MDX / FAQ / Theming / Props 表格參數(shù)類型定義code/addons/docs/src/types.tsDocsParameters.docs全量字段argTypes、canvas、codePanel、controls、container、description、disable、page、source、story、stories、subtitle、lang、theme、title、toc默認描述提取與自定義示例Description.tsx / extract-description.stories.ts各框架的 Docs 文檔見 code/renderers/react、code/renderers/vue3 等框架渲染器目錄下的配套說明以上配方均直接取自倉庫中的官方文檔 code/addons/docs/docs/recipes.md其中的參數(shù)簽名與行為可通過 code/addons/docs/src/types.ts 的類型定義和 code/addons/docs/src/blocks/blocks 下的塊實現(xiàn)逐一驗證?！久赓M下載鏈接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation項目地址: https://gitcode.com/GitHub_Trending/st/storybook創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考