组件库系列三：编写组件库文档_element的组件库的doc怎么写

vuepress介绍

• Vue 驱动的静态网站生成器
• 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
• 享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。
• VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。

创建文档工程

另起一个目录，创建por-ui-doc文件夹

yarn init -y  // 创建package.json
yarn add vuepress -D // 安装vuepress框架
1
2

配置运行指令

在package.json中

"scripts":{
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
}
1
2
3
4

vuepress浏览器自动更新

本地开发模式运行Vuepress 1.x 时，浏览器不能自动更新

`"dev": "vuepress dev docs"`

改为

`"dev": "vuepress dev docs --temp .temp"`
1
2
3
4
5

下载插件和依赖

element-ui、highlight.js(代码高亮)、sass

element-ui、highlight.js 可以直接下载

yarn add element-ui highlight.js -D
1

node-sass和sass-loader直接下载会有版本过高问题，版本匹配：5.0.0配合10.1.1

yarn add sass-loader@10.1.1 -D
yarn add node-sass@5.0.0 -D
1
2

npm/yarn link

由于组件库项目和文档项目之间存在依赖，可以使用yarn link将一个项目链接到另一个项目。

项目A中需要使用项目B时，可以使用yarn link或npm link将B引入到A。

PS：link本身是软链接，yarn link是将资源存在yarn的内存中，相当于建立了一个通道。

# 进入B项目，创建链接对象
yarn link
# 进入A项目，建立B项目的链接
yarn link B
# 解除链接
yarn unlink B
1
2
3
4
5
6

注意：

1. A和B均为package.json文件中的“name”对应的值，一般为文件夹名称

2. 项目B是我们自己开发封装的组件，引入前需要先完成打包

3. 使用完成后使用unlink解除链接

docs文件夹

在根目录下创建docs文件夹

在该文件夹下，创建README.md文件，两个的名称都不能改

home: true // 是否首页
actionText: 欢迎 → // 首页文本
actionLink: /components/button
features:
- title: por-ui官方文档
  details: por-ui官方文档
1
2
3
4
5
6

在该文件夹下，创建components文件夹

里面放每个组件都有一个md文件，例如button.md

注意文件中需要有标题，不然显示的是链接形式

# 按钮组件
1

或者设置title

---
title: Button
---
1
2
3

查看效果

运行yarn run dev

.vuepress文件夹

1. 创建.vuepress文件夹

在docs文件夹下创建.vuepress文件夹，在里面创建config.js,用来配置导航等文档基本结构信息，修改后重启项目才生效

module.exports = {
  title: 'por-ui', // 设置网站标题
  description: 'ui 库', //描述
  dest: './build', // 设置输出目录
  port: 1234, //端口
  markdown: {
    anchor: { permalink: false },
  },
  themeConfig: { //主题配置
    nav: [{
        text: '主页',
        link: '/'
      }, // 导航条
    ],
    // 为以下路由添加侧边栏
    sidebar: [{
        title: '介绍',
        collapsable: true, // 可折叠
        children: ["/introduce/"]
      },
      {
        title: '组件',
        collapsable: false,
        children: [
        	// 按钮组件
          "/components/button"
        ]
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

2. 去掉默认样式

在.vuepress文件夹下创建styles文件夹，在里面创建palette.styl文件写自己的样式去格式化掉框架自带的一些默认样式

$codeBgColor = #fafafa // 代码背景颜色

$accentColor = #3eaf7c
$textColor = #2c3e50

$borderColor = #eaecef
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961

.content pre{  margin: 0!important;}

.theme-default-content:not(.custom){
    max-width: 1000px !important;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

3. enhanceApp.js入口文件

在页面里要用上自己的组件，要在.vuepress文件夹下创建一个enhanceApp.js文件作为入口(启动当前的vuepress，这个文件就是当前项目的一个入口)，框架规定的，名字不能改

import Vue from 'vue';
import Element from 'element-ui'; // 引入elementUi，因为要用到elementui里的结构
import 'element-ui/lib/theme-chalk/index.css'

import hljs from 'highlight.js' //引入高亮js
import 'highlight.js/styles/googlecode.css' //引入高亮js样式文件

//正常情况引入porui要根据目录../../一层一层去引入的，
//这里为了方便在porui文件夹根目录下npm link一下，把porui添加到本地全局，
//注意要以package.json里的name名字为准
//然后在porui-doc文件夹下npm link por-ui一下，把本地全局的porui引入到文档项目下
//成功之后在porui-doc下的nodemodule下就能看到这个porui文件夹了(实际上是个链接，每次porui文件夹改动了，这里的也会改动)
//这样就可以以下面一行的方式引用了
import porUi from 'por-ui' // 要编写对应的文档的包
import 'por-ui/dist/por-ui.css'
// 写了一个高亮指令，可以去解析pre code里面的标签，添加高亮
Vue.directive('highlight', function(el) {
  let blocks = el.querySelectorAll('pre code');
  blocks.forEach((block) => {
    hljs.highlightBlock(block)
  })
})
export default ({
  Vue,
  options,
  router,
  siteData
}) => {
  Vue.use(Element);
  Vue.use(porUi) // 设置为全局组件
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

4. components文件夹

   在.vuepress文件夹下，创建components文件夹，放置为引入的poly-ui写一些测试代码组件，只要是这个目录下的都是全局组件，例如：在里面创建button文件夹，里面放button1.vue,那么buton1.vue就是button的测试

   // button1.vue
   <template>
     <div>
       <por-button>默认按钮</por-button>
       <por-button type='primary'>主要按钮</por-button>
       <por-button type='warning'>警告按钮</por-button>
       <por-button type='danger'>危险按钮</por-button>
       <por-button type='success'>成功按钮</por-button>
       <por-button type='info'>信息按钮</por-button>
     </div>
   </template>
   <script>
   export default {}
   </script>
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14

   然后button1.vue就可以在docs目录下的components内的所有.md文件内使用了

   #按钮组件
   //button是.vuepress内components下文件夹button的名字，-后面的button1是button文件夹下button1.vue的名字
   //找到的就是button1.vue，它会把这个文件渲染到文档上
   <button-button1></button-button1>。
   1
   2
   3
   4

5. core-js报错

如果遇到core-js报错，就yarn add core-js@2重新装一下

可收缩代码块

创建可收缩代码块

在.vuepress内components下文件夹下创建demo-block可收缩代码块，开发像elementui那种查看例子时，可以展开代码的功能

<template>
  <!-- 主要用到了三个插槽 -->
  <div
    class="demo-block"
    :class="[blockClass, { 'hover': hovering }]"
    @mouseenter="hovering = true"
    @mouseleave="hovering = false"
  >
    <div style="padding:24px">
      <!-- 第一个是源代码插槽 -->
      <slot name="source"></slot>
    </div>
    <div class="meta" ref="meta">
      <div class="description" v-if="$slots.default">
        <!-- 第二个是描述插槽 -->
        <slot></slot>
      </div>
      <div class="highlight" v-highlight>
        <!-- 第三个是高亮插槽 -->
        <slot name="highlight"></slot>
      </div>
    </div>
    <div class="demo-block-control" ref="control" @click="isExpanded = !isExpanded">
      <transition name="arrow-slide">
        <i :class="[iconClass, { 'hovering': hovering }]"></i>
      </transition>
      <transition name="text-slide">
        <span v-show="hovering">{{ controlText }}</span>
      </transition>
    </div>
  </div>
</template>

<style lang="scss">
.demo-block {
  border: solid 1px #ebebeb;
  border-radius: 3px;
  transition: 0.2s;
  &.hover {
    box-shadow: 0 0 8px 0 rgba(232, 237, 250, 0.6),
      0 2px 4px 0 rgba(232, 237, 250, 0.5);
  }

  code {
    font-family: Menlo, Monaco, Consolas, Courier, monospace;
  }

  .demo-button {
    float: right;
  }

  .source {
    padding: 24px;
  }

  .meta {
    background-color: #fafafa;
    border-top: solid 1px #eaeefb;
    overflow: hidden;
    height: 0;
    transition: height 0.2s;
  }

  .description {
    padding: 20px;
    box-sizing: border-box;
    border: solid 1px #ebebeb;
    border-radius: 3px;
    font-size: 14px;
    line-height: 22px;
    color: #666;
    word-break: break-word;
    margin: 10px;
    background-color: #fff;

    p {
      margin: 0;
      line-height: 26px;
    }

    code {
      color: #5e6d82;
      background-color: #e6effb;
      margin: 0 4px;
      display: inline-block;
      padding: 1px 5px;
      font-size: 12px;
      border-radius: 3px;
      height: 18px;
      line-height: 18px;
    }
  }

  .highlight {
    pre {
      margin: 0;
    }

    code.hljs {
      margin: 0;
      border: none;
      max-height: none;
      border-radius: 0;
      line-height: 1.8;
      color: black;
      &::before {
        content: none;
      }
    }
  }

  .demo-block-control {
    border-top: solid 1px #eaeefb;
    height: 44px;
    box-sizing: border-box;
    background-color: #fff;
    border-bottom-left-radius: 4px;
    border-bottom-right-radius: 4px;
    text-align: center;
    margin-top: -1px;
    color: #d3dce6;
    cursor: pointer;
    position: relative;

    &.is-fixed {
      position: fixed;
      bottom: 0;
      width: 868px;
    }

    i {
      font-size: 16px;
      line-height: 44px;
      transition: 0.3s;
      &.hovering {
        transform: translateX(-40px);
      }
    }

    > span {
      position: absolute;
      transform: translateX(-30px);
      font-size: 14px;
      line-height: 44px;
      transition: 0.3s;
      display: inline-block;
    }

    &:hover {
      color: #409eff;
      background-color: #f9fafc;
    }

    & .text-slide-enter,
    & .text-slide-leave-active {
      opacity: 0;
      transform: translateX(10px);
    }

    .control-button {
      line-height: 26px;
      position: absolute;
      top: 0;
      right: 0;
      font-size: 14px;
      padding-left: 5px;
      padding-right: 25px;
    }
  }
}
</style>

<script type="text/babel">
export default {
  name: 'demo-block',
  data () {
    return {
      hovering: false,
      isExpanded: false,
      fixedControl: false,
      scrollParent: null,
      langConfig: {
        "hide-text": "隐藏代码",
        "show-text": "显示代码",
        "button-text": "在线运行",
        "tooltip-text": "前往 jsfiddle.net 运行此示例"
      }
    }
  },

  props: {
    jsfiddle: Object,
    default () {
      return {}
    }
  },

  methods: {
    scrollHandler () {
      const { top, bottom, left } = this.$refs.meta.getBoundingClientRect()
      this.fixedControl = bottom > document.documentElement.clientHeight &&
        top + 44 <= document.documentElement.clientHeight
    },

    removeScrollHandler () {
      this.scrollParent && this.scrollParent.removeEventListener('scroll', this.scrollHandler)
    }
  },

  computed: {
    lang () {
      return this.$route.path.split('/')[1]
    },

    blockClass () {
      return `demo-${this.lang} demo-${this.$router.currentRoute.path.split('/').pop()}`
    },

    iconClass () {
      return this.isExpanded ? 'el-icon-caret-top' : 'el-icon-caret-bottom'
    },

    controlText () {
      return this.isExpanded ? this.langConfig['hide-text'] : this.langConfig['show-text']
    },

    codeArea () {
      return this.$el.getElementsByClassName('meta')[0]
    },

    codeAreaHeight () {

      if (this.$el.getElementsByClassName('description').length > 0) {
        return this.$el.getElementsByClassName('description')[0].clientHeight +
          this.$el.getElementsByClassName('highlight')[0].clientHeight + 20
      }
      return this.$el.getElementsByClassName('highlight')[0].clientHeight
    }
  },

  watch: {
    isExpanded (val) {
      this.codeArea.style.height = val ? `${this.codeAreaHeight + 1}px` : '0'
      if (!val) {
        this.fixedControl = false
        this.$refs.control.style.left = '0'
        this.removeScrollHandler()
        return
      }
      setTimeout(() => {
        this.scrollParent = document.querySelector('.page-component__scroll > .el-scrollbar__wrap')
        this.scrollParent && this.scrollParent.addEventListener('scroll', this.scrollHandler)
        this.scrollHandler()
      }, 200)
    }
  },

  mounted () {
    this.$nextTick(() => {
      let highlight = this.$el.getElementsByClassName('highlight')[0]
      if (this.$el.getElementsByClassName('description').length === 0) {
        highlight.style.width = '100%'
        highlight.borderRight = 'none'
      }
    })
  },

  beforeDestroy () {
    this.removeScrollHandler()
  }
};
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272

在组件.md文件中使用

# Button组件
常用的操作按钮。
## 基础用法
基础的按钮用法。

<demo-block>
::: slot source
<button-button1></button-button1>
:::

使用type属性来定义 Button 的样式。

::: slot highlight

```html
<div>
    <por-button>默认按钮</por-button>
    <por-button type="primary">主要按钮</por-button>
    <por-button type="success">成功按钮</por-button>
    <por-button type="info">信息按钮</por-button>
    <por-button type="warning">警告按钮</por-button>
    <por-button type="danger">危险按钮</por-button>
</div>
```
:::
</demo-block>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

到这里就基本上完成了一个文档的功能

效果展示