从 Vue-cli 开始构建 UI 库到 Markdown 生成文档和演示案例

Posted 2020-12-03 lindongdong

从 Vue-cli 开始构建 UI 库到 Markdown 生成文档和演示案例

1. vue-cli 环境搭建

• 打开cmd命令工具，输入npm install -g vue-cli全局安装 vue-cli

• 安装过程慢，切换到淘宝镜像源npm config set registry https://registry.npm.taobao.org

2. 构建 vue-cli 项目

• 打开cmd，进入想要创建项目的目录下，输入：vue init webpack vue-ui-docs,回车

• 等待初始化完成根据控制台输入命令完成接下去的操作

  • Project name:——项目名称
  • Project description:——项目描述
  • Author:——作者
  • Vue build:——构建模式，一般默认选择第一种
  • Install vue-router?:——是否安装引入 vue-router，这里选是，vue-router 是路由组件,后面构建项目会用到
  • Use ESLint to lint your code?:——这里强烈建议选 no 否则你会非常痛苦，eslint 的格式验证非常严格，多一个空格少一个空格都会报错，所以对于新手来说，一般不建议开启，会加大开发难度
  • Setup unit tests with Karma + Mocha ：——测试可以不安装
  • Setup e2e tests with Nightwatch ：——测试可以不安装

3. 构建完成初始化项目依赖

• 初始化完成目录结构

• 切换到目录 cd C:UsersjccfDesktopvue-ui-docs,执行命令npm install

• 开始安装依赖环境

• 依赖环境安装完成

4. 启动项目

• 打开cmd，进入到项目所在目录下，输入npm run dev,回车，启动项目

• 打开浏览器输入http://localhost:8080访问

5. 环境调整

• 目录结构调整和文件创建

├─examples  // 原 src 目录，改成 examples 用作示例展示
│  │  App.vue //主页文件
│  │  main.js //项目入口文件
│  │
│  ├─docs //markdown帮助文档文件夹
│  │
│  └─router
│          index.js //路由配置文件
│
├─src // 新增 src 用于编写存放组件
│  │  index.js  //组件集成统一访问文件配置
│  │
│  ├─components  //组件文件夹
│  ├─directives //自定义指令文件夹
│  ├─mixins //混入文件
│  └─styles //样式文件夹

• 由于目录调整需要调整对应的webpack配置才可以启动项目

  • 删除examples outerindex.js的无效代码
  • 找到uildwebpack.base.conf.js文件进行配置调整
  • 修改webpack的主文件入口

  entry: {
    app: ‘./examples/main.js‘,
  }

  • 修改webpack编译配置

  {
    test: /.js$/,
    loader: ‘babel-loader‘,
    include: [resolve(‘examples‘), resolve(‘src‘)]
  }

  • 修改App.vue的代码和引用
  • 启动项目npm run dev有错误就根据错误调整，直到可以正常访问不在报错

6. 解析markdown文件

• 通过markdown写帮助文档然后解析为页面，参考饿了么UI 组件库的使用 vue-markdown-loader
  将markdown文件解析为vue组件直接页面渲染,安装vue-markdown-loader直接执行命令

  npm install vue-markdown-loader --save-dev

• 配置webpack加载器解析markdown，在vue-loader.conf.js在属性rules追加配置加载器

module.exports = {
  module: {
    rules: [
      {
        test: /.md$/,
        loader: ‘vue-markdown-loader‘
      }
    ]
  }
};

• 在docs文件下创建第一个markdown文件，test.md

# test
> Hello World

• 配置路由

  routes: [{
    path: ‘/test‘,
    name: ‘test‘,
    component: r => require.ensure([], () => r(require(‘../docs/test.md‘)))
  }]

• 浏览器访问http://localhost:8080/#/test,正确的将markdown解析为 vue 组件并正确初始化路由

7. 解析代码块和示例生成

• 代码块示例

:::demo ### 描述标题

```html
<template>
    <img src="https://i.loli.net/2017/08/21/599a521472424.jpg" />
</template>
<script>
    console.log(1)
</script>
```

:::


```

• 将示例的markdown编译成以下效果

上面为代码执行示例，中间为描述信息，底部为代码示例

• 开发一个demo-block用于显示代码块的组件

<template>
  <div class="demo-block">
    <div class="demo-block-source">
      <slot name="source"></slot>
      <span class="demo-block-code-icon"
        v-if="!$slots.default"
        @click="showCode=!showCode"><img alt="expand code"
          src="https://gw.alipayobjects.com/zos/rmsportal/wSAkBuJFbdxsosKKpqyq.svg"
          class="code-expand-icon-show"></span>
    </div>
    <div class="demo-block-meta"
      v-if="$slots.default">
      <slot></slot>
      <span v-if="$slots.default"
        class="demo-block-code-icon"
        @click="showCode=!showCode"><img alt="expand code"
          src="https://gw.alipayobjects.com/zos/rmsportal/wSAkBuJFbdxsosKKpqyq.svg"
          class="code-expand-icon-show"></span>
    </div>
    <div class="demo-block-code"
      v-show="showCode">
      <slot name="highlight"></slot>
    </div>
  </div>
</template>
<script type="text/babel">

export default {
  data() {
    return {
      showCode: false
    };
  }
};
</script>
<style>
.demo-block {
  border: 1px solid #ebedf0;
  border-radius: 2px;
  display: inline-block;
  width: 100%;
  position: relative;
  margin: 0 0 16px;
  -webkit-transition: all 0.2s;
  transition: all 0.2s;
  border-radius: 2px;
}
.demo-block p {
  padding: 0;
  margin: 0;
}
.demo-block .demo-block-code-icon {
  position: absolute;
  right: 16px;
  bottom: 14px;
  cursor: pointer;
  width: 18px;
  height: 18px;
  line-height: 18px;
  text-align: center;
}
.demo-block .demo-block-code-icon img {
  -webkit-transition: all 0.4s;
  transition: all 0.4s;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  position: absolute;
  left: 0;
  top: 0;
  margin: 0;
  max-width: 100%;
  width: 100%;
  vertical-align: baseline;
  -webkit-box-shadow: none;
  box-shadow: none;
}
.demo-block .demo-block-source {
  border-bottom: 1px solid #ebedf0;
  padding: 20px 24px 20px;
  color: #444;
  position: relative;
  margin-bottom: -1px;
}
.demo-block .demo-block-meta {
  position: relative;
  padding: 12px 50px 12px 20px;
  border-radius: 0 0 2px 2px;
  -webkit-transition: background-color 0.4s;
  transition: background-color 0.4s;
  width: 100%;
  -webkit-box-sizing: border-box;
  box-sizing: border-box;
  font-size: 14px;
  color: #444;
  font-size: 14px;
  line-height: 2;
  border-radius: 0;
  border-bottom: 1px dashed #ebedf0;
  margin-bottom: -1px;
}
.demo-block .demo-block-meta code {
  color: #444;
  background-color: #e6effb;
  margin: 0 4px;
  display: inline-block;
  padding: 3px 7px;
  border-radius: 3px;
  height: 18px;
  line-height: 18px;
  font-family: Menlo, Monaco, Consolas, Courier, monospace;
  font-size: 14px;
}
.demo-block .demo-block-code {
  background-color: #f7f7f7;
  font-size: 0;
}
.demo-block .demo-block-code code {
  background-color: #f7f7f7;
  font-family: Consolas, Menlo, Courier, monospace;
  border: none;
  display: block;
  font-size: 14px;
  padding: 16px 32px;
}
.demo-block .demo-block-code pre {
  margin: 0;
  padding: 0;
}
.sh-checkbox {
  color: #444;
  font-weight: 500;
  font-size: 14px;
  position: relative;
  cursor: pointer;
  display: inline-block;
  white-space: nowrap;
  user-select: none;
}
</style>

• vue-markdown-loader依赖了highlight在App.vue的样式中引用进行代码着色，风格参照highlight.js自己引用

 @import ‘highlight.js/styles/color-brewer.css‘;

• 在main.js配置全局安装组件，让每个md文件都可以自动编译成 vue 组件并且渲染代码块

import DemoBlock from ‘./components/demo-block.vue‘
Vue.component(‘demo-block‘, DemoBlock)

• webpack.base.conf.js配置vue-markdown-loader的options属性
  • 将demo代码块解析，在 markdown 用demo-block组件包裹
  • 安装npm install markdown-it-container --save-dev
  • 对 options 进行配置完成效果渲染

const markdownRender = require(‘markdown-it‘)();

{
  test: /.md$/,
  loader: ‘vue-markdown-loader‘,
  options: {
    preventExtract: true,
    use: [
      [require(‘markdown-it-container‘), ‘demo‘, {

        validate: function (params) {
          return params.trim().match(/^demos+(.*)$/);
        },

        render: function (tokens, idx) {
          if (tokens[idx].nesting === 1) {
            // 1.获取第一行的内容使用markdown渲染html作为组件的描述
            let demoInfo = tokens[idx].info.trim().match(/^demos+(.*)$/);
            let description = (demoInfo && demoInfo.length > 1) ? demoInfo[1] : ‘‘;
            let descriptionHTML = description ? markdownRender.render(description) : ‘‘;
            // 2.获取代码块内的html和js代码
            let content = tokens[idx + 1].content;
            // 3.使用自定义开发组件【DemoBlock】来包裹内容并且渲染成案例和代码示例
            return `<demo-block>
            <div class="source" slot="source">${content}</div>
            ${descriptionHTML}
            <div class="highlight" slot="highlight">`;
          } else {
            return ‘</div></demo-block>
‘;
          }
        }
      }]
    ]

  }
}

• 重新运行npm run dev得到预期的效果

• 对App.vue样式和排版布局进行调整
  

8. 开发第一个组件

• 开发一个按钮组件，在srccomponents下开发kt-button.vue按钮组件

<template>
    <div class="kt-button">
      <slot></slot>
    </div>
</template>
<script>
export default {
    name: ‘KtButton‘
}
</script>
<style>
.kt-button {
  border: 1px solid #41a259;
  background-color: #41a259;
  display: inline-block;
  border-radius: 2px;
  height: 14px;
  line-height: 14px;
  color: #fff;
  padding: 10px 19px;
  cursor: pointer;
  white-space: nowrap;
}
</style>

• 在examplesdocs下创建button.md进行文档编写和代码示例

# Button 按钮

## 基础用法

:::demo 通过`plain`属性可以设置为朴素的按钮

```html
<kt-button>确认</kt-button>
```

:::

```

• 路由配置

export default new Router({
  routes: [
    {
      path: ‘/test‘,
      name: ‘test‘,
      component: r => require.ensure([], () => r(require(‘../docs/test.md‘)))
    },
    {
      path: ‘/button‘,
      name: ‘button‘,
      component: r => require.ensure([], () => r(require(‘../docs/button.md‘)))
    }
  ]
})

• 首页链接配置

<router-link to="/button">button 组件</router-link>

• 配置src下的的index.js

import KtButton from ‘./components/kt-button.vue‘

const components = [KtButton]

export default function(Vue) {
  components.map(component => {
    Vue.component(component.name, component)
  })
}

• main.js安装所有的组件，让所有的docs下的md文件都可以调用

import install from ‘../src/index‘
install(Vue)

• 效果预览，组件开发完成
  

8. 项目代码

• 代码下载：github

• 示例演示： shui.kitorv.com