Storybook 使用手册——MDX 和 Doc Blocks

https://images.unsplash.com/photo-1512850183-6d7990f42385?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb

MDX

MDX是一种标准的文件格式,由Markdown和JSX组合而成,文件后缀是.mdx。也就是说你可以在MDX中使用Markdown的语法编写内容,同时还能嵌入JSX编写的组件。

可以用MDX编写纯粹的文档,把文档和Story一起添加到Storybook中。

13275119dcbdc3ff

Doc Blocks

顾名思义,就是文档中的块。一个Story渲染成的文档就是由若干个Block组成的。在Storybook中有不少Block。常见的可能是ArgsTable,Canvas和Story。

ArgsTable

Story自动识别组件的Props,自动生成一个表格。表格中会列出这些参数,同时还提供了可交互的参数控制

3e0260e90f120a2a

image

Canvas

提供包含了一个控制条的可交互的画板,内部包含了Source这个Block,用于展示代码

47de4f4b9bcdbcbc

更多Block的信息可以参考这里

MDX的简单例子

<!-- Checkbox.stories.mdx --> import { Canvas, Meta, Story } from '@storybook/addon-docs'; import Checkbox from './Checkbox.vue'; <Meta title="MDX/Checkbox" component={Checkbox} /> export const Template = (args, { argTypes }) => ({ props: Object.keys(argTypes), components: { Checkbox }, template: '<Checkbox v-bind="$props" />', }); # Checkbox With `MDX`, we can define a story for `Checkbox` right in the middle of our Markdown documentation. <Canvas> <Story name="Unchecked" args={{ label: 'Unchecked', }}> {Template.bind({})} </Story> <Story name="Checked" args={{ label: 'Unchecked', checked: true, }}> {Template.bind({})} </Story> <Story name="Secondary" args={{ label: 'Secondary', checked: true, appearance: 'secondary', }}> {Template.bind({})} </Story> </Canvas>

最终会渲染在Storybook中,可以在页面的Docs中查看

1e4355e529bab949

可以看到,使用了@storybook/addon-docs 提供的几个组件:

  • Meta: 用于描述当前组件文档页面的信息

  • Canvas:绘制Story渲染使用的画板

  • Story:创建一个Story

Story中用于配置的各项参数,都可以做为这几个组件各自的Props传入。比如,使用CSF文件时,我们这么写:

// Checkbox.stories.js|jsx|ts|tsx import { Checkbox } from './Checkbox'; export default { /* 👇 The title prop is optional. * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading * to learn how to generate automatic titles */ title: 'Checkbox', component: Checkbox, }; const Template = (args) => ({ //👇 Your template goes here }); export const Unchecked = Template.bind({}); Unchecked.args = { label: 'Unchecked', };

在使用MDX编写时,则是如下:

<!-- Checkbox.stories.mdx --> import { Canvas, Meta, Story } from '@storybook/addon-docs'; import Checkbox from './Checkbox.vue'; <Meta title="MDX/Checkbox" component={Checkbox} /> export const Template = (args, { argTypes }) => ({ props: Object.keys(argTypes), components: { Badge }, template: '<Badge v-bind="$props" />', }); <Story name="Unchecked" args={{ label: 'Unchecked', }}> {Template.bind({})} </Story>

单纯的MDX文件

通常,在使用Storybook MDX时,在MDX中定义Story,而文档会自动与这些Story关联。

也可以编写不包含Story的MDX文档,将其与现有的Story相关联,或者将这个MDX作为文档节点嵌入Storybook的导航中。

d3b4d3de6cfe0c1a

MDX编写的方式和普通markdown大同小异,也是非常简单。

结束语

到目前为止,Storybook编写文档的基本方式已经介绍得差不多了。接下来将从一个组件库出发,演示如何使用Storybook,从零搭建一个文档站点。