vdoc-parser：一个强大的 Vue Props 解析工具

在 Vue 组件开发中，我们经常需要为组件编写文档，特别是对于组件库的开发者来说。如何高效地从组件代码中提取 Props 信息并生成文档一直是一个痛点。今天为大家介绍一个轻量级的工具库 ------ vdoc-parser，它可以帮助我们自动解析 Vue 组件的 Props 定义，轻松生成 Markdown 文档。

为什么需要 vdoc-parser？

在开发 Vue 组件库时，我们通常需要：

1. 记录每个 Props 的类型、默认值和说明
2. 维护 Props 的版本信息（新增于哪个版本）
3. 确保文档与代码的一致性
4. 支持多种组件定义方式（Options API、Composition API、TypeScript）

手动维护这些信息不仅耗时，还容易出错。而 vdoc-parser 正是为解决这些问题而生。、

特性一览

• 🎯 支持 Vue 2.x 和 Vue 3.x
• 📦 支持多种文件格式：.vue、.js、.jsx、.ts、.tsx
• 🔄 支持多种导出方式：默认导出、具名导出
• 🎨 支持多种组件定义：defineComponent、defineProps、ComponentOptions
• 📝 支持从注释中提取详细信息
• 🚀 提供同步和异步 API
• 💪 完整的 TypeScript 支持

快速开始

安装

npm install vdoc-parser -D
# 或者
yarn add vdoc-parser -D
# 或者
pnpm add vdoc-parser -D

基础使用

假设我们有一个简单的 Vue 组件：

<script>
export default {
  props: {
    /**
     * @description 用户名
     * @version 1.0.0
     */
    username: {
      type: String,
      default: 'guest',
      required: true
    }
  }
}
</script>

使用 vdoc-parser 解析：

import { parseFile } from 'vdoc-parser'

const result = await parseFile('./UserProfile.vue')
console.log(result)

输出结果：

[
  {
    "name": "username",
    "type": "string",
    "description": "用户名",
    "default": "guest",
    "version": "1.0.0",
    "required": "true",
    "isEvent": false
  }
]

进阶使用

1. 解析 Setup 语法

<script setup lang="ts">
const props = defineProps({
  /**
   * @description 主题色
   */
  theme: {
    type: String,
    default: 'light'
  }
})
</script>

直接使用 parseFile 即可解析：

const result = await parseFile('./ThemeProvider.vue')

2. 解析具名导出的 Props

// props.ts
export const buttonProps = {
  /**
   * @description 按钮大小
   */
  size: {
    type: String,
    default: 'medium'
  }
}

需要指定导出类型和名称：

const result = await parseFile('./props.ts', {
  exportType: 'named',
  exportName: 'buttonProps',
  type: 'props'
})

3. 解析复杂类型

当使用 TypeScript 的 PropType 时：

import type { PropType } from 'vue'

export default defineComponent({
  props: {
    /**
     * @description 用户列表
     * @type {{key: 'User[]'}}
     */
    users: {
      type: Array as PropType<User[]>,
      default: () => []
    }
  }
})

vdoc-parser 会正确解析类型注释。

注释规范

vdoc-parser 支持以下注释标签：

• @description: 属性描述
• @version: 版本信息
• @type: 复杂类型定义
• @default: 复杂默认值

示例：

/**
 * @description 数据配置
 * @version 1.2.0
 * @type {{key: 'Record<string, any>'}}
 * @default { id: 1, name: 'default' }
 */

实战应用

生成 Markdown 表格

import { parseFile } from 'vdoc-parser'

async function generatePropsDocs(componentPath: string) {
  const props = await parseFile(componentPath)
  
  const header = '| 属性 | 说明 | 类型 | 默认值 | 版本 |\n| --- | --- | --- | --- | --- |'
  const rows = props.map(prop => {
    return `| ${prop.name} | ${prop.description} | ${prop.type} | ${prop.default} | ${prop.version} |`
  })
  
  return [header, ...rows].join('\n')
}

// 使用
const docs = await generatePropsDocs('./Button.vue')
console.log(docs)

自动化文档生成

结合 vdoc-parser 和 Node.js 的文件系统操作，我们可以批量处理组件文件：

import { parseFile } from 'vdoc-parser'
import { readdir, writeFile } from 'fs/promises'
import { join } from 'path'

async function generateComponentsDocs(componentsDir: string) {
  const files = await readdir(componentsDir)
  const vueFiles = files.filter(file => file.endsWith('.vue'))
  
  for (const file of vueFiles) {
    const props = await parseFile(join(componentsDir, file))
    const markdown = generateMarkdown(props) // 生成 markdown 内容
    await writeFile(
      join('docs', `${file.replace('.vue', '.md')}`),
      markdown
    )
  }
}

最佳实践

1. 统一注释风格：在团队中统一使用 vdoc-parser 的注释规范
2. 自动化集成：将文档生成集成到构建流程中
3. 版本管理 ：善用 @version 标注新增的 Props
4. 类型声明 ：对于复杂类型，使用 @type 显式声明

总结

vdoc-parser 是一个强大而灵活的 Vue Props 解析工具，它可以：

• 大幅减少文档维护工作
• 确保文档与代码的同步
• 支持多种 Vue 组件定义方式
• 提供友好的 TypeScript 支持

对于 Vue 组件库的开发者来说，vdoc-parser 是一个不可多的工具。它不仅能提高开发效率，还能确保文档的准确性和一致性。

相关链接

• GitHub 仓库
• Gitee 仓库
• npm 包

如果你觉得这个工具有帮助，欢迎给个 Star ⭐️！

---

作者：hui.wang

本文首发于掘金，转载请注明出处。