QXS-BNS

Appearance

本页导航

创建文档必读 ​

这份文档用于约束组件文档、工具文档和示例文档的写法。
目标只有一个：让读者先看懂功能，再看 API，而不是先掉进一大块字段表。

文档目标 ​

写文档时优先回答下面三个问题：

  1. 这个组件 / 模块解决什么问题。
  2. 读者最常用的功能该怎么用。
  3. 需要查字段时，去哪里看 API。

如果一页文档没有先让读者看到 demo 和说明，而是直接进入大段字段表，这页文档基本就是反的。

推荐结构 ​

下面这张结构图可以直接当成所有文档页的骨架。
如果一页文档没有落到这五层结构里，通常就说明内容顺序已经开始失控。

loading

组件文档默认按下面的顺序组织，整体写法尽量参考 Element Plus：

  1. 标题和一句话说明
  2. 对应功能的 demo 分块
  3. 紧贴 demo 的说明、提示、警告
  4. API 表格
  5. 插槽、事件、方法、数据结构等补充表格

推荐骨架：

md
# QxsYourComponent

一句话说明组件用途。

## 功能一

先用 1-3 句话说明这个功能适合什么场景、读者看完会得到什么。

::: tip
需要强调的提示直接写在 demo 上方，不要单独起一个“注意事项”标题。
:::

<demo
  vue="/demo/components/your-component/feature-a.vue"
  title="功能一名称"
  description="说明这个 demo 具体演示了什么"
/>

## 功能二

说明这个功能的使用边界。

::: warning
这里写限制、踩坑点或宿主侧注意事项。
:::

<demo
  vue="/demo/components/your-component/feature-b.vue"
  title="功能二名称"
  description="说明这个 demo 覆盖的能力范围"
/>

## API

### 属性

| 名称 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| `foo` | 字段说明 | `string` | `''` |

### 事件

| 名称 | 说明 | Detail |
|------|------|--------|
| `change` | 事件说明 | `CustomEvent` |

### 插槽

| 名称 | 说明 |
|------|------|
| `default` | 默认插槽 |

Demo 写法要求 ​

1. demo 才是正文重点 ​

文档主体应该是 demo 和说明，不是 API 表格。
读者大多数时候是先看“这个功能怎么用”，只有确认能用后才会去查字段。

推荐写法与避免写法 ​

如果你不确定当前页面写得像不像 Element Plus，先看下面这组对比。
只要你开始连续堆 demo、写泛标题或者把 API 顶到最前面，读者的阅读顺序基本就断了。

loading

2. demo 的标题必须是“功能名” ​

title 必须直接写当前 demo 展示的功能，不要写成泛标题。 每个 demo 前还必须有一个对应的小节标题，目录里的标题和 demo title 应该表达同一个功能。

推荐：

  • 单选题预览
  • 量表列与问题行编辑
  • 运行时校验与提交数据
  • 禁用状态
  • 带图标按钮

不推荐：

  • 基础用法
  • 编辑态
  • 示例一
  • demo

推荐写法：

md
## 单选题预览

这里先说明这个 demo 演示什么。

<demo
  vue="/demo/components/subject/single-basic.vue"
  title="单选题预览"
  description="最基础的单选题预览态"
/>

3. demo 上方先写说明，再写提示 ​

每个 demo 前至少要有一小段说明，告诉读者：

  • 这个 demo 在演示什么
  • 适合什么场景
  • 有什么边界

如果需要补充提示或警告，直接跟在这段说明下面，用 tip / warning / danger callout 即可。
不要为了提示内容再单独起一个 ## 注意事项 或 ## 警告 标题。

4. 一个 demo 只演示一类能力 ​

不要把多个无关能力塞进同一个 demo。
如果一个 demo 同时讲“预览、编辑、禁用、插槽、远程加载”，读者很难定位重点。

更推荐拆成：

  • 预览输出
  • 编辑能力
  • 特定变体
  • 宿主接管能力

API 表格要求 ​

demo 和说明写完以后，再统一放 API。
表格建议放在文档下半部分，避免读者一进页就看到大块字段表。

常见表格顺序：

  1. 属性
  2. 事件
  3. 插槽
  4. 方法
  5. 数据结构 / 返回值 / 补充说明

字段说明要求：

  • 名称写真实字段名，不要翻译字段名
  • 类型尽量完整，必要时直接写联合类型
  • 默认值不要省略
  • 说明先写行为，再写边界

说明文案要求 ​

  • 页面正文尽量使用中文。
  • 组件名、字段名、事件名、类型名保留英文，避免和真实接口脱节。
  • 一段说明尽量只表达一个重点，不要一段里同时塞背景、做法、限制和结论。
  • 先讲“做什么”，再讲“为什么”，最后讲“限制是什么”。

常见反例 ​

  • 两个 demo 直接连在一起，中间没有说明。
  • demo 标题写成 基础用法、编辑态 这种泛标题，读者看目录时无法判断差异。
  • demo 前没有对应的小节标题，导致目录里只看到“大段基础用法”，找不到具体功能。
  • 把所有提示集中到一个独立章节，导致读者看 demo 时找不到上下文。
  • 先放很长的 API 表格，demo 放在后面。
  • 一个页面同时讲总览、接入、迁移、宿主职责和所有题型细节，导致目录失控。

创建或更新文档时的检查清单 ​

  • 是否先有 demo，再有 API。
  • demo 标题是否直接等于当前功能。
  • 每个 demo 前是否有对应的小节标题，且与 demo title 表达同一个功能。
  • 每个 demo 上方是否有简短说明。
  • 提示 / 警告是否紧贴对应 demo，而不是单独起标题。
  • API 是否放在文档下半部分。
  • 页面正文是否尽量使用中文。
  • 字段名、组件名、事件名是否保持真实英文标识。