iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 23
1
Modern Web

玩轉 Storybook系列 第 23

玩轉 Storybook: Day 23 DocsPage and Doc Blocks

DocsPage 介紹

Storybook Docs 是預設的 Addons,不需要做設定就可以使用。它可以整合元件裡的Stories、文字描述、程式註解、參數表列及程式範例到一個頁面,每個元件基本上都會對應一個DocPage。

Component parameter

Storybook 使用 component 當做 Key,用以抓取元件的說明跟傳入值

// MyComponent.stories.js

import { MyComponent } from './MyComponent';

export default {
  title: 'MyComponent',
  component: MyComponent,
};
// your templates and stories

Subcomponents parameter

當希望把子元件也一起顯示在DocsPage上時,可以利用subcomponent把子元件列舉出來。

例如,ButtonGroup及Button

// ButtonGroup.stories.js

import { Button, ButtonGroup } from '../ButtonGroup';

export default {
  title: 'Path/to/ButtonGroup',
  component: ButtonGroup,
  subcomponents: { Button },
};

DocsPage就會把目前元件列為首要呈現的元件,可以指定一至多個子元件一起在DocsPage上顯示出來。子元件的參數表會顯示在主要呈現元件頁籤的旁邊,頁籤的名稱會對應subcomponents的物件名稱。

重置 DocsPage

如果要重新製作DocsPage,可以使用Parameter做覆寫,設定的層級可以是Story、Component跟Global。

Story-level

  • 設定 特定 Story 沒有文件
// Button.stories.js

export const Primary = Template.bind({});
Primary.parameters = { docs: { page: null } };

這樣的話,Primary會顯示 No Doc,但切換到其他Story,在Docs Addon Pannel 還是會顯示出來。

  • 設定 特定 Story 顯示 Source Code
// Button.stories.js
export const Primary = Template.bind({});
Primary.parameters = {
  docs: { 
    source: {code: 'Some custom string here'}    
  },
};

Component-level

設定 Component 沒有文件

// Button.stories.js
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
  ...
  parameters: { docs: { page: null } },
};

Global-level

設定 Storybook 所有的 Component 都沒有文件

// .storybook/preview.js
export const parameters { docs: { page: null } });

使用 Doc Blocks 重置

DocsPage 是由一組 Doc Blocks 組成。簡易的客製化 DocsPage,就是將 Doc Blocks 做重新排序、增加或忽略不列入。

來看看一個重製 DocsPage 的範例

// Button.stories.js
import {
  Title,
  Subtitle,
  Description,
  Primary,
  ArgsTable,
  Stories,
  PRIMARY_STORY,
} from '@storybook/addon-docs/blocks';

import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    docs: {
      page: () => (
        <>
          <Title />
          <Subtitle />
          <Description />
          <Primary />
          <ArgsTable story={PRIMARY_STORY} />
          <Stories />
        </>
      ),
    },
  },
};

以下是可以設置的Doc Blocks,如果需要的話,可以自行排列Block的順序。

  • <Title />

用以顯示目前文件的 Title

title: 'Components/Button',

也可以接受用 Slot 的方式去設定

<Title>Custom Title</Title>
  • <Subtitle>

用以顯示 parameters.componentSubtitle 的設定文字,也可以接受用 Slot 的方式去設定

  • <Description />

用以顯示 parameters.doc.description.component|story 的設定文字

export default {
  title: 'CustomDescription'
  parameters: {
    docs: { 
      description: { 
        component: 'Component Description' 
      } 
    },
  }
};
export const WithStoryDescription = Template.bind({});
WithStoryDescription.parameters = {
  docs: { 
    description: { 
      story: 'Story Description' 
    } 
  },
};

也可以接受用 Slot 的方式去設定

<Description>Custom Description</Description>
  • <Primary />

顯示第一個(Primary)設定的 Story

  • <ArgsTable />

顯示 Primary Story 的 傳入參數列表

  • <Stories />

顯示除了 Primary Story 以外的 Stories,此區塊的標題預設出現Stories字樣,可以指定title去覆蓋

<Stories title="Stories title" />

Next

如果想要更複雜的文件製作,可以使用下一個單元要介紹的 MDX 來製作。

Reference

DocsPage - VueAngular

Doc Blocks - VueAngular


上一篇
玩轉 Storybook: Day 22 Construct a screen - Angular
下一篇
玩轉 Storybook: Day 24 MDX
系列文
玩轉 Storybook30

尚未有邦友留言

立即登入留言