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 - Vue、Angular

Doc Blocks - Vue、Angular