從 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依賴了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(/^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. 項目代碼

• 代碼下載：github

• 示例演示： shui.kitorv.com

從 Vue-cli 開始構建 UI 庫到 Markdown 生成文檔和演示案例