weihongyu12
weihongyu12

使用Vue Styleguidist编写组件文档

在日常 Vue 项目开发中，我们难免需要写一些基础公共组件，在大型项目中，我们难免会遇到下面的痛点：

  • 组件 API，对于 Vue 组件，有 props、event、slot 等接口，在团队内需要一定的沟通成本
  • 对于 UI 组件，还需要提供预览，方便团队内快速选择合适的组件

如果使用 Markdown 撰写，虽然能写 API 文档，但是无法提供组件预览，并且手动写文档的成本也很大

好在有一个这样的库，可以提供自动化文档的生成，并提供组件预览，这个库叫做 Vue Styleguidist

安装

首先，Vue Styleguidist 只能适用于 Webpack 打包的项目，在此基础上，我们需要安装 vue-styleguidist 这个包

npm install vue-styleguidist --save-dev

然后在 package.json 配置下面两行命令，分别用于开发预览和部署打包

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

如果是使用 @vue/cli 3 生成的项目，可以直接使用 vue-cli-plugin-styleguidist 这个插件进行更快捷的安装和配置

组件源代码

这里为了进行简单的演示，我们使用了 @vue/cli 3 生成项目，创建组件 src/components/AppButton/AppButton.vue

我们的组件源代码如下，下面的案例都会依照此源代码进行展开

Props

Props 是组件最基本的 API，用于为组件传递数据

实际上，在配置好 Vue Styleguidist 之后，如果有写 prop，就已经能生成一个这样的文档

我们可以看到，此时已经带出了 Props 的名称、参数类型、默认值、必填性等等

我们仅仅需要为 prop 写上相应的注释进行描述，像 JSDoc 一样，就能生成一份完整的 Props 说明

export default {
  props: {
    /**
     * 按钮主题，有效值：
     */
    theme: {
      type: String,
      required: true,
    },
    /**
     * 启用outline样式
     */
    outline: {
      type: Boolean,
      default: false,
    },
    /**
     * 按钮大小，有效值：lg sm
     */
    size: {
      type: String,
      default: '',
    },
    /**
     * 启用块状按钮
     */
    block: {
      type: Boolean,
      default: false,
    },
    /**
     * 禁用状态
     */
    disabled: {
      type: Boolean,
      default: false,
    },
    /**
     * 按钮类型，有效值：button submit reset
     */
    htmlType: {
      type: String,
      default: 'button',
    },
  },
};

最终会得到一份完整的 Props 说明

Events

除了 Props，Event 事件也是 Vue 的一个重要的 API 之一，可以通过 v-on 为组件绑定事件

Vue 的事件使用 vm.$('event', ...params) 的方法进行定义，我们只需要在这个方法之前，加上必要的注释就可以了

  • 如果事件名不是字符串，可以使用 @event 进行标注
  • 事件的参数使用 @type 进行标注
export default {
  methods: {
    handleClick(e) {
      /**
       * 单击事件
       * @type {Event}
       */
      this.$emit('click', e);
    },
  },
};

Slots

Slot 插槽是 Vue 的自定义元素之一，Slot 向一个组件传递内容，也是封装公共组件常见的 API 之一

与 Props 和 Events 不同的是，Slots 通常是定义在