简介

StoryBook是一款开源的Web应用开发工具，允许开发者浏览组件库、查看组件不同状态、交互地开发和测试组件，能够帮助开发者快速构建组件说明文档，能够帮助使用者快速准确地了解组件的功能与使用。

本文将介绍基于StoryBook+Vue2+Echarts构建一个看板组件库，主要阐述如何在已有Vue项目中引入StoryBook进行组件文档的构建，详细介绍请参考SotryBook官网。

安装与配置

1. 安装与启动

在已有或新建一个Vue项目，在控制台执行如下命令：

npx sb init

上述命令正常执行完成后，会在项目根目录下生成.storybook文件夹、src目录下生成.stories文件，表示安装成功：

运行如下命令启动StoryBook（StoryBook会自带几个简单的组件示例）：

npm run storybook

启动成功之后，默认打开首页（这个页面是我自定义的，默认是StoryBook相关信息）：

2. 基本配置

1）修改.stories文件存放位置

在src同级目录下创建storybook文件夹，存放.stories.js（组件文档实例）相关文件，并修改main.js中stories的配置路径，否则在打包发布的时候，会报错，提示无法识别.stories.js相关文件：

"stories": [
    "../storybook/**/*.stories.mdx",
    "../storybook/**/*.stories.@(js|jsx|ts|tsx)"
  ],

2）修改界面视图配置

storybook内置工具栏包括canvas（缩放组件、设置背景、尺寸及方向）和docs（查看组件文档，从组件代码自动推断）。

看板组件库更侧重于查看组件文档，说明其属性、事件和使用，所以选择隐藏掉canvas栏，在.storybook/.preview.js文件中进行相关配置：

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
  viewMode: 'docs', // 显示文档视图
  previewTabs: {
    canvas: { // 隐藏canvas tab
      hidden: true,
      disable: true
    }
  },
}

构建组件文档

一个SotoryBook组件文档包含两部分：基础模板、story（story的本质是不同状态的基础模板）：

import Annulus from '../../packages/annulus/src'

export default {
  title: 'Board/Annulus',
  component: Annulus,
  decorators: [() => ({ template: '<div style="minWidth: 300; minHeight: 300px"><story/></div>' })],
  argTypes: {}
}

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Annulus },
  template: `<annulus v-bind="$props" :style="style"/>`,
  data() {
    return {
      style: {
        background: '#172d8c',
        minWidth: '300px',
        minHeight: '300px'
      }
    }
  }   
})

export const 参数说明 = Template.bind({})
参数说明.args = {
  title: '标题',
  percentage: 60,
  backgroundColor: 'rgba(66, 66, 66, .3)',
  loopbackgroundColor: 'rgba(66, 66, 66, .1)',
  color: [
    {
      offset: 0,
      color: '#16CEB9'
    },
    {
      offset: 1,
      color: '#6648FF'
    }
  ]
}

export const 基础用法 = () => ({
  components: { Annulus },
  template: `
    <div>
      <annulus :percentage='percentage' :title='title' :backgroundColor="backgroundColor" :loopbackgroundColor="loopbackgroundColor" :color="color" :style="style" />
    </div>
  `,
  data() {
    return {
      style: {
        background: '#172d8c',
        minWidth: '300px',
        minHeight: '300px'
      },
      title: '环形图',
      percentage: 75,
      backgroundColor: 'rgba(66, 66, 66, .3)',
      loopbackgroundColor: 'rgba(66, 66, 66, .1)',
      color: [
        {
          offset: 0,
          color: '#FFB972'
        },
        {
          offset: 1,
          color: '#FF4040'
        }
      ]
    }
  } 
})
基础用法.parameters = {
  docs: {
    description: { 
      story: `绑定数据并指定标题背景色` 
    },
    source: {
      code: `
        <template>
          <annulus :percentage='percentage' :title='title' :backgroundColor='backgroundColor' :loopbackgroundColor='loopbackgroundColor' :color='color' />
        </template>

        <scirpt>
          export default {
            data() {
              title: '环形图',
              percentage: 75,
              backgroundColor: 'rgba(66, 66, 66, .3)',
              loopbackgroundColor: 'rgba(66, 66, 66, .1)',
              color: [
                {
                  offset: 0,
                  color: '#FFB972'
                },
                {
                  offset: 1,
                  color: '#FF4040'
                }
              ]
            }
          }
        </script>
      `
    }
  }
}

1. ArgTypes

ArgTypes是Storybook中用于指定Args行为的特性。通过指定一个参数的类型或者提供默认值，可以在渲染出来的组件中control其行为属性。argTypes 通常有两种呈现形式：自动推断和手动描述

1）自动推断

参数：在props中属性上方采用 "/** 参数的说明 */" 形式进行注释说明
插槽：在声明插槽的语句，即<slot name="slotName"/>的上方采用 "" 形式进行注释说明
事件：在触发父组件的函数语句，即this.$emit('事件名称')的上方采用 "/** 事件说明 */" 形式进行注释说明


 props: {
    /** 每隔多少秒刷新数据，默认30秒 */
    intervalTime: {
      type: Number,
      default: 30000
    },
    /** 标题 */
    title: {
      type: String,
      default: ''
    },
    dateParam: {
      type: String,
      default: ''
    }
  },

<!-- @slot 内容块的插槽 -->
<slot name="content"></slot>

 /** 每隔50000毫秒，会刷新的接口事件，重刷页面数据 */
 this.$emit('handleInitApi')

2）手动描述

const argTypes = {
  label: {
    name: 'label',
    type: { name: 'string', required: false },
    defaultValue: 'Hello',
    description: 'demo description',
    table: {
      type: { summary: 'string' },
      defaultValue: { summary: 'Hello' },
    },
    control: {
      type: 'text'
    }
  }
}

2.Decorators

Decorator是一种设计模式，把要被装饰的Story当做参数传入装饰器中，并加上额外的信息，赋予 Story 新的能力，而不需改动 Story 的本身。如Annulus组件在Docs中默认长、宽都是100%，可通过decorators限制Annulus的宽、高为300px：

export default {
  title: 'Board/Annulus',
  component: Annulus,
  decorators: [() => ({ template: '<div style="minWidth: 300; minHeight: 300px"><story/></div>' })],
  argTypes: {}
}

StoryBook构建组件文档

简介