vue组件文档生成工具,vue 文档生成
在我们的印象中，vue除了写业务代码，并没有什么特别新颖的功能。今天，我们来看看如何自动生成vue组件文档。
:
目录
1.现状2。社区解决方案2.1。业务梳理3。技术解决方案3.1。Vue文件分析3.2。信息提取3.2.1。3.2.2可以直接获得的信息。需要同意的信息4。总结5。展望。
一、现状
Vue框架广泛应用于前端开发。当一个很多人开发的Vue项目维护时间长了，就会沉淀出很多共同的成分。这时候往往一个人开发一个组件，其他维护人员或者新人都不知道这个组件是做什么的，怎么用。他们要重新翻看一遍源代码，或者根本没有注意到这个组件的存在，导致重复开发。这时候维护相应的组件文档，保证不同开发者之间良好的合作关系，就非常有必要了。
但是传统的手工维护文档会带来新的问题：
效率低，写文档是个费时费力的手工活，开发完组件就很难再有时间写文档了。很难去想。
容易出错，文档内容容易出错，可能与实际组件内容不一致。
不，它是智能的。当组件被更新和迭代时，需要手动地将更改同步到文档中，这需要时间并且容易错过。
而文档维护的理想方式是：
工作量很小，可以通过组合Vue组件自动获取相关信息，减少从零开始写文档的工作量。
信息准确，组件关键信息与组件内容一致，没有错误。
同步，Vue组件迭代升级时，文档内容可自动同步更新，无需手动检查信息是否一致。
二、社区解决方案
2.1、业务梳理
为了达到以上的理想效果，我在社区里搜索研究解决方案。目前Vue官方提供了可以用来快速构建Vue项目文档的Vue-press，并且已经有了可以自动提取Vue组件信息的库。
然而，现有的第三方库并不能完全满足要求，主要存在以下两个问题：
信息不完整，一些重要的内容无法获取，比如v-model无法处理，属性的修饰符sync无法解析，方法中函数参数的详细信息无法获取。
比如在下面的例子中，value属性和input事件可以组合成一个v-model属性，但是这个信息并没有反映在生成的文档中，所以文档读者要自己去理解和判断。此外，生成的文档没有显示是否支持同步。
自定义logo比较多，logo的命名过于个性化，所以对原代码的入侵比较大。比如下图所示的代码，为了标记注释，需要在原业务代码中添加 @vuese @arg 等标记，使得业务代码有了一些与业务无关的内容。
三、技术方案
针对上面提到的问题和社区方案的不足，我们团队里沉淀了一个小工具，获取Vue组件信息，输出组件文档。一般效果如下：
上图中，左边是常见的Vue单文件组件，右边是生成的文档。我们可以看到，我们已经成功地从组件中提取了以下信息：
组件的名称。
组件的描述。
道具、位置、事件、方法等。
组件的注释内容。
接下来，我们将详细解释如何从组件中提取这些信息。
3.1、Vue文件解析
既然是从Vue组件中提取信息，那么第一个问题就是如何解析Vue组件。Vue官方开发了Vue解析的Vue-template-compiler库，我们在这里也可以用同样的方式处理。通过查阅文档，我们可以知道Vue-template-compiler提供了一个parseComponent方法来处理原始的Vue文件。
从“Vue-template-compiler”导入{ parseComponent }
const result=parse component(VueFileContent，[选项])
处理结果如下，其中模板和脚本分别对应Vue文件中模板和脚本的文本内容。
导出接口SFCDes
模板：SFCBlock undefined
脚本：SFCBlock undefined
styles:sfc block[]；
custom blocks:sfc block[]；
}
当然，仅仅获得文本是不够的，还需要对文本进行进一步的处理以获得更多的信息。拿到脚本后，我们就可以用babel把js编译成js的Ast(抽象语法树)了。这个AST是一个普通的js对象，可以通过js进行遍历和读取。有了AST，我们可以得到我们想到的详细的组件信息。
从“@babel/parser”导入{ parse }；
const jsAst=parse(script，[options])；
接下来我们看模板，继续找Vue-template-compiler的文档。我们找到compile方法，专门用来把模板编译成AST，刚好符合要求。
从“Vue-template-compiler”导入{ compile }
const template ast=compile(template，[options])；
结果中的ast是模板的编译结果。
导出接口编译结果{
ast:作为一个元素，
渲染：字符串，
staticRenderFns: Arraystring，
错误：数组字符串
}
通过第一步的文件解析，我们成功的在脚本中获得了Vue的模板ast和js的AST，然后我们就可以从它们那里得到我们想要的信息。
3.2、信息提取
根据是否需要协议，信息可以分为两种类型：
一种是可以直接从Vue组件中获取，比如道具、事件等。
另一个需要额外的约定格式，如组件描述、道具属性描述等。可以放入注释中，通过解析注释获得。
为了方便从ast中读取信息，这里简单介绍一个工具@babel/traverse。这个库是由babel官方提供的，用于遍历js AST。使用方式如下：
从“@babel/traverse”导入导线
遍历(jsAst，options)；
在options中配置相应内容的回调函数，就可以得到想要的ast节点。具体使用请参考官方文件。
3.2.1、可直接获取的信息
可以直接从代码中获取信息，可以有效解决信息同步的问题。无论代码如何变化，文档的关键信息都能自动同步，省去了人工校对的麻烦。
可以直接获得的信息是：
组件道具
提供外部调用的方法。
事件
时间
1和2可以通过traverse直接在js AST上遍历名为props和methods的对象节点来获得。
获取的事件有点麻烦。可以通过查找$emit函数来定位事件的位置，而$emit函数可以在traverse中监听MemberExpress(复杂类型节点)，然后通过节点上的属性名是否为 $emit 来判断是否是事件。如果是事件，则读取$emit的父级中的arguments字段。参数的第一个元素是事件名称，后面的元素是事件参数。
这个。$emit(event ，arg)；
遍历(jsAst，{
MemberExpression(节点){
//确定它是否是事件
if(node . node . property . name=== $ emit ){
//第一个元素是事件名称
const event name=node . parent . arguments[0]；
}
}
});
成功获取事件后，再结合事件和道具，可以进一步判断道具中的两个特殊属性：
v-model的存在性：找出props中是否存在value属性，以及Events中是否存在输入事件来确定。
props的一个属性是否支持同步：判断事件的时间名称中是否存在以update开头的事件，事件名称与属性名称相同。
插槽的信息保存在上述模板的AST中。递归地遍历模板AST，找到一个名为slots的节点，然后就可以在这个节点上找到这个名称。
3.2.2、需要约定的信息
除了直接可用的组件信息之外，为什么还需要协议的附加部分？一是因为可以直接获取的信息内容比较单薄，不足以支撑一个比较完整的组件文档；其次，我们日常开发组件的时候，会写很多注释。如果能直接提取一些注释放到文档中，就能大大减少文档维护的工作量。
经过整理可以达成一致的有以下几项：
组件名称。
组件的整体介绍。
道具、事件、方法、槽位的文字描述。
方法标记和参考的详细描述。这些内容可以在评论中维护。之所以在注释中维护，是因为注释可以很容易地从上面提到的js AST和template AST中获取。当我们解析Vue组件信息时，我们可以一起解析这部分目标指令。
接下来，我们将重点讨论如何将提取的评论和评论与标注的内容进行匹配。
js中的评论根据立场不同可以分为引导性评论和尾随性评论。不同位置的注释将存储在相应的字段中。代码如下所示：
//头注释导出默认值{} //尾注释
分析结果
const exportNode={
类型：“ExportDefaultDeclaration”，
引导注释：[{
类型：注释行，
值：“标题注释”
}],
trailingComments: [{
类型：注释行，
值：“尾部注释”
}]
}
同样的位置，根据注释格式的不同，可以分为单行注释和块级注释。两个注释之间的差异将反映在CommentBlock的type字段中：
/* * *块级注释*//单行注释导出默认值{}
分析结果
const exportNode={
类型：“ExportDefaultDeclaration”，
引导注释：[
{
类型： CommentBlock ，
值：“块级注释”
},
{
类型：注释行，
值：“单行注释”
}
]
}
此外，从上面的分析结果中，我们还可以看到，注释节点是挂载在带注释的导出节点中的，这也解决了我们上面提到的另一个问题：如何获取注释和注释之间的关系——其实在编译代码的时候，babel已经为我们做好了。
在模板中查找注释的方法与注释内容的方法不同。模板中的注释节点像其他节点一样作为dom节点存在。在遍历节点时，我们可以通过判断isComment字段的值是否为true来确定它是否是注释节点。并且注释内容的位置在兄弟节点的最后一位：
！- template - slot注释节点/slot的注释
分析结果
const templateAst=[
{
isComment:没错，
文本：“模板的注释”，
类型：3
},
{
标签:“插槽”，
类型：1
}
]
知道了如何处理注释内容，我们就可以用注释做更多的事情。例如，您可以通过在方法的注释中指定一个标记@public来区分一个方法是私有方法还是公共方法。如果更详细，还可以参考另一个专门解析js注释的库js-DOC的格式，进一步解释方法的引用，丰富文档的内容。
我们只需要在获取注释内容后剪切并读取文本，例如：
导出默认值{
方法：{
/**
* @public
* @param {boolean}值参数描述
*/
显示(值){}
}
}
当然，为了避免对代码的过多干扰，我们仍然需要添加尽可能少的额外标识符。参考注释的格式和js-doc一样，主要是因为这种方案应用广泛，代码编辑器自动支持方便的编辑。
四、总结
编译组件文档是改善项目中前端开发人员协作的好方法，一个维护良好的文档会大大改善开发体验。如果可以进一步使用工具来自动化维护文档的过程，那么开发的幸福感就可以再次提高。
经过一系列的探索和尝试，我们成功找到了一种自动提取Vue组件信息的方案，大大减少了维护Vue组件文档的工作量，提高了文档信息的准确性。具体就是用vue-template-compiler处理Vue文件，得到模板的AST和js。有了这两个ast，你可以获得更详细的信息。我们来梳理一下目前生成的文档中可以获取的内容和方法：
至于拿到后是以Markdown还是json文件的形式输出内容，要看实际开发情况。
五、展望
我们这里讨论的是直接从单个Vue文件中获取信息并输出，但是和很多第三方组件库一样，比如elementUI的文档，不仅有组件信息，还有显示示例。如果一个组件库维护得比较好，那么一个组件应该有相应的测试用例。那么，能否提取构件的测试用例，实现构件文件中样本部件的自动提取呢？这也是一个值得研究的问题。
以上是分析如何自动生成vue组件文档的细节。更多关于自动生成vue组件文档的信息，请关注我们的其他相关文章！
郑重声明：本文由网友发布，不代表盛行IT的观点，版权归原作者所有，仅为传播更多信息之目的，如有侵权请联系，我们将第一时间修改或删除，多谢。