组件文档的规范

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

‍