自定义组件的文档怎么写才规范？

IT人正利提问于 2026-03-05 12:00:21 阅读 7

组件

我刚封装了一个带搜索功能的下拉选择组件，但不知道怎么写配套的文档。现在团队要求每个组件都要有清晰的使用说明，但我试了直接贴代码，同事说看不懂 props 和事件怎么用。

比如我的组件是这样用的：

<searchable-select
  :options="userList"
  v-model="selectedId"
  placeholder="请选择用户"
  @change="handleSelect"
/>

那文档里到底该写哪些内容？props 列表、事件说明、插槽用法这些都要手写吗？有没有推荐的格式或者工具能自动生成一部分？

文档编写

我来解答赞 6 收藏

反馈

1 条解答

打工人梓希 Lv1

组件的文档确实很重要，不然同事用起来会骂娘。我一般会分这几个部分写，比直接贴代码清晰多了：

1. 基础用法
直接给个最简单的例子：

<searchable-select 

  :options="[{id:1, name:'张三'}]"

  v-model="selectedId"

/>

2. Props表格
列清楚每个属性的用途和类型：
options：选项数组，必填，格式[{id, name}]
v-model：双向绑定的选中值
placeholder：提示文字，选填，默认'请选择'

3. 事件说明
比如你那个@change：
触发时机：选项变更时
回调参数：(selectedItem, oldItem)

4. 插槽用法（如果有）
比如自定义选项展示：

<template #option="{ item }">

  {{ item.name }} (ID: {{ item.id }})

</template>

工具推荐用VuePress或者Storybook，它们能自动从代码注释生成部分文档。但关键的用法示例还是得手动写，不然生成的文档也像屎一样难用。

我自己的习惯是在组件文件顶部用JSDoc写注释，这样既能给工具用，自己看代码也方便。比如：

/**

 * 带搜索功能的下拉选择器

 * @prop {Array} options - 选项列表

 * @event change - 选择变更事件

 */

写文档最烦的是要经常维护，所以越简单直接越好，别整那些花里胡哨的。

2026-03-05 12:04