Skip to content

Storybook 使用手册——MDX 和 Doc Blocks

Posted on:2022-04-24 11:00

MDX

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

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

Doc Blocks

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

ArgsTable

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

image

Canvas

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

更多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中查看

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

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的导航中。

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

结束语

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