创建一个UI组件库以及生成组件文档

本人技术不精，随便玩玩，仅供参考，文章末尾提供完整源码。

个人认为，现在市面上的组件库太多了，其实是不需要我们自己去建的，随便拿出来一个都可以满足基本开发需求，如果想要玩一玩的可以试着自己搭建一个。

首先简单一点，使用Vue-cli 搭建一个项目结构。
为了能随时看到效果，我们默认将src作为引用组件的入口，用来调试组件效果；还需要创建一个components（名字随意）文件夹用来存放组件。目录结构如下

├─node_modules
├─public
├─components //存放组件
├─src  //引用组件
    ├─components
    ├─assets
    ├─App.vue
    ├─router.js
    ├─index.js  //自建文件，引入组件库
    └─main.js
├─babel.config
├─package.json
└─README.md

接下来，就正式进入搭建组件环节

1. 创建组件目录
我们以button组件为例，为了样式可以按需引入，以及使用者可以方便修改样式，我们把css拿出来单独编写，当然如果你只是为了编写一个组件供少数人使用，也可以直接写在.vue里，一个组件包含以下文件:

├─components 
  ├─style  // 样式文件
      ├─index.scss  //全局样式
      ├─base.scss  //共用样式
      └─button.scss  //单独组件样式
  └─button //组件文件
      ├─index.js //单独打包文件
      └─src
        ├─main.vue  //编写组件
        └─myBtn.md //显示示例

2. 编写组件
在 main.vue 写一个组件，代码如下

<template>
  <button @click="btnClick" :class="['btn',`btn-${type}`]">
    <!-- 插槽 -->
    <slot></slot>
  </button>
</template>
<script>
export default {
  name:'myBtn',
  props:{
    // `medium` / `small` / `mini`
    size:{
      type:String,
      default:'medium'
    },
    // `primary` / `success`
    type:{
      type:String,
      default:'primary'
    }
  },
  methods:{
    btnClick(){
      // 这是点击事件
      this.$emit('点击')
    }
  }
}
</script>

通过 :class="['btn',btn-${type}]" 对传入的不同类型的按钮进行样式更改

在style文件夹对应的scss里写一些样式，代码如下：

.btn{
    width:150px;
    height: 40px;
    border:none;
    font-size:16px;
    color:#fff;
}
.btn-primary{
    background:blue;
}
.btn-success{
    background:green;
}

在index.js里对组件进行注册，代码如下：

import Mybtn from "./src/main.vue"

Mybtn.install = function(Vue) {
  Vue.component(Mybtn.name, Mybtn);
};

export default Mybtn;

---

3. 使用组件
现在一个组件就完成了，我们来使用一下看看效果
在main.js引入组件及样式（我这里全局引入，也可以按需引入）

import Vue from 'vue'
import App from './App.vue'


import {Mybtn} from "./index.js"
import "../components/style/index.scss";

Vue.use(Mybtn)

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

可以在App.vue 使用一下

<template>
  <div id="app">
   <Mybtn >常规按钮</Mybtn>
   <Mybtn type='success'>成功按钮</Mybtn>
  </div>
</template>

<script>
export default {
  name: 'App',
}
</script>

<style>

</style>

一个按钮组件就出来了

---

4. 生成组件库文档

组件完成后，为了用户可以更直观的使用，就需要创建组件文档了，我使用的是@Vuese/cli,很简单易用，具体安装教程参考文档 @vuese/cli
安装完成后，执行 vuese gen
此时，根目录就会出现【website】目录，你的组件文档就生成了，目录如下
website
├── index.html
├── components
├──├── myBtn.md
├──├── HelloWorld.md

这里要标记重点了！！其实我只建了一个myBtn的组件，但是目录却出来了两个，这是因为vuese会自动识别.vue后缀文件,我们可以规定一下他的生成路径

官网：vuese 会在命令的运行目录搜索 vuese.config.js 或 .vueserc 或者是 package.json 文件的 vuese 属性

所以我们在根目录下新建一个.vueserc，给它配置一下

{
  "include": [
    "./components/**/*.vue" //指定被生成的.vue文件
  ],
  "title": "组件文档",  //组件标题
  "genType": "docute"  //组件类型
}

删掉website（目录下已有文件重新打包的时候不会自动删除，所以建议删掉重新生成一份）,执行 vuese gen ，这个时候就只有一个myBtn了，重新启动后，组件文档就出来啦，太方便了，页面如下：

还有一个问题需要注意：生成的文档是没有首页的，如果你点击标题，可以看到路由变成了’/‘ ，页面显示404，这个时候，就需要我们手动加一个首页了，很简单，我们在website目录下手动写一个README.md 文件，（文件名一定是README！），打包文档的时候会自动识别为路由’/’，目录如下：
website
├── index.html
├── README.md
├── components
├──├── myBtn.md

README.md 就随便写

# 文档说明
这是首页

这个时候再看一下

---

5. 实现组件文档可预览,并且对整个组件进行打包
vuese只能生成一个纯文档，只有大片大片的文字，没有组件预览效果，以及使用示例，我们只能手动添加了，还记得我们一开始留了一个放组件预览的地方!

预览实现过程：

• 因为文档每次打包的时候，内容都会重新生成一遍，即使给它手动添加了预览代码以及事件动作，它也会在重新打包后回到原来的内容，这种方式显然不可取 ×
• 所以我们预留一个单独写预览功能的md文件，在执行vuese gen 文档打包的时候，利用gulp将两个md文件合并，这个时候，就是既有预览，又有组件了。

因为一开始没有找到很全的参考资料，不是缺少预览，就是打包太随意，所以我在做打包和预览的时候，参考融合了这两篇文章的内容，组件预览功能、 打包功能（ 大家可以点进去看看，作者的打包过程写的很详细）形成了一个比较全面的组件全流程，因为文章里都很详细，我这里就不多介绍实现过程了，至于融合怎么做，可以戳文章底部的我的github看看。

• 事件和样式一起添加到文档里
  我们可以在website目录外，新建一个index.html,引入样式及js，再把这个新建的index.html将website文件夹里的index.html替换掉（同样gulp），这个时候，文档功能就已经很全了。
  此时的目录结构
  根目录
  ├── website
  ├── gulpfile.js //新增
  ├── document //新增目录
  ├──├── index.html //新建文件

此时启动文档页面

到现在，一个完整的组件功能流程就出来了
打包和发布我会重新写一篇文章

---

完整示例戳github
github地址