Vue Styleguidist 生成组件说明文档

前言

多人开发同一个项目的时候，根据业务需求和产品的设计风格，会出现很多相同的样式、可复用的组件，此时就会出现问题：

• 组件 API很多，有 props、event、slot 等，个人写完组件后，需要和团队每个人员沟通使用方法
• 成员需要在组件里面添加新属性、方法，也需要沟通
• 自己封装的组件，需要能够预览，便于选择合适的组件

使用其他方式，如word文档、README.md等方式，不能同时提供代码块以及组件预览，Vue Styleguidist为我们提供了此功能。

1、安装依赖

npm install --save-dev vue-styleguidist

2、创建script命令

{
  "scripts": {
    "styleguide": "vue-styleguidist server",
    "styleguide:build": "vue-styleguidist build"
  }
}

npm run styleguide:可在本地预览组件； npm run styleguide:build:生成一个styleguide包，可用于部署到服务端

3、创建styleguide.config.js文件

在项目的根目录下创建一个styleguide.config.js文件

// styleguide.config.js
const path = require('path');
module.exports = {
    //说明文档标题
    title: 'ERP项目共用组件说明文档',
    // 需要被被添加说明的组件
    components: 'src/components/**/*.vue',
    // 忽略的组件
    ignore:["src/components/**/example.vue"],
    version: '1.1.1',
    //styleguide:build 成的包名
    styleguideDir: 'styleguide-dist',
    // 在编辑器的右上角添加一个小按钮，用于将编辑器的内容复制到剪贴板
    copyCodeButton:true,
    // 是否每个章节是一个独立的页面. 默认:false
    pagePerSection: true,
    // props/events/slot的说明默认是展开还是收缩: expand / collapse / hide
    usageMode: 'expand',
    // 左侧导航默认是展开还是收缩: expand / collapse / hide
    tocMode: 'expand',
    // 显示 prop、事件、槽或方法是否来自当前文件或在 mixin 或扩展组件中配置。如果它是外部的，它会显示组件的名称，并在悬停时显示文件的相对路径。
    displayOrigins: true,
    require: [path.join(__dirname, 'styleguide/global.require.js')], //全局vue组件使用的插件
}

全部配置项的使用，请参阅styleguide官方文档

此时，执行 npm run styleguide会生成对应的组件文档：

4、搭建组件预览环境

因为styleguide是不会加载main.js的，所以需要把组件用到的依赖重新引入

我的项目用到的是vue2、elementUI，以此为例：

4-1、引入全局组件依赖

根目录下新建一个styleguide文件，添加global.require.js文件，此文件会在styleguide.config.js里被引用；

import Vue from 'vue';
import Element from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
Vue.use(Element, {
  size: 'medium' // set element-ui default size
})

4-2、创建预览demo

为了便于cv，采用README.md引入外部文件的方式，查看组件示例代码 在组件的同级下，新建一个example.vue的文件

README.md文件中引入example.vue

5、预览以及代码块结果展示

全部配置完成后，执行npm run styleguide

注意：在example.vue文件中，使用到的其他组件、样式、依赖，都需要在global.require.js中重新引入，不然不会渲染出来。