Vue DevUI
主题

组件 API 和 Demo 文档规范

Demo 文档

  1. 演示 demo 需要对所使用的 API 及组件默认行为和样式等进行尽可能详细的说明。避免让用户自己去推测，降低用户学习和使用成本。
  2. 每个组件的第一个 demo，应该是组件最基本的用法，即展示组件在不传参数或者传入最基本参数情况下的效果。后面的 demo 应该尽可能按照参数的使用频率来排序。
  3. 每个 demo 所展示的 API 应该尽量精简，尽量不要一个 demo 中展示多个 API 的用法。
  4. 当 API 是枚举值时，demo 中应尽量展示每个枚举值的效果。
  5. 演示 demo 代码，组件的参数大于三个或单行过长时需要每个参数占用一行来展示，避免出现横向滚动条，。
  6. 演示 demo 自定义 class 样式，命名格式为 xxx-demo-yyy(xxx 为组件名，yyy 为自定义样式名)，不然会成为全局样式，有可能影响其他组件或者 demo 效果。
  7. 文案描述需清晰，尽量参考 ng devui 的文案描述，尽量避免口语化；标点符号使用需正确；文案中若涉及到英文单词，需在单次左右两侧加一个空格。
  8. 一个标题尽量展示一个 demo，避免一个标题中展示多个 demo。
  9. boolean 类型的参数，在 demo 中展示，设置为 true 的时候，不需要显式的设置为 true，直接写参数名字即可。
  10. demo 的描述说明文案中，用到代码块的地方需要用反引号包裹。
  11. demo 的描述说明文案应该跟在:::demo 后面，不应该放在 h4 或其他标签中，也不应该放在代码块外面。
  12. 【何时使用】标题等级应该为四级，避免出现在快速前往导航中。

API 文档

  1. API 部分应该遵循参数、事件、方法、插槽、类型定义的顺序，若某一项缺失则跳过；如果组件有特殊项需要说明，需要在类型定义后面编写。
  2. API 表格的标题，组成格式为：Xxx [参数 | 事件 | 方法 | 插槽]，Xxx 为组件名字，采用大驼峰书写，需要注意组件名字后面加一个空格，标题等级为三级；类型定义标题的格式为 Xxx 类型定义，组件名字同样为大驼峰格式，中间同样需要加一个空格，标题等级同样为三级，标题后需要加一个br标签，防止和后面具体类型靠得太紧；具体类型名字跟随在后面用四级标题定义。
  3. API 表格表头和内容应该左对齐。
  4. 参数表格需要具备的列名及顺序为：参数名、类型、默认值、说明、跳转 Demo。
    • 参数不需要使用反引号。
    • 类型需要使用反引号包裹(需要增加锚点定位的类型除外)；类型需准确，简单枚举值类型可直接列出来，复杂一些的类型可以写类型名字（如 SizeType），然后增加锚点定位；参数基本类型采用首字母小写 string，自定义类型名字采用大驼峰命名，（如 SizeType）。
    • 默认值不需要反引号包裹，如果默认值为字符串或者枚举类型，应该使用单引号包裹，若无默认值则用双横线--表示。
    • 说明中需要标注该参数为必选还是可选。
    • 跳转 Demo 中的链接需能够正确跳转，并且 demo 中需要展示对应 API 的用法；若无展示 Demo，则空白展示。
  5. 事件表格需要具备的列名及顺序为：事件名、回调参数、说明、跳转 Demo。
    • 事件名不需要使用反引号。
    • 回调参数需要使用反引号包裹；类型格式为 Function(name: string)。
    • 跳转 Demo 中的链接需能够正确跳转，并且 demo 中需要展示对应 API 的用法；若无展示 Demo，则空白展示。
  6. 方法表格需要具备的列名及顺序为：方法名、类型、说明。
    • 方法名不需要使用反引号。
    • 类型需要使用反引号包裹。
  7. 插槽表格需要具备的列名及顺序为：插槽名、说明、参数。
    • 默认插槽也需要做说明，并且插槽名字应该为 default。
    • 参数为组件内部暴露出来的数据。
  8. 类型定义需要使用 typescript 代码块，代码块格式为 type xxx = yyy。
粤A2-20044005号