For front-end projects, with the increase of time and personnel, there will be more and more self-developed components. If there is no unified component library document, team collaboration will be chaotic, and it is difficult to synchronize information in real time, so build your own unified components Libraries are more urgent.
Since we are using vue and element, we choose to use VuePress to generate a component document library, which contains examples of Vue components, displays of common functions such as attributes and events.
Source code address: source code sample download
Install VuePress
npm install vuepress
You can create a new project, or use it directly in your existing project. I use it directly in the existing project. Of course, I first create a new project and test it successfully before adding it to the current project.
1. Configure VuePress
The directory name can be defined by yourself, and the default is docs as the document directory of the project
Create a new homepage.md file
Create README.md in the webdocs directory as the main page of the system,
home: true
heroImage: ''
heroText: Ctj-UI 前端组件文档
features:
- title: 一致性 Consistency
details: 与现实生活一致：与现实生活的流程、逻辑保持一致，遵循用户习惯的语言和概念
- title: 反馈 Feedback
details: 通过界面样式和交互动效让用户可以清晰的感知自己的操作
- title: 效率 Efficiency
details: 界面简单直白，让用户快速识别而非回忆，减少用户记忆负担。
footer: by yourself
Create configuration file
新建 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: {
},
}
The page is as follows
The directory structure is as follows:
Install the Demo Container plugin vuepress-plugin-container
Demo Container is a Vuepress-based plugin that can help you add Vue examples when writing documents. It was born to reduce the difficulty of adding some related examples when writing component documents.
Plugin description: Demo container plugin
npm install vuepress-plugin-demo-container
Then configure the plugin in the /docs/.vuepress/config.js file
2. Create component documents
1. Use third-party components such as Element to generate documents
Add component reference
// 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)
}
}
Create component document select.md, run the result
2 Generate documentation using components in your own project
When using the components of your own project, you should pay attention to that each custom component needs to export install so that it can be called by Vue.use
First create a custom component, the directory structure is as follows
Core group code
<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>
Export in group/index.js
import Module from './src/index.vue';
// 给组件定义install方法
Module.install = Vue => {
Vue.component(Module.name, Module);
};
export default Module;
A single component can be exported directly. If there are multiple components, they can be processed centrally in the main directory of the 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,
}
Then use the created component to add a reference to the local component in docs/.vuepress/enhanceApp.js
import CtjUI from '../../webui/index.js';
export default async ({
Vue }) => {
if (typeof process === 'undefined') {
Vue.use(CtjUI);
}
};
Create custom component documentation
Create a group document group.md file, see the example for the file
, so far the VuePress document can be used successfully
3. Deployment
This step is relatively simple. To build the document through npm run build, the dist directory will be generated in the .vuepress directory, and the files in the dist directory can be published to the server. The effect is the same as the local preview
