在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
<towxml nodes="{{doc}}"/>
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
})
}
})
