04.ElementUI源碼學習:組件封裝、說明文檔的編寫發布

0x00.前言

書接上文。項目經過一系列的配置,開發腳手架已經搭建完畢。接下來開始封裝自定義組件、並基於 markdown 文件生成文檔和演示案例。

后續文章代碼會根據篇幅，不影響理解的情況下進行部分刪減，詳細代碼可在 Github Repo 查看。

0x01.封裝第一個組件

封裝組件

接下來封裝一個loading組件。

創建 packages/loading/src/main.vue 文件(篇幅問題，樣式代碼詳見Github)。

創建 packages/loading/index.js 文件。使用 install 方法來全局注冊該組件，安裝組件通過全局方法 Vue.use() 即可。官網-Vue插件

創建 src/index.js 文件,該文件的作用:

1. 導入組件庫所有組件
2. 定義組件庫組件注冊安裝的install 方法
3. 整體導出版本、install、各個組件等。

引用組件

在 examples/main.js 文件中引用組件庫

在 examples/App.vue 中添加組件引用

頁面效果如下

0x02.編寫組件說明文檔

接下來基於 markdown 編寫組件文檔，能讓示例代碼像組件一樣在頁面中渲染。

md-loader

markdown 文件的解析基於markdown-it 及其社區插件。

1. markdown-it 主要的解析器/渲染器。官方文檔
2. markdown-it-anchor 生成標題錨點。官方文檔
3. markdown-it-container 創建塊級自定義容器的解析插件。官方文檔
4. markdown-it-chain 支持鏈式調用 markdown-it 。官方文檔

npm i  -D  markdown-it markdown-it-anchor markdown-it-container markdown-it-chain

其他核心插件

npm i -D transliteration // 漢字轉拼音

自定義loader
項目將使用element的自定義loader，在源碼目錄 build\md-loader 創建文件，目錄結構如下。

├─md-loader
|     ├─config.js
|     ├─containers.js
|     ├─fence.js
|     ├─index.js
|     └─util.js

index.js文件是loader的入口文件，通過提取template 與 script 的內容，把 Markdown 轉化成 Vue 組件。

config.js文件使用 markdown-it-chain 配置markdown-it選項、插件和容器信息，初始化markdown-it實例。

containers.js文件使用 markdown-it-container 來轉換自定義容器,將自定義容器 :::demo轉換成 demo-block 組件。

fence.js文件中重寫了代碼塊（fence）默認渲染規則。

util.js文件提供 stripScript stripStyle stripTemplate genInlineComponentText等方法用於頁面內容提取和生成組件。

webpack 配置

創建build/config.js文件設置 webpack 公共配置信息。

更新 build\webpack.config.js文件，添加自定義 md-loder ，實現 markdown 文件的解析。

編寫文檔

編寫組件說明文檔examples\docs\loading.md

安裝 vue-router 插件。

npm i -D vue-router  

新增 examples/router.js 文件配置路由信息。

import Vue from 'vue';
import VueRouter from 'vue-router';

Vue.use(VueRouter);

const routes = [
  {
    path: '/',
    name: 'index',
    //使用vue的異步組件技術 , 可以實現按需加載 .
    component: (resolve) => require(['./components/HelloWorld.vue'], resolve), 
  },
];

routes.push({
  path: '/test',
  name: 'test',
  component: (resolve) => require(['./docs/loading.md'], resolve),
});

routes.push({
  path: '/jsx',
  name: 'jsx',
  component: (resolve) => require(['./components/JSX.vue'], resolve), 
});

export default new VueRouter({
  mode: 'hash',
  base: process.env.NODE_ENV !== 'production' ? '/' : '/me-ui',
  routes,
});

調整 examples 目錄下文檔結構如下，詳見源碼。

├─examples
|    ├─App.vue
|    ├─main.js
|    ├─router.js
|    ├─docs
|    |  └loading.md
|    ├─components
|    |     ├─HelloWorld.vue
|    |     └JSX.vue
|    ├─assets
|    |   └logo.png

examples\main.js 引入路由，examples\App.vue 更新路由導航信息。

// main.js
...
...
import router from './router'; 
...
new Vue({
  router,
  render: (h) => h(App),
}).$mount('#app');

// App.vue
<template>
  <div id="app">
    <div id="nav">
      <router-link to="/">Home</router-link> | <router-link to="/jsx">JSX</router-link> |
      <router-link to="/test">loading組件</router-link>
    </div>
    <router-view />
  </div>
</template>

頁面效果如下

demo-block 組件

上面的說明文檔功能十分簡陋，接下來編寫 demo-block 組件,支持示例組件渲染、高亮代碼等功能。

安裝語法高亮插件 highlight.js 。

npm i -D highlight.js    // 代碼高亮

創建 examples\components\demo-block.vue 組件

examples\main.js 引入 highlight 插件、 demo-block 組件，配置語法高亮主題樣式。增加 afterEach 全局后置鈎子,高亮頁面代碼塊。

組件說明文檔 examples\docs\loading.md 更新成約定的文檔格式。

運行程序，頁面示例代碼塊渲染組件，可以展開收起源代碼，語法高亮顯示，效果如下：

0x03.示例代碼

Github Repo

0x04.參考

Element 文檔中的 Markdown 解析
element的demo-block
highlight 97種主題樣式列表