Skip to content

feat(Table): 规范细节微调&参照规范完善Table文档 #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kagol merged 1 commit into from
Apr 8, 2022
Merged

feat(Table): 规范细节微调&参照规范完善Table文档 #420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 43 additions & 37 deletions packages/devui-vue/docs/components/table/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -807,52 +807,54 @@ export default defineComponent({

:::

### d-table 参数

| 参数名 | 类型 | 默认值 | 说明 | 跳转 Demo |
| :-------------------- | :------------------ | :------ | :------------------------------------------------------------------------- | :------------------------ |
| data | `array` | [] | 可选，显示的数据 | [基本用法](#基本用法) |
| striped | `boolean` | false | 可选，是否显示斑马纹间隔 | [表格样式](#表格样式) |
| size | `TableSize` | 'sm' | 可选，表格大小，分别对应行高 40px,48px,56px | [表格样式](#表格样式) |
| max-width | `string` | -- | 可选，表格最大宽度 |
| max-height | `boolean` | -- | 可选，表格最大高度 |
| table-width | `string` | -- | 可选，表格宽度 |
| table-height | `string` | -- | 可选，表格高度 |
| row-hovered-highlight | `boolean` | true | 可选，鼠标在该行上时，高亮该行 | [表格样式](#表格样式) |
| fix-header | `boolean` | false | 可选，固定头部 | [固定表头](#固定表头) |
| show-loading | `boolean` | false | 可选，显示加载动画 | [空数据模板](#空数据模板) |
| header-bg | `boolean` | false | 可选，头部背景 | [表格样式](#表格样式) |
| table-layout | `'fixed' \| 'auto'` | 'fixed' | 可选，表格布局，可选值为'auto' | [表格样式](#表格样式) |
| span-method | `SpanMethod` | -- | 可选，合并单元格的计算方法 | [合并单元格](#合并单元格) |
| border-type | `BorderType` | '' | 可选，表格边框类型，默认有行边框；`bordered`: 全边框；`borderless`: 无边框 | [表格样式](#表格样式) |

### d-table 方法
### Table 参数

| 参数名 | 类型 | 默认值 | 说明 | 跳转 Demo |
| :-------------------- | :------------------------ | :------ | :------------------------------------------------------------------------- | :------------------------ |
| data | `array` | [] | 可选，显示的数据 | [基本用法](#基本用法) |
| striped | `boolean` | false | 可选，是否显示斑马纹间隔 | [表格样式](#表格样式) |
| size | [TableSize](#tablesize) | 'sm' | 可选，表格大小，分别对应行高 40px,48px,56px | [表格样式](#表格样式) |
| max-width | `string` | -- | 可选，表格最大宽度 |
| max-height | `boolean` | -- | 可选，表格最大高度 |
| table-width | `string` | -- | 可选，表格宽度 |
| table-height | `string` | -- | 可选，表格高度 |
| row-hovered-highlight | `boolean` | true | 可选，鼠标在该行上时，高亮该行 | [表格样式](#表格样式) |
| fix-header | `boolean` | false | 可选，固定头部 | [固定表头](#固定表头) |
| show-loading | `boolean` | false | 可选，显示加载动画 | [空数据模板](#空数据模板) |
| header-bg | `boolean` | false | 可选，头部背景 | [表格样式](#表格样式) |
| table-layout | `'fixed' \| 'auto'` | 'fixed' | 可选，表格布局，可选值为'auto' | [表格样式](#表格样式) |
| span-method | [SpanMethod](#spanmethod) | -- | 可选，合并单元格的计算方法 | [合并单元格](#合并单元格) |
| border-type | [BorderType](#bordertype) | '' | 可选，表格边框类型，默认有行边框；`bordered`: 全边框；`borderless`: 无边框 | [表格样式](#表格样式) |

### Table 方法

| 方法名 | 类型 | 说明 |
| :------------- | :--------- | :------------------- |
| getCheckedRows | `() => []` | 获取当前选中的行数据 |

### d-column 参数
### Column 参数

| 参数名 | 类型 | 默认值 | 说明 | 跳转 Demo |
| :---------- | :----------------- | :----- | :------------------------------------------ | :-------------------- |
| header | `string` | -- | 可选，对应列的标题 | [基本用法](#基本用法) |
| field | `string` | -- | 可选，对应列内容的字段名 | [基本用法](#基本用法) |
| type | `ColumnType` | '' | 可选，列的类型，设置`checkable`会显示多选框 | [表格多选](#表格多选) |
| width | `string \| number` | -- | 可选，对应列的宽度，单位`px` |
| min-width | `string \| number` | -- | 可选，对应列的最小宽度，单位`px` |
| fixed-left | `string` | -- | 可选，该列固定到左侧的距离，如：'100px' | [固定列](#固定列) |
| fixed-right | `string` | -- | 可选，该列固定到右侧的距离，如：'100px' | [固定列](#固定列) |
| formatter | `Formatter` | -- | 可选，格式化列内容 |
| 参数名 | 类型 | 默认值 | 说明 | 跳转 Demo |
| :---------- | :------------------------ | :----- | :------------------------------------------ | :-------------------- |
| header | `string` | -- | 可选，对应列的标题 | [基本用法](#基本用法) |
| field | `string` | -- | 可选，对应列内容的字段名 | [基本用法](#基本用法) |
| type | [ColumnType](#columntype) | '' | 可选，列的类型，设置`checkable`会显示多选框 | [表格多选](#表格多选) |
| width | `string \| number` | -- | 可选，对应列的宽度，单位`px` |
| min-width | `string \| number` | -- | 可选，对应列的最小宽度，单位`px` |
| fixed-left | `string` | -- | 可选，该列固定到左侧的距离，如：'100px' | [固定列](#固定列) |
| fixed-right | `string` | -- | 可选，该列固定到右侧的距离，如：'100px' | [固定列](#固定列) |
| formatter | [Formatter](#formatter) | -- | 可选，格式化列内容 |

### d-column 插槽
### Column 插槽

| 插槽名 | 说明 |
| :------ | :----------------------- |
| default | 默认插槽，自定义列内容 |
| header | 表头插槽，自定义表头内容 |
| 插槽名 | 说明 | 参数 |
| :------ | :----------------------- | :------------------ |
| default | 默认插槽，自定义列内容 | `{ row, rowIndex }` |
| header | 表头插槽，自定义表头内容 | |

### 类型定义
### Table 类型定义

<br>

#### TableSize

Expand All @@ -877,6 +879,10 @@ type SpanMethod = (data: {
type BorderType = '' | 'bordered' | 'borderless';
```

### Column 类型定义

<br>

#### ColumnType

```ts
Expand Down
56 changes: 28 additions & 28 deletions ...vui-vue/docs/contributing/development-specification/component-document/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,38 +2,38 @@

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