[Day12] Storybook - Writing Docs

DocsPage

DocsPage 是由 Storybook Docs 所提供的页面，无需任何的设定自动就会从 Stories 和元件中的 props, emits、slots 甚至是注解 (没错就是注解) 中解析聚合出基本的预设文档。

Storybook Docs 包含在 Essential Addons 中，所以用 CLI 建立的专案都会预设含有 Storybook Docs。

ArgsTable

如果有看过上一篇 Storybook - Controls 的朋友一定会注意到， DocsPage 中的 ArgsTable 和 Controls 面板非常相似，因为事情上他们背後是使用相同的运作原理，所以 argsType 的设定会同时在 Controls 面板中以及 DocsPage 出现。

Customizing

ArgsTable 的内容预设是从元件以及 Story 中自动推断出来的，但 Storybook 也提供我们一些属性可以自己定义内容来让文件更丰富。

栏位	说明
name	属性名称
type.required	是否为必填属性，是的话会出现红色星号
description	属性说明
table.category	属性的分类
table.subcategory	属性的子分类
table.type.summary	属性类型的简短描述
table.type.detail	属性类型的描述
table.defaultValue.summary	属性预设值的简短描述
table.defaultValue.detail	属性预设值的描述

control | 查看完整列表

其中我特别挑 category 和 subcategory 出来说明，我们可以将类似的 args 分门别类，甚至细到可以再分一层子类别。

import MyButton from './Button.vue'

export default {
  title: 'Example/Button',
  component: MyButton,
	argTypes: {
	  backgroundColor: {
	    control: 'color',
	    table: {
	      category: 'Colors'
	    }
	  },
	  primary: {
	    table: {
	      category: 'Colors'
	    }
	  },
	  label: {
	    table: {
	      category: 'Text',
	      subcategory: 'Label'
	    }
	  },
	  size: {
	    table: {
	      category: 'Text',
	      subcategory: 'Size'
	    },
	    control: {
	      type: 'select',
	      options: ['small', 'medium', 'large']
	    }
	  },
	  click: {
	    table: {
	      category: 'Events'
	    }
	  }
	}
}

Description

我们可以为整份 DocsPage 写上补充说明

import MyButton from './Button.vue'

export default {
  title: 'Example/Button',
  component: MyButton,
  parameters: {
    docs: {
      description: {
        component: 'This is Button\'s description.',
      }
    }
  },
  ...
}

Subcomponents parameter

有些元件可能会在包裹着子元件，这时如果要想要将他们一起显示在同一个 DocsPage 中，可以透过subcomponents 属性。

// src/stories/Header.stories.js

import MyHeader from './Header.vue';
import MyButton from './Button.vue';

export default {
  title: 'Example/Header',
  component: MyHeader,
  subcomponents: { MyButton }
};