组件文档编写规范（AI 参考）
本文件是 给 AI 工具阅读的组件文档格式规范，确保所有组件文档风格统一。
VitePress 不会路由_开头的文件，此文件仅作为内部规范。
一、文件结构总览
每篇组件文档 必须 按以下顺序包含这些章节（可选章节标注 [可选]）：
1. Frontmatter
2. # 标题
3. > 一句话描述
4. ## 🚀 在线演示
5. ## ✨ 特性
6. ## 📦 安装
7. ## 🎯 快速开始
8. ## 📖 API 文档
9. ## 🎨 使用示例 [可选 — 复杂组件推荐]
10. ## ⚠️ 注意事项 [可选]
11. ## 🔧 常见问题
12. ## 📝 更新日志
13. ## 📚 相关资源
14. ## 🤝 贡献指南
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request
:::tip 组件位置
npm 包源码: `naive-ui-components/src/components/C_【组件名称】/index.vue`
npm 包地址: [@robot-admin/naive-ui-components](https://www.npmjs.com/package/@robot-admin/naive-ui-components)
:::
## 📄 许可证
Copyright (c) 2025 by ChenYu, All Rights Reserved.
---
15. **💡 提示**: ...1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
二、逐章节格式详解
2.1 Frontmatter
yaml
---
outline: "deep"
---1
2
3
2
3
- 固定写法，无其他字段
2.2 标题
markdown
# C_ComponentName 中文功能描述1
- 组件名使用
C_前缀 + PascalCase - 空格后跟简短中文功能名（2-6 字）
2.3 一句话描述
markdown
> 🎯 配置化管理任何场景的按钮组，支持分组布局、下拉菜单、响应式控制1
- 以
>引用块开头 - emoji + 一句话概括核心能力（30-80 字）
- 列举 3-5 个亮点关键词
2.4 在线演示
markdown
## 🚀 在线演示
<DemoIframe src="/preview/component-name" title="中文标题" height="700" />1
2
3
2
3
src规则：/preview/+ 组件名小写（kebab-case 或全小写连写）height：默认700，简单组件可用600- 某些仅在 Robot Admin 内体验的组件可用文字提示代替
2.5 特性
markdown
## ✨ 特性
- **🎨 配置化驱动**: 通过 `ActionItem[]` 数组声明式配置按钮
- **📐 分组布局**: 左右分组（`leftActions` / `rightActions`）+ 中间自定义 slot
- **⚡ 响应式控制**: `loading` / `disabled` / `show` 均支持 `Ref` 响应式值
- **💪 TypeScript**: 完整类型定义1
2
3
4
5
6
2
3
4
5
6
格式要求：
- 每行
- **emoji 特性名**: 描述 - 特性名加粗，冒号后有空格
- 代码中的属性名/类型名用
`包裹 - 3-8 条为宜
- 最后一条固定为
**💪 TypeScript**: 完整类型定义
2.6 安装
markdown
## 📦 安装
::: code-group
\`\`\`bash [bun (推荐)]
bun add @robot-admin/naive-ui-components
\`\`\`
\`\`\`bash [pnpm]
pnpm add @robot-admin/naive-ui-components
\`\`\`
\`\`\`bash [npm]
npm install @robot-admin/naive-ui-components
\`\`\`
:::1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
- 固定写法，三种包管理器顺序固定：bun → pnpm → npm
- bun 标注
(推荐)
2.7 快速开始
markdown
## 🎯 快速开始
### 最简用法 / 基础使用
\`\`\`vue
<template>
<C_Component :prop="value" @event="handler" />
</template>
<script setup>
// 无需导入，已全局注册
</script>
\`\`\`
### 场景二标题
\`\`\`vue {3-4}
<!-- 带行号高亮的代码示例 -->
\`\`\`1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
格式要求：
- 第一个子标题为
### 最简用法或### 基础使用 - 代码块使用
vue语言标识 - 可用
{3-4}语法高亮关键行 - 需要时可加
> [!TIP]提示框 - 2-5 个用法示例为宜
2.8 API 文档
章节标题固定为 ## 📖 API 文档（不是 📋 API）
Props 表格
markdown
### Props
| 参数 | 类型 | 默认值 | 说明 |
| ----------- | ----------------- | ---------- | ---------------------- |
| **actions** | `ActionItem[]` | `[]` | 按钮列表 |
| **config** | `ActionBarConfig` | `{}` | 全局配置 |
| **loading** | `boolean` | `false` | 加载状态 |1
2
3
4
5
6
7
2
3
4
5
6
7
- 四列：
参数 | 类型 | 默认值 | 说明 - 参数名 加粗（
**propName**） - 类型名用反引号（
`Type`） - 默认值用反引号；无默认值时用
— - 必填参数在说明中标注
**（必填）** - 联合类型用
\|转义竖线
子类型/配置表格
markdown
### TypeName
| 字段 | 类型 | 默认值 | 说明 |
| ----------- | ----------------- | ---------- | -------------- |
| `fieldName` | `string` | `''` | 字段说明 |1
2
3
4
5
2
3
4
5
- 子类型表格字段名用反引号（与 Props 区分）
- 第一列标题为
字段（不是参数） - 无默认值概念时可省略默认值列（三列：
字段 | 类型 | 说明）
Events 表格
markdown
### Events
| 事件名 | 参数 | 说明 |
| ---------------- | -------------------- | ------------ |
| **action-click** | `(action: ActionItem)` | 按钮点击事件 |1
2
3
4
5
2
3
4
5
- 事件名 加粗
- 参数用反引号，包含括号和类型
- 无参数时用
—
Slots 表格
markdown
### Slots
| 插槽名 | 说明 |
| ---------- | ------------------ |
| **center** | 中间区域自定义内容 |1
2
3
4
5
2
3
4
5
- 插槽名 加粗
- 有作用域参数时增加
参数列
Expose / 暴露方法
markdown
### Expose 方法
| 方法名 | 类型 | 说明 |
| -------------- | --------------------- | ---------- |
| **validate** | `() => Promise<void>` | 全量验证 |1
2
3
4
5
2
3
4
5
- 方法名 加粗
- 类型使用函数签名格式
CSS 变量（可选）
markdown
### CSS 变量
| 变量 | 默认值 | 说明 |
| ------------------- | --------- | ---------- |
| `--c-prefix-name` | `#d1d5db` | 变量说明 |1
2
3
4
5
2
3
4
5
- 变量名用反引号
- 遵循
--c-组件名-属性名命名
类型定义
markdown
### 类型定义
\`\`\`typescript
interface ComponentProps {
prop: Type // 中文说明
}
\`\`\`1
2
3
4
5
6
7
2
3
4
5
6
7
- 复杂组件可用
::: details 🔧 类型定义 — 完整的 TypeScript 接口定义包裹 - 属性后用
//添加行内中文注释 - 子标题用
####
2.9 使用示例（可选）
markdown
## 🎨 使用示例
::: details 💡 场景标题 - 功能描述
\`\`\`vue
<template>
<!-- 完整示例 -->
</template>
\`\`\`
:::1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
- 每个示例用
::: details折叠 - 标题格式：
emoji 场景名 - 描述 - 常用 emoji：💡 🔑 ⚡ 🎯 📱
2.10 注意事项（可选）
markdown
## ⚠️ 注意事项
### 1. 注意点标题
::: code-group
\`\`\`vue [✅ 推荐]
<!-- 正确写法 -->
\`\`\`
\`\`\`vue [⚠️ 备选]
<!-- 备选写法 -->
\`\`\`
:::1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2.11 常见问题
markdown
## 🔧 常见问题
::: details ❌ 问题描述
解答文字 + 代码示例
:::1
2
3
4
5
6
7
2
3
4
5
6
7
- 每个问题用
::: details ❌ 问题描述包裹 - 2-4 个常见问题为宜
2.12 更新日志
markdown
## 📝 更新日志
### v0.6.0 (2026-02-14)
- ✨ 新增 `ComponentName` 组件
- ✨ 支持 xxx 功能
- 🐛 修复 xxx 问题
- 📝 文档更新1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
- 标题固定为
📝 更新日志（不使用🔄 未来规划） - 版本号格式：
### vX.Y.Z (YYYY-MM-DD) - 条目前缀：✨ 新增 / 🐛 修复 / 📝 文档 / ♻️ 重构 / ⚡ 性能
2.13 相关资源
markdown
## 📚 相关资源
- [演示页面源码](../../views/demo/NN-component/index.vue)1
2
3
2
3
2.14 页脚
markdown
## 🤝 贡献指南
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request
:::tip 组件位置
npm 包源码: `naive-ui-components/src/components/C_【组件名称】/index.vue`
npm 包地址: [@robot-admin/naive-ui-components](https://www.npmjs.com/package/@robot-admin/naive-ui-components)
:::
## 📄 许可证
Copyright (c) 2025 by ChenYu, All Rights Reserved.
---
**💡 提示**: 针对该组件的特色描述，关联使用场景，鼓励社区反馈。emoji1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!--@include-->引入公共贡献说明（固定写法）**💡 提示**必须跟在 include 后面，空一行- 内容针对当前组件定制，60-150 字
- 末尾带一个主题相关 emoji
三、命名规则汇总
| 位置 | 规则 | 示例 |
|---|---|---|
| 文件名 | 小写 kebab-case | org-chart.md |
| 组件名（标题） | C_ + PascalCase | C_OrgChart |
| DemoIframe src | /preview/ + 小写（kebab 或连写） | /preview/orgchart |
| CSS 变量前缀 | --c-组件名-属性 | --c-orgchart-line-color |
| 演示页面源码 | ../../views/demo/NN-name/ | ../../views/demo/56-orgchart/ |
四、参考文档
- 简单组件标杆：
action-bar.md（完整的 Props/Events/Slots + 使用示例 + 注意事项 + 更新日志 + 提示） - 中等组件标杆：
upload.md（分片上传多配置 + 完整 API） - 复杂组件标杆：
form.md/table.md（多子配置表、config 详解、架构概览）
核心原则：所有新文档必须对齐
action-bar.md的完整度和格式；复杂组件参考form.md增加架构概览和子配置表。