组件文档的规范

本贴最后更新于 307 天前,其中的信息可能已经水流花落

1. API 表格规范

  1. API 部分应该遵循参数、事件、方法、插槽、类型定义的顺序,若某一项缺失则跳过;如果组件有特殊项需要说明,需要在类型定义后面编写。

  2. API 表格的标题,组成格式为:Xxx [参数 | 事件 | 方法 | 插槽]​,Xxx​为组件名字,采用大驼峰书写,需要注意组件名字后面加一个空格,标题等级为三级;类型定义标题的格式为 Xxx 类型定义​,组件名字同样为大驼峰格式,中间同样需要加一个空格,标题等级同样为三级,具体类型名字跟随在后面用四级标题定义。

  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​。

2. 组件 API 规范

  1. 命名方式用中划线风格:组件的参数名和事件名统一使用中划线格式。
  2. 组件名称前缀:组件的命名统一使用 gas​前缀。
  3. 针对需要双向绑定的参数,需要直接用 v-model​,避免增加额外参数,例如 v-model:xxx​。
  4. 原生支持的属性尽量不再用 API 去单独声明,直接通过 attrs​透传即可,比如 placeholder​。

3. 演示 demo 规范

  1. 演示 demo 需要对所使用的 API 及组件默认行为和样式等进行尽可能详细的说明。避免让用户自己去推测,降低用户学习和使用成本。
  2. 每个组件的第一个 demo,应该是组件最基本的用法,即展示组件在不传参数或者传入最基本参数情况下的效果。后面的 demo 应该尽可能按照参数的使用频率来排序。
  3. ***==每个 demo 所展示的 API 应该尽量精简,尽量不要一个 demo 中展示多个 API 的用法。==***
  4. 文案描述需清晰,尽量参考 element​的文案描述,尽量避免口语化;标点符号使用需正确;文案中若涉及到英文单词,需在单次左右两侧加一个空格。
  5. 演示 demo 自定义 class 样式,命名格式为 xxx-demo-yyy​(xxx 为组件名,yyy 为自定义样式名),不然会成为全局样式,有可能影响其他组件或者 demo 效果。

4. 编码规范

使用丽云的

5. 组件目录/文件规范

参考 element​源码文件

my-component
├── index.ts                  // 组件入口文件
└── src                       // 组件源码
   └── components             // 子组件
      ├── my-sub-component.ts
   └── composables            // 组件的逻辑部分 composable
      ├── my-use-component.ts
   ├── my-component.types.ts  // 组件类型文件
   ├── my-component.scss      // 组件样式
   └── my-component.tsx       // 组件

组件类型文件:

import { PropType, ExtractPropTypes } from 'vue'

export const myComponentProps = {
  myProp: {
    type: Number,
    default: 1
  },
  myProp2: {
    type: Array as PropType<number[]>,
    default: [5, 10, 20, 50]
  },
} as const

export type MyComponentProps = ExtractPropTypes<typeof myComponentProps>;

6. 样式命名规范

use-namespace​文件中,封装了样式命名的相关方法。样式命名采用 BEM 规范use-namespace​提供了如下几个方法:

// 以 Button 组件为例

// 创建 Button 组件的命名空间
const ns = useNamespace('button');

// 根组件一般采用此命名
ns.b();  // gas-button

// 组件内的块元素样式命名,即 BEM 规范的 Element 部分
ns.e('content');  // gas-button__content

// 组件的修饰类样式命名,即 BEM 规范的 Modifier 部分
ns.m('primary');  // gas-button--primary

// 块元素和修饰类样式组合使用
ns.em('content', 'primary');  // gas-button__content--primary

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...