前端项目,随着时间和人员的增加,自研组件会越来越多,如果没有统一的组件库文档,团队协同上就会比较混乱,而且难以做取信息实时同步,所以搭建自己的统一组件库比较迫切。
由于使用的是vue和element,所以选择使用VuePress生成组件文档库,包含Vue组件的示例,属性,事件等常用功能的展示。

源码地址:源码示例下载

安装VuePress

npm install vuepress

可以创建一个新项目,也可以直接在自己现有项目中使用,我是直接在现有项目中使用的,当然先是创建个新项目测试成功后,才加到现在项目中

一、配置VuePress

目录名称可以自己定义,默认是docs做为项目的文档目录

新建首页.md文件

在webdocs目录下创建README.md,做为系统的主页面,

home: true
heroImage: ''
heroText: Ctj-UI 前端组件文档
features:
  - title: 一致性 Consistency
    details: 与现实生活一致:与现实生活的流程、逻辑保持一致,遵循用户习惯的语言和概念
  - title: 反馈 Feedback
    details: 通过界面样式和交互动效让用户可以清晰的感知自己的操作
  - title: 效率 Efficiency
    details: 界面简单直白,让用户快速识别而非回忆,减少用户记忆负担。
    footer: by yourself

创建配置文件

新建 docs/.vuepress/config.js ,填入基本的配置信息。注意,这个文件是VuePress最核心的一个文件,具体参数参考VuePress官方文档 https://vuepress.vuejs.org/zh/config/
主要设置一下title, 导航和侧边栏
module.exports = {
  theme: '',
  title: 'Ctj-UI',
  description: '基于Element组件搭建的后管理系统的单组件',
  base: '/',
  port: '8080',
  themeConfig: {
    nav: [
      {
        text: '首页',
        link: '/',
      },
      {
        text: '组件',
        link: '/comps/',
      },
    ],
    sidebar: {
      '/comps/': ['/comps/', '/comps/select.md', '/comps/group'],
    },
  },
  head: [],
  plugins: ['demo-container'],
  markdown: {},
}

页面如下
在这里插入图片描述

目录结构如下:
在这里插入图片描述

安装Demo Container插件 vuepress-plugin-container

Demo Container 是一个基于 Vuepress 的插件,它可以帮助你在编写文档的时候增加 Vue 示例,它的诞生初衷是为了降低编写组件文档时增加一些相关示例的难度。
插件说明:Demo container插件

npm install vuepress-plugin-demo-container

然后在/docs/.vuepress/config.js文件中配置上该插件

二、创建组件文档

1、使用Element等第三方组件生成文档

添加组件引用

// Element 组件
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default async ({ Vue }) => {
  if (typeof process === 'undefined') {
    Vue.use(ElementUI)   
  }
}

创建组件文档 select.md,运行结果
在这里插入图片描述

2 使用自已项目中的组件生成文档

使用自已项目的组件的时候,要注意一下,每个自定义组件要导出 install,以便被Vue.use调用
首先创建一个自定义组件,目录结构如下
在这里插入图片描述
核心group 代码

<template>
  <p class="labelTitle" :name="name">
    {{ name }}<span v-if="tips" class="tips">({{ tips }})</span>
  </p>
</template>
<script>
export default {
  name: 'CtjGroup',
  /**
   * ctj-group属性参数
   * @property {string} [name] 分组名称
   * @property {string} [tips] 补充说明,默认值空
   */
  props: {
    // 分组名称
    name: {
      type: String,
      default: '分组名称',
    },
    // 补充信息
    tips: {
      type: String,
      default: '',
    },
  },
  data() {
    return {}
  },
}
</script>
<style lang="css" scoped>
.labelTitle {
  font-weight: bolder;
  font-size: 16px;
  border-left: 4px solid #1890ff;
  padding-left: 4px;
}
.tips {
  font-size: 12px;
  color: #606266;
  font-weight: 400;
  padding-left: 4px;
}
</style>

group/index.js中进行导出

import Module from './src/index.vue';

// 给组件定义install方法
Module.install = Vue => {
  Vue.component(Module.name, Module);
};

export default Module;

单个组件可以直接导出,如果是多个组件,可以在webui要目录中,集中处理

import group from './group'

const components = [group]

const install = Vue => {
  // 判断组件是否安装,如果已经安装了就不在安装。
  if (install.installed) return
  install.installed = true
  // 遍历的方式注册所有的组件
  components.map(component => Vue.use(component))
}

// 检查vue是否安装,满足才执行
if (typeof window !== 'undefined' && window.Vue) {
  install(window.Vue)
}

export default {
  // 所有的组件必须有一个install的方法,才能通过Vue.use()进行按需注册
  install,
  ...components,
}

然后使用创建的组件,在docs/.vuepress/enhanceApp.js中增加本地组件的引用

import CtjUI from '../../webui/index.js';

export default async ({ Vue }) => {
  if (typeof process === 'undefined') { 
    Vue.use(CtjUI);
  }
};

创建自定义组件文档

创建一个group文档group.md文件,文件见示例
在这里插入图片描述
至此VuePress文档已可以成功使用

三、部署

这步比较简单,通过 npm run build 构建文档,会在.vuepress目录下生成dist目录,将dist目录下的文件发布到服务器上就可以,效果和本地预览的一样
在这里插入图片描述

Logo

前往低代码交流专区

更多推荐