# table (w-table)

- **Import**: `WTable` from `win-design-next`
- **Tag**: `<w-table>`
- **说明**: Table 表格
- **分类**: data-display
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/table.md`

## API

## Table API

### Table 属性

| 属性名                  | 说明                                                                                                                                                                                                          | 类型                                                                                                                                              | Default                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| data                    | 表数据                                                                                                                                                                                                        | ^[array]`any[]`                                                                                                                                   | []                                                                                                                      |
| height                  | table 的高度。 默认为自动高度。 如果 height 为 number 类型，单位 px；如果 height 为 string 类型，则这个高度会设置为 Table 的 style.height 的值，Table 的高度会受控于外部样式。                                | ^[string] / ^[number]                                                                                                                             | —                                                                                                                       |
| max-height              | table 的最大高度。 合法的值为数字或者单位为 px 的高度。                                                                                                                                                       | ^[string] / ^[number]                                                                                                                             | —                                                                                                                       |
| stripe                  | 是否为斑马纹 table                                                                                                                                                                                            | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| border                  | 是否带有纵向边框                                                                                                                                                                                              | ^[boolean]                                                                                                                                        | true                                                                                                                    |
| size ^(1.0.7)           | Table 的尺寸                                                                                                                                                                                                  | ^[enum]`'extra-large' \| 'large' \| 'default' \| 'small' \| 'mini'`                                                                               | default                                                                                                                 |
| fit                     | 列的宽度是否自撑开                                                                                                                                                                                            | ^[boolean]                                                                                                                                        | true                                                                                                                    |
| show-header             | 是否显示表头                                                                                                                                                                                                  | ^[boolean]                                                                                                                                        | true                                                                                                                    |
| highlight-current-row   | 是否要高亮当前行                                                                                                                                                                                              | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| current-row-key         | 当前行的 key，只写属性                                                                                                                                                                                        | ^[string] / ^[number]                                                                                                                             | —                                                                                                                       |
| row-class-name          | 行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className。                                                                                                                                 | ^[Function]`(data: { row: any, rowIndex: number }) => string` / ^[string]                                                                         | —                                                                                                                       |
| row-style               | 行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style。                                                                                                                                 | ^[Function]`(data: { row: any, rowIndex: number }) => CSSProperties` / ^[object]`CSSProperties`                                                   | —                                                                                                                       |
| cell-class-name         | 单元格的 className 的回调方法，也可以使用字符串为所有单元格设置一个固定的 className。                                                                                                                         | ^[Function]`(data: { row: any, column: any, rowIndex: number, columnIndex: number }) => string` / ^[string]                                       | —                                                                                                                       |
| cell-style              | 单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有单元格设置一样的 Style。                                                                                                                         | ^[Function]`(data: { row: any, column: any, rowIndex: number, columnIndex: number }) => CSSProperties` / ^[object]`CSSProperties`                 | —                                                                                                                       |
| header-row-class-name   | 表头行的 className 的回调方法，也可以使用字符串为所有表头行设置一个固定的 className。                                                                                                                         | ^[Function]`(data: { row: any, rowIndex: number }) => string` / ^[string]                                                                         | —                                                                                                                       |
| header-row-style        | 表头行的 style 的回调方法，也可以使用一个固定的 Object 为所有表头行设置一样的 Style。                                                                                                                         | ^[Function]`(data: { row: any, rowIndex: number }) => CSSProperties` / ^[object]`CSSProperties`                                                   | —                                                                                                                       |
| header-cell-class-name  | 表头单元格的 className 的回调方法，也可以使用字符串为所有表头单元格设置一个固定的 className。                                                                                                                 | ^[Function]`(data: { row: any, column: any, rowIndex: number, columnIndex: number }) => string` / ^[string]                                       | —                                                                                                                       |
| header-cell-style       | 表头单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有表头单元格设置一样的 Style。                                                                                                                 | ^[Function]`(data: { row: any, column: any, rowIndex: number, columnIndex: number }) => CSSProperties` / ^[object]`CSSProperties`                 | —                                                                                                                       |
| row-key                 | 行数据的 Key，用来优化 Table 的渲染； 在使用`reserve-selection`功能与显示树形数据时，该属性是必填的。 类型为 String 时，支持多层访问：`user.info.id`，但不支持 `user.info[0].id`，此种情况请使用 `Function`。 | ^[function]`(row: any) => string` / ^[string]                                                                                                     | —                                                                                                                       |
| empty-text              | 空数据时显示的文本内容， 也可以通过 `#empty` 设置                                                                                                                                                             | ^[string]                                                                                                                                         | No Data                                                                                                                 |
| default-expand-all      | 是否默认展开所有行，当 Table 包含展开行存在或者为树形表格时有效                                                                                                                                               | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| expand-row-keys         | 可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用，该属性为展开行的 keys 数组。                                                                                                            | ^[array]`string[]`                                                                                                                                | —                                                                                                                       |
| default-sort            | 默认的排序列的 prop 和顺序。 它的 `prop` 属性指定默认的排序的列，`order` 指定默认排序的顺序                                                                                                                   | ^[object]`Sort`                                                                                                                                   | 如果设置了`prop`，但没有设置 `order`，那么 `order`将被默认设置为 ascending                                              |
| tooltip-effect          | 溢出的 tooltip 的 `effect`                                                                                                                                                                                    | ^[enum]`'dark' \| 'light'`                                                                                                                        | dark                                                                                                                    |
| tooltip-options         | 溢出 tooltip 的选项，[参见下述 tooltip 组件](tooltip.html#attributes)                                                                                                                                         | ^[object]`Pick`                                                                                                                                   | ^[object]`{ enterable: true, placement: 'top', showArrow: true, hideAfter: 200, popperOptions: { strategy: 'fixed' } }` |
| append-filter-panel-to  | 挂载到哪个 DOM 元素                                                                                                                                                                                           | ^[string]                                                                                                                                         | —                                                                                                                       |
| show-summary            | 是否在表尾显示合计行                                                                                                                                                                                          | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| sum-text                | 显示摘要行第一列的文本                                                                                                                                                                                        | ^[string]                                                                                                                                         | Sum                                                                                                                     |
| summary-method          | 自定义的合计计算方法                                                                                                                                                                                          | ^[Function]`(data: { columns: any[], data: any[] }) => (VNode \| string)[]`                                                                       | —                                                                                                                       |
| span-method             | 合并行或列的计算方法                                                                                                                                                                                          | ^[Function]`(data: { row: any, column: any, rowIndex: number, columnIndex: number }) => number[] \| { rowspan: number, colspan: number } \| void` | —                                                                                                                       |
| select-on-indeterminate | 在多选表格中，当仅有部分行被选中时，点击表头的多选框时的行为。 若为 true，则选中所有行；若为 false，则取消选择所有行                                                                                          | ^[boolean]                                                                                                                                        | true                                                                                                                    |
| indent                  | 展示树形数据时，树节点的缩进                                                                                                                                                                                  | ^[number]                                                                                                                                         | 16                                                                                                                      |
| lazy                    | 是否懒加载子节点数据                                                                                                                                                                                          | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| load                    | 加载子节点数据的函数，`lazy` 为 true 时生效                                                                                                                                                                   | ^[Function]`(row: any, treeNode: TreeNode, resolve: (data: any[]) => void) => void`                                                               | —                                                                                                                       |
| tree-props              | 渲染嵌套数据的配置选项                                                                                                                                                                                        | ^[object]`{ hasChildren?: string, children?: string, checkStrictly?: boolean }`                                                                   | ^[object]`{ hasChildren: 'hasChildren', children: 'children', checkStrictly: false }`                                   |
| table-layout            | 设置表格单元、行和列的布局方式                                                                                                                                                                                | ^[enum]`'fixed' \| 'auto'`                                                                                                                        | fixed                                                                                                                   |
| scrollbar-always-on     | 总是显示滚动条                                                                                                                                                                                                | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| show-overflow-tooltip   | 是否隐藏额外内容并在单元格悬停时使用 Tooltip 显示它们。这将影响全部列的展示，详请参考[tooltip-options](#table-attributes)                                                                                     | ^[boolean] / [`object`](#table-attributes)                                                                                                        | —                                                                                                                       |
| flexible                | 确保主轴的最小尺寸，以便不超过内容                                                                                                                                                                            | ^[boolean]                                                                                                                                        | false                                                                                                                   |
| scrollbar-tabindex      | body 的滚动条的包裹容器 tabindex                                                                                                                                                                              | ^[string] / ^[number]                                                                                                                             | —                                                                                                                       |
| allow-drag-last-column  | 是否允许拖动最后一列                                                                                                                                                                                          | ^[boolean]                                                                                                                                        | true                                                                                                                    |
| tooltip-formatter       | 自定义 `show-overflow-tooltip` 时的 tooltip 内容                                                                                                                                                              | ^[Function]`(data: { row: any, column: any, cellValue: any }) => VNode \| string`                                                                 | —                                                                                                                       |
| h-scrollbar-size        | 配置表格的水平滚动条大小，防止水平和垂直滚动条重叠。                                                                                                                                                          | `number`                                                                                                                                          | 10                                                                                                                      |
| scrollbar-size          | 配置表格的垂直滚动条大小，防止水平和垂直滚动条重叠。                                                                                                                                                          | `number`                                                                                                                                          | 10                                                                                                                      |
| hover ^(1.1.9)          | 是否开启鼠标悬停高亮                                                                                                                                                                                          | ^[boolean]                                                                                                                                        | true                                                                                                                    |

### Table 事件

| 事件名             | 说明                                                                                                                     | 类型                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| select             | 当用户手动勾选数据行的 Checkbox 时触发的事件                                                                             | ^[Function]`(selection: T[], row: T) => void`                                                |
| select-all         | 当用户手动勾选全选 Checkbox 时触发的事件                                                                                 | ^[Function]`(selection: any[]) => void`                                                      |
| selection-change   | 当选择项发生变化时会触发该事件                                                                                           | ^[Function]`(newSelection: any[]) => void`                                                   |
| cell-mouse-enter   | 当单元格 hover 进入时会触发该事件                                                                                        | ^[Function]`(row: any, column: any, cell: HTMLTableCellElement, event: Event) => void`       |
| cell-mouse-leave   | 当单元格 hover 退出时会触发该事件                                                                                        | ^[Function]`(row: any, column: any, cell: HTMLTableCellElement, event: Event) => void`       |
| cell-click         | 当某个单元格被点击时会触发该事件                                                                                         | ^[Function]`(row: any, column: any, cell: HTMLTableCellElement, event: Event) => void`       |
| cell-dblclick      | 当某个单元格被双击击时会触发该事件                                                                                       | ^[Function]`(row: any, column: any, cell: HTMLTableCellElement, event: Event) => void`       |
| cell-contextmenu   | 当某个单元格被鼠标右键点击时会触发该事件                                                                                 | ^[Function]`(row: any, column: any, cell: HTMLTableCellElement, event: Event) => void`       |
| row-click          | 当某一行被点击时会触发该事件                                                                                             | ^[Function]`(row: any, column: any, event: Event) => void`                                   |
| row-contextmenu    | 当某一行被鼠标右键点击时会触发该事件                                                                                     | ^[Function]`(row: any, column: any, event: Event) => void`                                   |
| row-dblclick       | 当某一行被双击时会触发该事件                                                                                             | ^[Function]`(row: any, column: any, event: Event) => void`                                   |
| header-click       | 当某一列的表头被点击时会触发该事件                                                                                       | ^[Function]`(column: any, event: Event) => void`                                             |
| header-contextmenu | 当某一列的表头被鼠标右键点击时触发该事件                                                                                 | ^[Function]`(column: any, event: Event) => void`                                             |
| sort-change        | 当表格的排序条件发生变化的时候会触发该事件                                                                               | ^[Function]`(data: {column: any, prop: string, order: any }) => void`                        |
| filter-change      | column 的 key， 如果需要使用 filter-change 事件，则需要此属性标识是哪个 column 的筛选条件                                | ^[Function]`(newFilters: any) => void`                                                       |
| current-change     | 当表格的当前行发生变化的时候会触发该事件，如果要高亮当前行，请打开表格的 highlight-current-row 属性                      | ^[Function]`(currentRow: any, oldCurrentRow: any) => void`                                   |
| header-dragend     | 当拖动表头改变了列的宽度的时候会触发该事件                                                                               | ^[Function]`(newWidth: number, oldWidth: number, column: any, event: MouseEvent) => void`    |
| expand-change      | 当用户对某一行展开或者关闭的时候会触发该事件（展开行时，回调的第二个参数为 expandedRows；树形表格时第二参数为 expanded） | ^[Function]`(row: any, expandedRows: any[]) => void & (row: any, expanded: boolean) => void` |
| scroll             | 表格被用户滚动后触发                                                                                                     | ^[Function]`({ scrollLeft: number, scrollTop: number }) => void`                             |

### Table 插槽

| 插槽名  | 说明                                                                                                                                    | 子标签       |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| default | 自定义默认内容                                                                                                                          | Table-column |
| append  | 插入至表格最后一行之后的内容， 如果需要对表格的内容进行无限滚动操作，可能需要用到这个 slot。 若表格有合计行，该 slot 会位于合计行之上。 | —            |
| empty   | 当数据为空时自定义的内容                                                                                                                | —            |

### Table Exposes

| 方法名             | 说明                                                                                                    | Type                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| clearSelection     | 用于多选表格，清空用户的选择                                                                            | ^[Function]`() => void`                                                      |
| getSelectionRows   | 返回当前选中的行                                                                                        | ^[Function]`() => any[]`                                                     |
| toggleRowSelection | 用于多选表格，切换某一行的选中状态， 如果使用了第二个参数，则可直接设置这一行选中与否                   | ^[Function]`(row: any, selected?: boolean, ignoreSelectable = true) => void` |
| toggleAllSelection | 用于多选表格，切换全选和全不选                                                                          | ^[Function]`() => void`                                                      |
| toggleRowExpansion | 用于可扩展的表格或树表格，如果某行被扩展，则切换。 使用第二个参数，您可以直接设置该行应该被扩展或折叠。 | ^[Function]`(row: any, expanded?: boolean) => void`                          |
| setCurrentRow      | 用于单选表格，设定某一行为选中行， 如果调用时不加参数，则会取消目前高亮行的选中状态。                   | ^[Function]`(row: any) => void`                                              |
| clearSort          | 用于清空排序条件，数据会恢复成未排序的状态                                                              | ^[Function]`() => void`                                                      |
| clearFilter        | 传入由`columnKey` 组成的数组以清除指定列的过滤条件。 如果没有参数，清除所有过滤器                       | ^[Function]`(columnKeys?: string[]) => void`                                 |
| doLayout           | 对 Table 进行重新布局。 当表格可见性变化时，您可能需要调用此方法以获得正确的布局                        | ^[Function]`() => void`                                                      |
| sort               | 手动排序表格。 参数 `prop` 属性指定排序列，`order` 指定排序顺序。                                       | ^[Function]`(prop: string, order: string) => void`                           |
| scrollTo           | 滚动到一组特定坐标                                                                                      | ^[Function]`(options: number \| ScrollToOptions, yCoord?: number) => void`   |
| setScrollTop       | 设置垂直滚动位置                                                                                        | ^[Function]`(top?: number) => void`                                          |
| setScrollLeft      | 设置水平滚动位置                                                                                        | ^[Function]`(left?: number) => void`                                         |
| columns            | 获取表列的 context                                                                                      | ^[array]`TableColumnCtx[]`                                                   |
| updateKeyChildren  | 适用于 lazy Table, 需要设置 `rowKey`, 更新 key children                                                 | ^[Function]`(key: string, data: T[]) => void`                                |
