微信小程序组件文档工程实现方案---towxml转化本地markdown文件

在H5开发中，一套组件库的说明文档往往可以通过书写markdown的形式，通过各种开源插件转化，最终变为浏览器可解析的标签语言，开发者可直接通过浏览器来查阅相应组件说明。但微信小程序只能在微信开发者工具或真机中预览效果，而其对应的组件说明若想使用markdown进行转化，则只能通过官方推荐的towxml这一插件实现，而此插件仅支持转化在线MD文件，暂不支持直接将本地MD文件转化为微信小程序的wxml标签语言。尽管如此，我们还是找到了一种微信小程序组件文档工程的实现方案，最终实现效果如下图所示。本文着重说明towxml转化本地markdown文件的实现方法。

1 本地MD文件格式处理

1.1 将此脚本命名为genDoc.js，放至小程序项目根目录下

const fs = require('fs')
const path = require('path')

function genDocStr (mdDir) {
  let data = fs.readFileSync(path.join(mdDir, 'doc.md'), 'utf-8')
  data = data.replace(/\n/g, '\\n').replace(/\t/g, '\\t')
    .replace(/'/g, '\\\'')
  fs.writeFileSync(path.join(mdDir, 'doc.js'), 'const doc = \'' + data + '\'\nmodule.exports = doc\n')
}

function readDir (dir) {
  const dirInfo = fs.readdirSync(dir)
  dirInfo.forEach(item => {
    const location = path.join(dir, item)
    const info = fs.statSync(location)
    if (info.isDirectory()) {
      readDir(location)
    } else if (location.slice(-6) === 'doc.md') {
      genDocStr(dir)
    }
  })
}

readDir(path.join(__dirname, 'components'))

1.2 向package.json文件执行脚本中加入如下命令

"scripts": {
    "genDoc": "node ./genDoc"
  }

1.3 执行脚本

npm run genDoc

脚本会递归查找同级components目录下所有组件中的doc.md说明文件，并在其相同位置生成doc.js文件，该文件将doc.md中文件内容作为变量导出，具体形式如下：

• doc.md

# date-picker
## 1 引入
## 2 基本使用
## 3 属性
|参数|类型|可选值|默认值|必填|说明|
|:-:|:-:|:-:|:-:|:-:|:-:|
|show|Boolean|-|false|否|是否显示|
|value|String|-|当天|否|当前选择的日期|
|min|String|-|'1999/01/01'|否|日期选择最小值|
|max|String|-|'2099/12/31'|否|日期选择最大值|
|confirmText|String|-|'确认'|否|确认按钮文字|
|cancelText|String|-|'取消'|否|取消按钮文字|

• doc.js

const doc = '# date-picker\n## 1 引入\n## 2 基本使用\n## 3 属性\n|参数|类型|可选值|默认值|必填|说明|\n|:-:|:-:|:-:|:-:|:-:|:-:|\n|show|Boolean|-|false|否|是否显示|\n|value|String|-|当天|否|当前选择的日期|\n|min|String|-|\'1999/01/01\'|否|日期选择最小值|\n|max|String|-|\'2099/12/31\'|否|日期选择最大值|\n|confirmText|String|-|\'确认\'|否|确认按钮文字|\n|cancelText|String|-|\'取消\'|否|取消按钮文字|'
module.exports = doc

2 构建Towxml

2.1 克隆项目到本地

git clone https://github.com/sbfkcel/towxml.git

2.2 安装构建依赖

npm install

2.3 编辑配置文件towxml/config.js

根据自行要求，仅保留你需要的功能即可（配置中有详细注释）

运行 npm run build

3 使用方法

3.1 将构建出来的towxml解压至小程序项目根目录下，即（小程序/towxml）

3.2 在app.js中引入库

//app.js
App({
    // 引入`towxml3.0`解析方法
    towxml:require('/towxml/index')
})

3.3 在页面配置文件中引入towxml组件 /pages/index/index.json

{
  "usingComponents": {
    "towxml":"/towxml/towxml"
  }
}

3.4 在页面中插入组件/pages/index/index.wxml

3.5 解析内容并使用/pages/index/index.js

const app = getApp();
Page({
    data: {
       curCpt: {
          name: '日期选择',
          cptName: 'date-picker',
          docDir: 'form/datePicker'
       },
       doc: {}   // 内容数据
    },
    onLoad() {
        const source = require('../../components/' + this.data.curCpt.docDir + '/doc.js')
        const doc = app.towxml(source, 'markdown')
        this.setData({
          doc
        })
    }
})