基于VuePress，AntDesign搭建自己的组件库 原创
基于VuePress，AntDesign搭建自己的组件库
前言
是否见过炫酷的ElementUI,iview,AntDesign等炫酷的UI框架网站，是否思考过自己搭建一个类似于这样的网站并封装成自己的组件库。是否思考过自己封装的组件统一管理便于以后使用，避免重复造轮子。
下面我将从安装，页面搭建，组件的引入与封装等章节跟大家分享组件库的搭建过程
最终形成的效果如下:
- 组件库能直接引用或二次封装Ant的组件
- 组件库能显示组件代码供他人查阅
介绍
VuePress 由两部分组成：第一部分是一个极简静态网站生成器 (opens new window)，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。
初始化项目
-
创建目录
-
初始化项目
yarn init # npm init
- 引入依赖
推荐本地安装，不建议全局安装
yarn add -D vuepress # npm install -D vuepress
- 添加README.md文件
- 配置package.json 启动命令
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}}
- 本地启动服务器
yarn docs:dev # npm run docs:dev
页面搭建
Vuepress是用来写文档的，所以它的所有文件都会被包裹在docs文件夹下（可以理解成Vuepress项目的src文件夹）。你可以在自己的Vuepress项目中单独创建docs也可以让它“寄生”在已经存在的项目下（与原项目的运行互不影响）。对于package目录用于存放我们自己自定义的组件，便于后期处理发布到npm或git
Vuepress项目的docs的目录结构如下：
├─ docs
│ ├─ .vuepress
│ │ └─ components
│ │ └─ config
│ │ └─ public
│ │ └─ styles
│ │ └─ theme
│ │ └─ config.js
│ │ └─ enhanceApp.js
│ └─ components
│ └─ README.md
├─ .gitignore
└─ package.json
上述文件的作用分别是：
- docs/.vuepress: 存放全局的配置、组件、静态资源等。
- docs/.vuepress/components: 存放页面组件展示示例。
- docs/.vuepress/config: 存放页眉导航栏和子页面侧栏的配置文件。
- docs/.vuepress/public: 静态资源目录。
- docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
- docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
- docs/.vuepress/theme: 项目自定义主题文件。
- docs/.vuepress/config.js: 配置文件的入口文件。
- docs/.vuepress/enhanceApp.js: 客户端应用的增强，可以用于引入AntDesign、ElementUi等。
- docs/README.md: 文档的入口页面。
完成文档目录调整后，我们需要配置我们的页面文件了。接下来我们可以通过配置config.js，md文件，导航栏，页面侧边栏来完成页面的搭建。
导航栏配置
- 在docs/.vuepress/config文件目录下增加navbar.js
导航栏的配置，是配置二级页面路由的过程,需要包含
- 点击组件，能路由到组件页面
- 连接到我们线上的git地址
接下来我们逐步实现上述需求：
在docs/.vuepress/config/navbar.js中做出如下配置：
module.exports=[
{ text: '主页', link: '/' },
{ text: '基础组件', link: '/components/Button/base' },
{ text: "Gitee码云", link: "https://gitee.com/wocwin/t-ui" }
]
这里只做了基础的配置，没有多层级的配置，如果做多层级的配置，可以在子栏目中添加chilren属性配置
字段含义:
text： 显示在导航栏上的文字信息
link： 路由地址显示的页面（类似于router中的component）会自动寻址到指定目录下的README.md，把它作为主入口显示出来。link字段也可以配置线上地址，点击后跳转到线上页面。默认页面路由地址如下：
| 文件的相对路径 | 页面路由地址 |
|---|---|
| /README.md | / |
| /components/README.md | /components |
children： 子路由的嵌套信息，可多层嵌套
- 引入navbar.js
做完navbar.js配置后我们需要把navbar.js的配置引入到vuepress的入口文件config.js中
const navbar = require('./config/navbar')
module.exports = {
title: 'TW-UI', //主题名称
description: '技术分享及基础组件使用', //主题的描述
base: '/t-ui/', //主题的上下文路径
head: [ // 注入到当前页面的 HTML <head> 中的标签
['link',
{
rel: 'shortcut icon', type: 'image/x-icon',
href: `./favicon.ico`
}
]
],
markdown: { lineNumbers: true // 代码块显示行号 },
themeConfig: {
nav:navbar //配置头部navabar导航栏
}
}
这样我们可以完成头部页眉的导航栏配置
但是这样的情况距离我们页面的展示还缺失以一部分二级页面的侧边栏的切换，接下来我们就需要配置我们的侧边栏
侧边栏配置
侧栏的承载的信息比较多，每个页面的侧栏交由该页面独立控制
- 配置sidebar
module.exports={
'/components/': [
{
title: '基础组件',
collapsable: true, //是否默认展开
children: [
{
title: '常用组件',
collapsable: false, //是否默认展开
children: [
'Button/base', // 按钮
'Icon/base', // ICON
]
}
]
},
]
}
- 引入sidebar
将sidebar的配置引入到vuepress入口文件config.js，最终形成的配置文件如下
const navbar = require('./config/navbar') //头部导航栏
const sidebar = require('./config/sidebar') //侧边栏
module.exports = {
title: 'TW-UI', //主题名称
description: '技术分享及基础组件使用', //主题的描述
base: '/t-ui/', //主题的上下文路径
head: [ // 注入到当前页面的 HTML <head> 中的标签
['link',
{
rel: 'shortcut icon', type: 'image/x-icon',
href: `./favicon.ico`
}
]
],
markdown: { lineNumbers: true // 代码块显示行号 },
themeConfig: {
nav:navbar //配置头部navabar导航栏 ，
sidebar: sidebar //配置页面侧边栏
}
}
完成配置后我们就形成了一个初步的静态网站了
Vue组件的引入与封装
该项目是基于antDesign的做的示例项目，所以首先我们需要引入antDesign
1. antDesign引入
import Antd from 'ant-design-vue'
import 'ant-design-vue/dist/antd.css'
import Tui from '../../packages' //Tui为二次封装的自定义业务组件
export default ({ Vue }) => {
Vue.use(Antd)
Vue.use(Tui)
}
2. 组件示例的编写
引入antDesign之后我们需要编写我们的自己的组件使用示例，现在基于antDesing的按钮组件编写示例
-
创建组件示例目录
在 docs/.vuepress/components 下创建文件夹docsComponents用于存放文档示例，然后在文件夹中添加按钮文件夹（Button),用于存放按钮使用示例组件。 -
编写示例组件
在 docs/.vuepress/components/docsComponents目录下创建示例组件，例如：basic.vue
<template>
<div>
<a-button type="primary">Primary</a-button>
<a-button>Default</a-button>
<a-button type="dashed">Dashed</a-button>
<a-button type="danger">Danger</a-button>
<a-config-provider :auto-insert-space-in-button="false">
<a-button type="primary">按钮 </a-button>
</a-config-provider>
<a-button type="primary">按钮</a-button>
<a-button type="link">Link</a-button>
</div>
</template>
<script>
export default {
name: 'basic'
}
</script>
<style scoped></style>
- 编写.md文件
在docs/components/ 目录下创建组件示例的使用文档（.md文件)文件中包含组件使用的方法
例：
# Button 按钮按钮用于开始一个即时操作。
## 何时使用 标记了一个（或封装一组）操作命令，响应用户点击行为，触发相应的业务逻辑。## 组件注册
### 按钮类型按钮有五种类型：主按钮、次按钮、虚线按钮、危险按钮和链接按钮。主按钮在同一个操作区域最多出现一次。
<common-code-format>
<docsComponents-Button-basic
slot="source">
</docsComponents-Button-basic>
<<< @/docs/.vuepress/components/docsComponents/Button/basic.vue
</common-code-format>
.....
- 组件展示code封装
如上我们引入组件时我们使用了一个common-code-format的组件，该组件用于我们对于组件的编码的展示和复制的功能。
在docs/.vuepress/components/common 中创建一个用于code展示的组件code-format.vue
<template>
<div
class="code-format"
:class="{ 'hover': hovering }"
@mouseenter="hovering = true"
@mouseleave="hovering = false" >
<div class="source">
<slot name="source"></slot>
</div>
<div
class="code-format-control"
ref="control"
v-if="control"
@click="isExpanded = !isExpanded"
>
<div>
<transition name="arrow-slide">
<a-icon
:type="iconType"
:class="[iconClass,
{ 'hovering': hovering }]">
</a-icon>
</transition>
<transition name="text-slide">
<span >{{controlText}}</span>
</transition>
</div>
<div class="control-button-container">
<a-button
ref="copyButton"
size="small"
type="link"
@click.stop="copyCode"
>复制代码</a-button>
</div>
</div>
<div class="meta" ref="meta">
<div class="description" v-if="$slots.default">
<slot></slot>
</div>
<div class="highlight">
<slot name="highlight"></slot>
</div>
</div>
</div>
</template>
Vuepress主题相关
一个 VuePress 主题应该负责整个网站的布局和交互细节。在 VuePress 中，目前自带了一个默认的主题（正是你现在所看到的），它是为技术文档而设计的。同时，默认主题提供了一些选项，让你可以去自定义导航栏（navbar）、 侧边栏（sidebar）和 首页（homepage） 等
1. 目录结构
在 .vuepress 文件夹下创建 theme ，目录结构如下：
├─ theme
│ ├─components
│ │ └─ page.vue
│ │ └─ navbar.vue
│ │ └─ sidebar.vue
│ ├─fonts
│ ├─layouts
│ │ └─ Layout.vue
│ ├─mixins
│ ├─styles
│ │ └─ theme.styl
│ ├─utils
上述文件的作用分别是：
- theme/components: 存放主题布局组件，内容，头部导航栏，侧边栏。
- theme/fonts: 存放主题字体文件。
- theme/layouts: 主题布局的入口文件。
- theme/styles: 主题的样式文件。
- theme/utils: 自定义主题的工具类。
2. 布局
在 theme/layout 目录下创建一个 Layout.vue 文件，Vuepress将会以此为首页布局来渲染 docs 根目录下的 README.md 文件，在Layout中引入编写的导航栏navbar，侧边栏sidebar和内容区域的主体文件page
3. 配置
在vuepress的入口文件config.js中增加右侧边栏的配置，配置方式：
themeConfig: {
type:'TwHome',
nav:navbar ,
subSidebar: 'auto',//在所有页面中启用自动生成子侧边栏，原 sidebar 仍然兼容
sidebar: sidebar
}
然后我们基本的框架已经形成(具有头部导航栏，侧边栏，右侧内容边栏的静态组件框架),当然也可以丰富自己的主题，修改自己的主题样式
自定义组件发布
安装以上的步骤我们已经完成了自定义组件的开发以及形成了自己的组件网站，接下来我们就需要发布我们的自定义组件，提供给其他人使用
1. 创建npm账号
首先，你需要有一个 npm 账号。如果还没有可以访问这里创建一个。
2. 登录npm
执行这一步前需要先安装nodejs和npm,然后执行
npm login
此时会提示输入用户名密码
如果你的 npm registry 修改过则会登录失败。可以尝试如下命令修改默认的：
npm config set registry https://registry.npmjs.org/
3. 组件编写
在上面步骤中我们已经编写过我们自定以的组件，在packages中，我们只需要关注添加一个入口文件导出我们编写的组件
在package中添加index.js,如下：
import { TAntModal, TAntProtocol } from './modal'
// 存储组件列表
const components = [
TAntModal,
TAntProtocol
]
// 定义 install 方法，接收 Vue 作为参数。如果使用 use 注册插件，则所有的组件都将被注册const install = function (Vue) {
// 判断是否安装
if (install.installed) return
install.installed = true
// 遍历注册全局组件
components.map(component => Vue.component(component.name, component))
}
// 判断是否是直接引入文件
if (typeof window !== 'undefined' && window.Vue) {
install(window.Vue)
}
export default {
...components, // 按需引入
// 导出的对象必须具有 install，才能被 Vue.use() 方法安装
install
}
4. npm发布
使用命令发布npm包
npm publish
参考文档:
项目参考地址有吗