关于TypeDoc是个什么鬼及其使用,可以阅读之前那篇文章

typedoc使用笔记

以下记录TOC二级菜单插件的开发

先明确你自己的需求,你要做什么?现有的插件有没有能满足你的,如果有类似的,改改是否能用?如果毛都没有,那就从头写吧!

造轮子有一定代价,官网如果没有良好的教程指导,那将会很令人神伤。而TypeDoc就是这样,至少我谷歌了好久,没找到类似教程的东西,索性一把梭的去看了好多插件的源码实现。还好明白套路…

插件的作用无外乎是对原有的系统做了些许扩展。其原理在于某个时刻做某些拦截,然后构造必要的数据,然后再根据主题模板进行文件输出渲染。比如我们要改造TOC模块,使其支持二级栏目:

1. GitHub找到TypeDoc源码,找到TOC模块所在

TocPlugin.ts


initialize() {
this.listenTo(this.owner, {
[PageEvent.BEGIN]: this.onRendererBeginPage
});
}

private onRendererBeginPage(page: PageEvent) {
// 以上省略.... 可以看到这里,右边原有的TOC目录树就是从这里生成数据。而我们要改的可能也在这里
TocPlugin.buildToc(model, trail, page.toc, tocRestriction);
}

2. 研究其他插件的入口文件index.js,我们可以发现

所有插件都有类似的注册方法,即:你的插件名称,功能需要挂接到文档系统。当开始生成数据时,收到事件后开始构造需要的数据结构


const P = require('./plugin');

module.exports = function(PluginHost) {
const app = PluginHost.owner;

// 如果已经注册过了,就别再重复注册
if (app.converter.hasComponent(P.PLUGIN_NAME)) {
return;
}
if (app.renderer.hasComponent(P.PLUGIN_NAME)) {
return;
}

// 此处声明插件名称
app.options.addDeclaration({ name: P.PLUGIN_NAME, short: P.PLUGIN_SHORT_NAME });

// 监听数据变化
app.converter.addComponent(P.PLUGIN_NAME, P.TocGroupPlugin);

// 监听页面渲染
app.renderer.addComponent(P.PLUGIN_NAME, P.TocGroupPlugin);
};

3. 做必要的监听及数据模型构造

研究TOC主题模板可以看到下图所示,其实最终读的就是toc这个变量里的children。而要改造的就是把标签内容再包一层,塞到这个变量里。弄成二维数组即可。

需要注意的是,一定要在initialize方法里正确的监听事件。否则拿不到你要的值。正确监听的前提还必须是在index.js里正确注册。

比如要处理PageEvent事件,就要监听rendered类型;处理Converter事件,就要监听converter类型。

获取文档中指定注解名称和内容


// 1. initialize里监听: [Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve,
// 2. onBeginResolve回调中拿到Context,根据需求取或存数据
const groupedData = [];
const deprecatedData = new Set();
const mapedTocData = {};
const reflections = context.project.reflections;
for (const key in reflections) {
const ref = reflections[key];
const comment = ref.comment;
const homePath = `modules/_index_.${context.project.name.replace(/\-/g, '')}.html`;

if (!comment || !comment.tags) continue;

for (const tag of comment.tags) {
// add deprecated item names
if (DEPRECATED_REGEXP.test(`@${tag.tagName}`)) deprecatedData.add(ref.name);
// add special tags
if (this.regexp.test(`@${tag.tagName}`)) {
groupedData.push(ref.name);
const groupKey = tag.text.split(/\r\n?|\n/)[0];
if (!mapedTocData[groupKey]) mapedTocData[groupKey] = [];
mapedTocData[groupKey].push(ref.name);
break;
}
}
}

// 以上构造的数据需要存到Context中,试过插件的成员变量,但是在其他事件回调中拿不到成员变量的值,事件关系没有深扒....
context.project[PLUGIN_NAME] = { groupedData, deprecatedData, mapedTocData, homePath };

构造我们所需要的数据

请直接参考这里代码:buildGroupTocContent

4. 测试功能

将插件目录下的文件组织好,配置编译命令。然后拷贝到node_modules下,执行typedoc构建时,将会自动加载插件,无需手动配置:

Loaded plugin xxx/node_modules/typedoc-plugin-toc-group

如果控制台能打印类似的这条命令,那恭喜,你的新插件已经成功加载了。然后剩下的就是反复调试。直到实现你要的功能即可。

5. 定制主题

默认情况下,数据结构有了,页渲染出你要的结果了。但是可能长相不太好看。这时你就要定制一下默认的主题了。思路就是猜测你的功能所在的文件,然后去改造他。比如上面截图那个。

改完了之后,你可以选择提交到npm,也可以放到自己项目中,用路径的方式去引用。

6. 总结一下

  1. 明确需求,猜测与你功能相关的代码在哪里,去看源码;
  2. 研究其他插件或主题的目录结构,搭建自己的插件或主题目录结构;
  3. 入口文件注册事件,监听事件。拿到注解上的内容;
  4. 当页面开始渲染时,根据注解去解析、拼凑你要的数据结构;
  5. 将原来的数据结构从内部改掉(注意别改的太离谱否则加载会崩溃);
  6. 数据没问题后,定制主题。改成你喜欢的样子;

就写到这里,有不明白了。可以文章后留言,或者直接去看我写的这个主题。