前前言
随着前端的内卷，人均写组件库，但在笔者认为大部分组件库都是在相互学习借鉴，并无太多创新的地方，重复轮子意义并不大，笔者将从另一个视角来为组件库开发贡献一份力
前言
我们在写组件库的时候，通常需要为组件写文档，在写组件时我们定义好了props，最终还需要写文档给到用户使用，这让工作变得繁琐，这时我们可能希望能直接使用组件定义的props，这样能做到实时同步且省时省力(手动修改文档很可能发生我们更新了组件但却忘了更新文档，且耗时耗力)，最直接的方案是通过解析props，然后转换到markdown上显示。
这里采用的是vitepress，其他文档工具类似，核心都在于解析interface
如何解析interface
最简单的是采用@babel/parser · Babel 中文网 (babeljs.cn)
当然作者也尝试过使用typescript解析器直接解析，结果是比较繁琐，且解析结果需要多次二次处理，比较耗时.
import { parse } from '@babel/parser'
export function parseCode(code: string): ParseResult<any> {
return parse(code, {
sourceType: "module",
plugins: ['typescript'],
});
}
parseCode('code') // return => ast
注意：这里我们还需要考虑plugins可能需要解析其他文件类型，我们简化流程，目前只支持typescript文件
定义返回格式
通常我们组件所需传递的props能写出如下格式
export interface Props {
/**
* 描述a是干啥的
* @default 默认值是啥呢？
*/
a: string
b: number
}
通过babel/parser 我们可以解析出AST结构的东西，然后再遍历ast，进行transform，最终我们可以得出一个业务所需的JSON数据，具体逻辑在vitepress-plugin-props2table中 这里不再贴源码，返回大致如下：
export interface InterfaceDefinition {
/**
* 属性名
*/
name: string;
/**
* 属性类型
*/
type: string;
/**
* 是否必填
*/
required: boolean;
/**
* 所有注释都将解析到这里
*/
comments: Record<string, string>
}
至此，我们已经可以得到解析结果，接下来是如何显示到markdown中
添加 vite plugin
虽然我们已经能解析interface，但是我们需要和文档进行关联，笔者这里的做法是直接在markdown上添加一个路径，用于替换为解析的结果，类似 VitePress 中的 <<< @/filepath这种形式
注: 当然可以直接拼接解析，不再手动在md文档上写，效果类型，使用方式不同，思路相同
我们定义解析的规则如下：
@props2table(filepath, configId, propsId)
- file path为要解析的文件路径
- config id 为可能用户需要自定义解析的表格样式
- props id 可能是用户仅需要解析某一个interface
注：也就说我们直接在.md文档上写上@props2table(filepath, configId, propsId)然后替换为表格
定义好规则后我们需要匹配正则表达式以进行替换，/@props2table\((.+)\)/g
最后取得用户录入的正则，获取用户填入的参数，进行表格拼接替换即可
在哪里替换？这是一个问题，这涉及到plugin的开发，我们通常在transfrom中进行替换操作,如下：
export function props2table(
config: PluginConfig = {},
parsePlugins?: ParserPlugin[]
): Plugin {
dir = getCallerFile()
return {
enforce: 'pre',
name: 'props2table',
transform(code, id) {
// 以md的结尾的才进行转换
if (id.endsWith('.md')) {
// replaceCode2table函数的作用如上所述 用来将json数据拼接处表格
const { importPath, code: tableCode } = replaceCode2table(code,config)
return {
code: tableCode + hmrCode(importPath),
}
}
},
}
}
// 使用 => 在vite.config.ts中
import { defineConfig } from 'vite'
// 导入上方我们写的逻辑
import { props2table } from '../src/index'
export default defineConfig({
plugins: [
props2table(),
],
})
热更新
可以看到plugin只有简单的一段逻辑 也就是拦截下markdown文件进行查找替换处理，其次我们可以发现多了一个hmrCode函数，通过函数名可以得知，是用于热更新的，为什么需要热更新呢？
因为我们在markdown直接写@props2table("../src/假设一个文件路径.ts") 当文件内容更新时，页面并不会重新更新，因为vite并未解析到你使用了该文件的内容。
因此，我们需要手动的给它添加一个热更新逻辑，市面上大家使用插件都不关注热更新，比如plugin-vue类似的插件，是因为插件内部已经帮我们做好了更新逻辑，因此我们也需要加上这一块的更新，做法很简单，如下：
export function hmrCode(paths: string[]) {
return `
<script setup>
const hmrFiles = import.meta.glob(${JSON.stringify(paths)}, { eager: true })
</script>
`
}
我们直接给code加上一段引用，paths 是通过获取用户录入的文件路径，然后传递给import.meta.glob即可实现，import.meta.glob的详细文档见vite官方import.meta.glob
效果
image.png
发布
细节实现见：yucccc/vitepress-plugin-props2table: 📃 Parsing interface Show as a table. (github.com)
结束语
目前我们已经能应付大部分的需求，但插件的开发还需要不断打磨完善，欢迎大家试用与贡献
网友评论