简介

Storybook是一个UI组件的开发环境。

使用

初始化StoryBook环境

$ npx -p @storybook/cli sb init

storybook自动检测开发环境，安装依赖。

执行以上命令行会进行以下操作：

1. 自动生成以下目录结构：

├─.storybook // Storybook 全局配置文件
    ├─ main.js // 入口文件
    └─ preview.js // 页面展示、全局资源配置
└─stories // 示例代码
    └─assets

2. 更新pkg#run-scripts：

...
  "scripts": {
    "storybook": "start-storybook -p 6006 -h 0.0.0.0", // 启动本地服务以预览
    "build-storybook": "build-storybook"  // 构建
  },
...

核心文件

main.js

module.exports = {
  "stories": [  // 组件Stories目录所在 —— Storybook会载入配置路径下的指定文件渲染展示
    "../stories/**/*.stories.mdx",
    "../stories/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  "addons": [  // Storybook所用插件 —— Storybook功能增强
    "@storybook/addon-links",
    "@storybook/addon-essentials"
  ],
  "framework": "@storybook/vue3" // Storybook所用框架 —— Vue环境支持
}

该文件定义StoryBook与编译相关的配置。

preview.js

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  }
}

该文件引入全局依赖，定义StoryBook渲染相关的配置。

简单示例

入口配置

更新.storybook/main.js，将组件所在目录注册到入口文件声明中：

module.exports = {
  "stories": [  // 组件Stories目录所在 —— Storybook会载入配置路径下的指定文件渲染展示
    "../packages/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  ...
}

组件Story编写

import SubmitForm from "./index"; // 引入组件
import { SchemaType, RuleTrigger } from "./src/schemas/baseSchema";

const caseSchema = [ // 示例数据
  {
    key: "moduleName",
    name: "title",
    type: SchemaType.Text,
    label: "栏目名称",
    placeholder: "请输入栏目名称",
    attrs: {
      //
    },
    rules: [
      {
        required: true,
        message: "栏目名称必填~",
        trigger: RuleTrigger.Blur,
      },
    ],
  },
  ...
];

export default {
  title: "ui组件/SubmitForm", // 展示标题：使用路径定义命名空间 —— 分组、分类
  component: SubmitForm,
};

const Template = (args: any) => ({ // 渲染组件
  components: { SubmitForm },
  setup() {
    return {
      ...args,
    };
  },
  template: '',
});

export const 基本应用 = Template.bind({}); // 组件应用示例

(基本应用 as any).args = {
  schema: caseSchema,
  ref: "submitFormRef",
};

其中，

默认导出的是组件的元数据，包含归属组件、组件所属StoryBook文档分类、组件参数交互式声明...

更多配置参见：

ArgsTable配置

Contorl配置

命名导出的Story ( export const 基本应用 = Template.bind({}); ) 是一个函数，变量名为StoryBook文档展示的标题，另一种导出方式参考下文。

全局依赖配置

因为示例代码中依赖element-plus，通过上述展现的页面没有样式，所以，StoryBook渲染需要额外引入element-plus主题：

// .storybook/preview.js
import "element-plus/lib/theme-chalk/index.css";

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  }
}

启动本地服务

启动服务

更新pkg#storybook:

  // package.json
  "scripts": {
    "storybook": "start-storybook -p 6006 -h 0.0.0.0",
    "build-storybook": "build-storybook"
  },

命令行执行：

$ npm run storybook

效果展示

image

默认参数栏只展示两项，如需更多参数信息，修改 preview.js 文件：

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
  controls: {
    expanded: true // 展开所有参数信息
  }
}

image

在Stories中使用第三方UI库

以ElementPlus为例：

全局配置

如果 babel.config 没有配置按需加载，可直接编辑.storybook/preview.js：

// .storybook/preview.js
import elementPlus from 'element-plus';
import { app } from '@storybook/vue3'

app.use(elementPlus);
export const decorators = [
  (story) => ({
    components: { story, elementPlus },
    template: ''
  })
];
import "element-plus/lib/theme-chalk/index.css";

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  }
}

Notes：配置按需加载后，import elementPlus from 'element-plus';导入elementPlus报错：elementPlus is not defined —— 全局加载、按需加载不能在同一项目中使用。

按需加载

在需要使用ElementPlus的Stories中直接引入即可：

// SubmitForm.stories.ts
import { ElButton } from 'element-plus';
import SubmitForm from "./index";
import { SchemaType, RuleTrigger } from "./src/schemas/baseSchema";

const caseSchema = [
  {
    key: "moduleName",
    name: "title",
    type: SchemaType.Text,
    label: "栏目名称",
    placeholder: "请输入栏目名称",
    attrs: {
      //
    },
    rules: [
      {
        required: true,
        message: "栏目名称必填~",
        trigger: RuleTrigger.Blur,
      },
    ],
  },
  ...
];

export default {
  title: "ui组件/SubmitForm",
  component: SubmitForm,
};

const Template = (args: any) => ({
  components: { SubmitForm, ElButton },
  setup() {
    return {
      ...args,
    };
  },
  template: '提交',
});
export const 基本应用 = Template.bind({});
(基本应用 as any).args = {
  schema: caseSchema,
};

补充已有示例交互

// SubmitForm.stories.ts
import { ElButton } from "element-plus";
import { ref } from "vue";
import SubmitForm from "./index";
import { SchemaType, RuleTrigger } from "./src/schemas/baseSchema";

const caseSchema = [
  {
    key: "moduleName",
    name: "title",
    type: SchemaType.Text,
    label: "栏目名称",
    placeholder: "请输入栏目名称",
    attrs: {
      //
    },
    rules: [
      {
        required: true,
        message: "栏目名称必填~",
        trigger: RuleTrigger.Blur,
      },
    ],
  },
  ...
];

export default {
  title: "ui组件/SubmitForm",
  component: SubmitForm,
};
const Template = (args: any) => ({
  components: { SubmitForm, ElButton },
  setup() {
    const { refName } = args;
    const submitFormRef = ref();
    function submit() {
      console.log(submitFormRef.value.values);
    }
    function onRuntimeChange(name: string, value: any) {
      console.log(name, " = ", value);
    }
    return {
      submit,
      onRuntimeChange,
      [refName]: submitFormRef,
      ...args,
    };
  },
  template: `
      
      提交
    `,
});
export const 基本应用 = Template.bind({});

(基本应用 as any).args = {
  refName: "submitFormRef",
  schema: caseSchema,
};

这里做了两件事：

增加提交按钮
增加数据提交交互

配置参数文档

默认文档展示

默认查看到的文档是两栏展示：

image

更新 .storybook/preview.js 文件：

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
  controls: {
    expanded: true
  }
}

参数的所有配置都展示：

image

参数配置

通过配置argTypes可以补充参数信息：

// SubmitForm.stories.ts
...
export default {
  title: "ui组件/SubmitForm",
  component: SubmitForm,
  argTypes: {
    refName: {
      description: '表单组件引用',
      type: {
        required: true,
      },
      table: {
        defaultValue: {
          summary: 'defaultNameRef',
        }
      },
      control: {
        type: 'text'
      }
    },
    schema: {
      type: {
        required: true,
      },
      table: {
        type: {
          summary: '渲染表单所需JSON结构',
          detail: 'JSON结构包含表单渲染、交互所需要的必要字段，也包含表单的校验规则',
        },
        defaultValue: {
          summary: '[]',
          detail: `[
              {
                key: "moduleName",
                name: "title",
                type: SchemaType.Text,
                label: "栏目名称",
                placeholder: "请输入栏目名称",
                attrs: {
                  //
                },
                rules: [
                  {
                    required: true,
                    message: "栏目名称必填~",
                    trigger: RuleTrigger.Blur,
                  },
                ],
              }
            ]
          `
        }
      }
    },
    runtimeChange: {
      description: '实时监听表单的更新',
      table: {
        category: 'Events',
      },
    }
  }
};
...

更多相关配置见：

ArgsTable配置

Contorl配置

StoryBook功能模块

一个Story是以函数形式描述如何渲染组件的方式。

args提供动态参数，提供省时的便利：

参数可在Controls面板实时编辑，可检测组件在不同参数下的状态。
事件可在Actions面板查看日志输出。
- 需要配置actions

自定义Stories展示名称

命名模块

export const 自定义名称 = () => ({
  components: { Button },
  template: '

【推荐】storyName属性设定

export const Primary = () => ({
  components: { Button },
  template: '

https://storybook.js.org/docs/vue/get-started/setup

Args

提供交互动态修改Props、Slots、styles、inputs...的方式，允许在Storybook交互界面中实时编辑，不必改动底层组件代码。

通过Storybook交互界面指定Args

界面直接修改

通过URL设定Args

?path=/story/avatar--default&args=style:rounded;size:100

由于安全策略（XSS攻击）和特殊值，传入URL需要处理，见详情。

全局依赖

// .storybook/preview.js
import { app } from '@storybook/vue3';
import Vuex from 'vuex';

// Storybook Vue app being extended and registering the library
app.use(Vuex);

export const decorators = [
  (story) => ({
    components: { story },
    template: '',
  }),
];

静态资源访问

// .storybook/main.js

module.exports = {
  stories: [],
  addons: [],
  staticDirs: ['../public'],
};

或

// .storybook/main.js

module.exports = {
  staticDirs: [
     { 
        from: '../my-custom-assets/images', 
        to: '/assets' 
     }
  ],
};

查看更多配置

定制化主题

修改Logo

安装依赖：

npm i -D @storybook/addons @storybook/theming

修改pkg#scripts

// pkg#scripts
"storybook": "start-storybook -p 6006 -s public",
"build-storybook": "build-storybook -s public",

新建.storybook/manager.js文件：

import { addons } from "@storybook/addons";
import theme from "./themes/theme";

addons.setConfig({
  theme: theme
})

创建./storybook/themes/theme.js:

// .storybook/themes/theme.js
import { create } from '@storybook/theming';

export default create({
  base: 'light',
  brandTitle: 'Custom StoryBook', // logo不展示时，替代文本alt
  brandImage: '/logo.png',
});

Notes：brandImage和brandTitle同时配置的情况下，只有一项起作用，优先级brandImage > brandTitle

Notes：自定义主题时，base配置是必填的。

// package.json
{
  ...
  "scripts": {
    "replace": "rimraf storybook-static/favicon.ico && cpr .storybook/themes/favicon.ico storybook-static/favicon.ico",
    "storybook": "start-storybook -p 6006 -h 0.0.0.0",
    "build-storybook": "build-storybook && npm run replace"
  },
}

Notes：打包的话，需要用本地图标替换storybook包内的默认图标。

这里使用了Cli参数-s指定静态文件访问地址，更推荐在main.js中配置：

// .storybook/main.js

module.exports = {
  stories: [],
  addons: [],
  staticDirs: ['/public'],
};

修改站点Title、favicon

新增.storybook/manager-head.html:

参见更多配置

组件样式—Scss

组件样式需要storybook-addon的支持

npm i -D @storybook/preset-scss

修改.storybook/main.js

module.exports = {
  "stories": [
    "../packages/**/*.stories.@(js|jsx|ts|tsx)",
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/preset-scss"
  ],
  "framework": "@storybook/vue3"
}

Rem支持

替换@storybook/preset-scss为@storybook/addon-postcss:

npm uninstall -D @storybook/preset-scss
npm i -D @storybook/addon-postcss
# 修改webpack内核为版本5
# 初始化环境时修改
npx -y sb init --builder webpack5
# 初始化时未设定，后续修改
npm i -D @storybook/builder-webpack5
npm i -D @storybook/manager-webpack5

// 修改.storybook/main.js
module.exports = {
  "stories": [
    "../packages/**/*.stories.@(js|jsx|ts|tsx)",
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    {
      name: '@storybook/addon-postcss',
      options: {
        postcssLoaderOptions: {
          implementation: require('postcss'),
        },
        sassLoaderOptions: {
          implementation: require('sass'),
        }
      },
    }
  ],
  core: {
    builder: 'webpack5',
  },
  webpackFinal: (config) => {
    config.module.rules.push({
      test: /\.scss$/,
      use: ['style-loader', 'css-loader', 'postcss-loader', 'sass-loader'],
    });
    return config
  },
  "framework": "@storybook/vue3"
}

在preview.js中引入flexible.js，并定义视窗：

import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
import '../assets/js/flexible.all';
import './assets/stylesheets/sb.scss';
import '../assets/stylesheets/reset.scss';

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
  viewport: {
    viewports: INITIAL_VIEWPORTS, // newViewports would be an ViewportMap. (see below for examples)
    defaultViewport: 'iphone6',
  },
  controls: {
    expanded: true
  }
}

详细内容参见文章地址

同类对比

vue-styleguidist.github.io
vuepress

Decorator自定义画布、文档样式

Decorator通过包裹Story来增强其表现形式。
作用域：全局 > Component > Story（按执行顺序排列）

// js示例
export default {
  title: 'YourComponent',
  component: YourComponent,
  decorators: [() => ({ template: '' })],
};
// mdx示例
 ({
      template: '',
    }),
  ]}
/>

Decorator可在.storybook/preview.js、组件声明、Story声明中定义，最终会合并，执行顺序为 Global > Component > Story，可通过定义ClassName的命名空间来定制样式。

更多配置： https://storybook.js.org/docs/vue/writing-stories/decorators#wrap-stories-with-extra-markup

画布、文档的分离

默认文档中包含画布信息，若不想文档中渲染Story，需要写.stories.js和.stories.mdx两个文件
其中，.stories.js中默认导出不添加任何元数据，转移至.stories.mdx中，示例如下：

// *.stories.ts
export default {}
const Template = (args: any) => ({
  components: {
    Drawer
  },
  props: Object.keys(args),
  methods: {
    onClose: action('onClose'),
    onStretched: action('onStretched')
  },
  setup () {
    const state = reactive({
      ...args
    })
    function toogleVisible () {
      state.visible = true
    }
    return {
      state,
      toogleVisible
    }
  },
  template: `
    
    
    
  `
})
export const Primary = Template.bind({}) as any
(Primary as any).args = {
  visible: false,
  title: '示例'
}
Primary.parameters = { docs: { disable: true } };


// *.stories.mdx
import { Meta, Story } from '@storybook/addon-docs'
import { Primary } from './Drawer.stories.ts';
import Drawer from './index'
export const argsType = {
  visible: {
    description: '是否显示Dialog，支持.sync修饰符',
    type: {
      required: true
    },
    table: {
      type: {
        summary: 'Boolean'
      },
      defaultValue: {
        summary: false
      }
      // category: 'Boolean' // 参数分组
      // subcategory: 'Button colors', // 子分组
    },
    control: 'boolean'
  },
  ...
}
# Drawer

## 基本用法
 ({
      template: '',
    })
  ]}
  story={Primary} />

## 自定义内容

## 参数文档

parameters = { docs: { disable: true } }可在docs中禁止渲染Story
https://storybook.js.org/docs/vue/api/mdx#documentation-only-mdx
https://github.com/storybookjs/storybook/blob/master/addons/docs/docs/recipes.md#docspage
https://github.com/storybookjs/storybook/blob/master/addons/docs/docs/mdx.md#documentation-only-mdx

Notes：

mdx文件中jsx和markdown语法之间要用空行分隔；
jsx定义对象，尤其是空对象，不能有多余的空行；

export const argTypes = {

}
# 这样会报错

正确写法：

export const argTypes = {}

# 这样才能正确解析

侧边栏忽略子节点

若不想要侧边栏创建子节点，可以定义Story.storyName与export default的组件title保持一致：

// 示例
export default {
  title: '组件/Basic/Drawer'
}
export const Primary = Template.bind({}) as any
Primary.storyName = 'Drawer';

调整docs优先展示权

默认优先展示stories，可以通过优先展示docs

parameters = {
  docs: {
    disable: true
  },
  viewMode: 'docs'
}

https://github.com/storybookjs/storybook/blob/761501bf1344c5bab34e881702cc1938557b611c/addons/docs/docs/recipes.md#controlling-a-storys-view-mode

隐藏Canvas

  previewTabs: {
    canvas: {
        hidden: true,
    }
  },

可以隐藏当前Stories的Canvas面板

修改Logo跳转地址

// .storybook/themes/theme.js
import { create } from '@storybook/theming';

export default create({
  base: 'light',
  brandTitle: 'StoryBook',
  brandUrl: '/?path=/docs/快速开始--primary',
  brandImage: '/logo.png',
});

关闭Addons

showPanel无论设置在哪一层级，都是全局的

parameters = {
  docs: {
    disable: true
  },
  controls: {
    disable: true
  },
  options: {
    showPanel: false
  }
}

MDX写法

动机

上述的写法为CSF，component story format，是 Storybook 官方推荐的一种基于 ES module 的 stories 编写方法，由一个 export default 和一个或多个 export 组成。

它是Storybook 提供了一些封装过后的组件供使用，让我们能够较为快速的生成 stories。

代价是灵活度会相对的没有高，当然，如果只是简单的展示组件及其接收参数，那其实已经完全足够了。

可如果在展示组件之余，还想要编写一个额外的文档，比如介绍一下组件封装的背景，用到的技术等，CSF 就不是那么好用了。

基于这样的需求，Storybook 也支持使用 MDX 格式编写 stories。

MDX，如同 TSX，就是一种能够在 Markdown 文档中写 JSX 的格式。使用 MDX 格式编写 stories，文字部分内容的编写会更加灵活，没有了官方预置的内容，真正的所写即所得。

MDX示例

import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs';
import { action } from '@storybook/addon-actions'
import { reactive } from 'vue'
import Dialog from './index'

# Dialog

export const argsType = {
  visible: {
    description: '是否显示Dialog，支持.sync修饰符',
    type: {
      required: true
    },
    table: {
      type: {
        summary: 'Boolean'
      },
      defaultValue: {
        summary: false
      }
      // category: 'Boolean' // 参数分组
      // subcategory: 'Button colors', // 子分组
    },
    control: 'boolean'
  },
  showCancel: {
    description: '展示独立的关闭按钮X',
    table: {
      type: {
        summary: 'Boolean'
      },
      defaultValue: {
        summary: true
      }
    },
    control: 'boolean'
  },
  title: {
    description: 'Dialog的标题，也可通过具名slot（见下表）传入',
    table: {
      defaultValue: {
        summary: '示例Dialog'
      }
    },
    control: 'text'
  },
  rawHtml: {
    description: 'dialog主体内容',
    table: {
      type: {
        summary: 'string / htmlString'
      },
      defaultValue: {
        summary: 'DJ小能手',
        detail: 'DJ小能手'
      }
    },
    control: 'text'
  },
  confirm: {
    description: '确认相关的配置项目',
    mapping: {
      label: '确定按钮的文本内容',
      handler: '确认的回调'
    },
    options: ['label', 'handler'],
    table: {
      type: {
        summary: 'Object',
        detail: `
          confirm.label: 确定按钮的文本内容;
          confirm.handler: 确认的回调;
        `
      }
    },
    control: 'object'
  },
  cancel: {
    description: '取消相关的配置项目',
    table: {
      type: {
        summary: 'Object',
        detail: `
        cancel.label: 取消按钮的文本内容;
        cancel.handler: 取消的回调;`
      }
    },
    control: 'object'
  },
  header: {
    description: 'Dialog标题区的内容',
    table: {
      type: {
        summary: 'Vnode'
      },
      defaultValue: ''
    },
    control: 'text',
    category: 'Slots'
  },
  default: {
    description: 'Dialog的内容',
    table: {
      type: {
        summary: 'Vnode'
      },
      defaultValue: ''
    },
    control: 'text',
    category: 'Slots'
  },
  'update:visible': {
    table: {
      disable: true
    }
  }
}

export const actionData = {
  updateVisible: action('update:visible')
}

## 参数文档





## 基本用法

export const argsData = {
  visible: false,
  showCancel: true,
  confirm: {
    label: '确定',
    handler () {
      console.log('确定')
    }
  },
  cancel: {
    handler () {
      console.log('X')
    }
  }
}

export const HTMLTemplate = `
  
    
    
  
  
`

export const ConstructorFactory = (args) => ({
  components: { Dialog },
  props: Object.keys(args),
  setup () {
    const state = reactive({
      ...args
    })
    function toggleVisible () {
      state.visible = true
    }
    return {
      state,
      toggleVisible
    }
  },
  methods: {
    ...actionData
  },
  template: HTMLTemplate
})

内置组件

ArgsTable

自定义arguments类型，用于Props、Slots、Events展示与交互。

属性	示例	属性说明	属性值	属性值示例
of		自动解析组件的Props、Slots、Events等声明，依据Storybook内置类型声明输出Storybook文档	import导入的组件对象	`import Dialog from './index'`的"Dialog"
story		自定义arguments，需要使用story属性承接arguments类型声明。	Story标签的name属性值	的"storyName"

Canvas

生成一个 Canvas 画板，用于展示我们自己编写的组件。

画布会提供一些便捷的功能，比如展示当前组件的源代码等；

Canvas默认将Stroybook的Template函数作为源码输出，若想自定义源码输出，将源码作为属性mdxSource的值即可。

点击链接查看更多属性配置

Story

生成一个 story。

Notes：并不是一定要把 story 写在 组件中，Canvas 组件只是能够提供一些其他的功能（展示源码、复制代码之类的）。直接编写 story 的话，组件也能正常渲染。

image

区别在于，写在中，Canvas会提供便捷的功能：工具栏、源代码查看...

vscode语法提示插件

名称: MDX

ID: silvenon.mdx
说明: Provides syntax highlighting and bracket matching for MDX (JSX in Markdown) files.
版本: 0.1.0
发布者: Matija Marohnić
VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=silvenon.mdx

名称: MDX Preview

ID: xyc.vscode-mdx-preview
说明: MDX Preview
版本: 0.3.3
发布者: Xiaoyi Chen
VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=xyc.vscode-mdx-preview

名称: Vue Storybook Snippets

ID: megrax.vue-storybook-snippets
说明: Storybook Snippets for Vue
版本: 0.0.7
发布者: Megrax
VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=Megrax.vue-storybook-snippets

参考文档：

如何使用 Storybook 搭建前端组件文档

组件库开发—Storybook生成UI文档

简介

使用

初始化StoryBook环境

核心文件

main.js

preview.js

简单示例

入口配置

组件Story编写

全局依赖配置

启动本地服务

启动服务

效果展示

在Stories中使用第三方UI库

全局配置

按需加载

补充已有示例交互

配置参数文档

默认文档展示

参数配置

StoryBook功能模块

自定义Stories展示名称

命名模块

【推荐】storyName属性设定

Args

通过Storybook交互界面指定Args

通过URL设定Args

全局依赖

静态资源访问

定制化主题

修改Logo

修改站点Title、favicon

组件样式—Scss

Rem支持

Decorator自定义画布、文档样式

画布、文档的分离

侧边栏忽略子节点

调整docs优先展示权

隐藏Canvas

修改Logo跳转地址

关闭Addons

MDX写法

动机

MDX示例

内置组件

Meta

ArgsTable

Canvas

Story

vscode语法提示插件

名称: MDX

名称: MDX Preview

名称: Vue Storybook Snippets

参考文档：

你可能感兴趣的:(组件库开发—Storybook生成UI文档)