kitorv 阅读(20) 评论(0)

从 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:\Users\jccf\Desktop\vue-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\router\index.js的无效代码
    • 找到\build\webpack.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依赖了highlightApp.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-loaderoptions属性
    • 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(/^demo\s+(.*)$/);
        },

        render: function (tokens, idx) {
          if (tokens[idx].nesting === 1) {
            // 1.获取第一行的内容使用markdown渲染html作为组件的描述
            let demoInfo = tokens[idx].info.trim().match(/^demo\s+(.*)$/);
            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>\n';
          }
        }
      }]
    ]

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

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

8. 开发第一个组件

  • 开发一个按钮组件,在src\components下开发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>
  • examples\docs下创建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. 项目代码