在日常 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
我们的组件源代码如下，下面的案例都会依照此源代码进行展开
<template>
<button
class="btn"
:type="htmlType"
:class="btnClass"
:disabled="disabled"
@click="handleClick"
>
<slot />
</button>
</template>
<script>
export default {
name: 'AppButton',
props: {
theme: {
type: String,
required: true,
},
outline: {
type: Boolean,
default: false,
},
size: {
type: String,
default: '',
},
block: {
type: Boolean,
default: false,
},
disabled: {
type: Boolean,
default: false,
},
htmlType: {
type: String,
default: 'button',
},
},
computed: {
btnClass() {
return {
[`btn-${this.theme}`]: !!this.theme && !this.outline,
[`btn-outline-${this.theme}`]: this.outline,
[`btn-${this.size}`]: !!this.size,
'btn-block': this.block,
};
},
},
methods: {
handleClick(e) {
this.$emit('click', e);
},
},
};
</script>
<style lang="scss">
@import '~bootstrap/scss/bootstrap';
</style>
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 通常是定义在 <template> 部分，不能使用 JS 注释进行标注，需要使用 HTML 注释，并且在注释里使用 @slot 进行标注
<button
class="btn"
:type="htmlType"
:class="btnClass"
:disabled="disabled"
@click="handleClick"
>
<!-- @slot 按钮的内容 -->
<slot />
</button>
如果使用的是具名 Slot（具名插槽），则会自动生成插槽名称
<button
class="btn"
:type="htmlType"
:class="btnClass"
:disabled="disabled"
@click="handleClick"
>
<!-- @slot 按钮的图标 -->
<slot name="icon" />
<!-- @slot 按钮的内容 -->
<slot />
</button>
Methods
看到这里可能各位会有个疑问，Methods 和 Events 有什么区别？
区别主要有以下两个：
- 定义方式不同：Methods 只要在
methods里定义函数即可，Events 则需要使用vm.$('event', ...params)进行定义 - 调用方式不同：Methods 使用
vm.$refs.ref.method()这样的方式进行调用，Events 使用v-on指令或者vm.$on('event')进行监听
实际上，使用 Methods 方法封装组件 API 的情况是比较少的，但是依然不能排除这种情况
对于 Methods 方法，我们只需要像使用 JSDoc 一样为函数进行注释就可以了，最后再附上 @public 进行标识
export default {
methods: {
/**
* 单击事件
* @param {Event} e
* @public
*/
click(e) {
// some code
},
},
};
编写样例
通过上面的例子，我们将至少得到一个这样的文档
这个文档把该有的 API 都暴露出来了，但是它并不是完美无缺的：
- 直接对比 Markdown 文档，并没有明显的优势
- 缺乏组件 UI 样例
在文章的开头，我们说过，UI 组件需要为团队提供样式预览，并且需要自动生成
很遗憾的是，Vue Styleguidist 并不能直接生成预览样式，这个需要手写样式代码
在 Vue Styleguidist，有两种编写组件样例的方式
README方式
在组件的同个目录下，新建一个文件 README.md，比如 src/components/AppButton/README.md
然后直接调用组件代码
这样我们就能快速简洁的生成一个预览+示例代码了
我们也可以为组件传入 Props，预览组件的表现
<docs>组件方式
可以直接在组件下方增加一个组件 <docs></docs>，并在里面直接使用 Markdown 编写样例，这种方式适用于项目结构比较简单的项目，但是我认为会使组件的代码变得很冗长，在此不再赘述
配置
Vue Styleguidist 支持自定义配置，只需要在项目根目录下，创建 styleguide.config.js，就可以参照官方文档进行配置
// styleguide.config.js
module.exports = {
title: 'Default Style Guide', // 文档的标题
components: 'src/components/**/*.vue', // 组件的目录
defaultExample: false, // 是否使用默认样例
usageMode: 'expand', // 是否展开用法
exampleMode: 'expand', // 是否展开示例代码
styleguideDir: 'styleguide', // 打包的目录
codeSplit: true, // 打包时是否进行分片
skipComponentsWithoutExample: true, // 是否跳过没有样例的组件
};
注意事项和总结
注意事项
- JSDoc 的标签仍然有效
- TypeScript、Flow 和 Class 组件同样可以使用，只是使用方法稍有不同
- JSX 也可以使用
总结
通过 Vue Styleguidist，我们将至少得到下面两项好处：
- 完整的组件 API 和用法
- 直观的组件预览
另外我认为还能得到以下几项好处：
- 完善的注释
- 较小的 UI 调试成本
- 减少团队内部沟通成本
Vue Styleguidist 实际上还拥有多种配置和用法，各位感兴趣可以去官网看看文档
题外话：实际上 Vue Styleguidist 来源于 React Styleguidist（也依赖于这个项目），使用方法大同小异，不同于 Vue 组件的是，React 组件的 API 只有 Props 一项
