头图

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

BerylLee

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

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

首先简单一点,使用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地址

阅读 302
18 声望
1 粉丝
0 条评论
18 声望
1 粉丝
文章目录
宣传栏