Table 表格
用于展示多条结构类似的数据， 可对数据进行排序、筛选、对比或其他自定义操作。
基础表格
带斑马纹表格
带边框表格
带状态表格
固定表头
固定列
固定列和表头
流体高度
多级表头
单选
多选
排序
筛选
自定义列模板
自定义表头
展开行
树形数据与懒加载
表尾合计行
合并行或列
自定义索引
表格布局
API
Table Props
| 属性名 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| data | 显示的数据 | array | — | — |
| height | Table 的高度， 默认为自动高度。 如果 height 为 number 类型，单位 px；如果 height 为 string 类型，则这个高度会设置为 Table 的 style.height 的值，Table 的高度会受控于外部样式。 | string / number | — | — |
| max-height | Table 的最大高度。 合法的值为数字或者单位为 px 的高度。 | string / number | — | — |
| stripe | 是否为斑马纹 | boolean | — | false |
| border | 是否带有纵向边框 | boolean | — | false |
| size | Table 的尺寸 | string | large / default /small | — |
| fit | 列的宽度是否自撑开 | boolean | — | true |
| show-header | 是否显示表头 | boolean | — | true |
| highlight-current-row | 是否要高亮当前行 | boolean | — | false |
| current-row-key | 当前行的 key，只写属性 | string / number | — | — |
| row-class-name | 行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className。 | function({ row, rowIndex }) / string | — | — |
| row-style | 行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style。 | function({ row, rowIndex }) / object | — | — |
| cell-class-name | 单元格的 className 的回调方法，也可以使用字符串为所有单元格设置一个固定的 className。 | function({ row, column, rowIndex, columnIndex }) / string | — | — |
| cell-style | 单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有单元格设置一样的 Style。 | function({ row, column, rowIndex, columnIndex }) / object | — | — |
| header-row-class-name | 表头行的 className 的回调方法，也可以使用字符串为所有表头行设置一个固定的 className。 | function({ row, rowIndex }) / string | — | — |
| header-row-style | 表头行的 style 的回调方法，也可以使用一个固定的 Object 为所有表头行设置一样的 Style。 | function({ row, rowIndex }) / object | — | — |
| header-cell-class-name | 表头单元格的 className 的回调方法，也可以使用字符串为所有表头单元格设置一个固定的 className。 | function({ row, column, rowIndex, columnIndex }) / string | — | — |
| header-cell-style | 表头单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有表头单元格设置一样的 Style。 | function({ row, column, rowIndex, columnIndex }) / object | — | — |
| row-key | 行数据的 Key，用来优化 Table 的渲染； 在使用 reserve-selection 功能与显示树形数据时，该属性是必填的。 类型为 String 时，支持多层访问：user.info.id，但不支持 user.info[0].id，此种情况请使用 Function。 | function(row) / string | — | — |
| empty-text | 空数据时显示的文本内容， 也可以通过 #empty 设置 | string | — | No Data |
| default-expand-all | 是否默认展开所有行，当 Table 包含展开行存在或者为树形表格时有效 | boolean | — | false |
| expand-row-keys | 可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用，该属性为展开行的 keys 数组 | array | — | — |
| default-sort | 默认的排序列的 prop 和顺序。 它的 prop 属性指定默认的排序的列，order 指定默认排序的顺序 | object | (order: 'ascending' | 'descending') | 如果只指定了 prop, 没有指定 order, 则默认顺序是 ascending |
| tooltip-effect | tooltip 模式 | string | dark / light | dark |
| tooltip-options | 溢出 tooltip 的选项, 参见下述 tooltip 组件 | object | 请参考 tooltip | object |
| show-summary | 是否在表尾显示合计行 | boolean | — | false |
| sum-text | 显示摘要行第一列的文本 | string | — | Sum |
| summary-method | 自定义的合计计算方法 | function({ columns, data }) | — | — |
| span-method | 合并行或列的计算方法 | function({ row, column, rowIndex, columnIndex }) | — | — |
| select-on-indeterminate | 在多选表格中，当仅有部分行被选中时，点击表头的多选框时的行为。 若为 true，则选中所有行；若为 false，则取消选择所有行 | boolean | — | true |
| indent | 展示树形数据时，树节点的缩进 | number | — | 16 |
| lazy | 是否懒加载子节点数据 | boolean | — | — |
| load | 加载子节点数据的函数，lazy 为 true 时生效 | function(row, treeNode, resolve) | — | — |
| tree-props | 渲染嵌套数据的配置选项 | object | — | { hasChildren: 'hasChildren', children: 'children' } |
| table-layout | 设置表格单元、行和列的布局方式 | string | fixed / auto | fixed |
| scrollbar-always-on | 总是显示滚动条 | boolean | — | false |
| flexible | 确保主轴的最小尺寸 | boolean | — | false |
Table Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 当用户手动勾选数据行的 Checkbox 时触发的事件 | selection, row |
| select-all | 当用户手动勾选全选 Checkbox 时触发的事件 | selection |
| selection-change | 当选择项发生变化时会触发该事件 | selection |
| cell-mouse-enter | 当单元格 hover 进入时会触发该事件 | row, column, cell, event |
| cell-mouse-leave | 当单元格 hover 退出时会触发该事件 | row, column, cell, event |
| cell-click | 当某个单元格被点击时会触发该事件 | row, column, cell, event |
| cell-dblclick | 当某个单元格被双击击时会触发该事件 | row, column, cell, event |
| cell-contextmenu | 当某个单元格被鼠标右键点击时会触发该事件 | row, column, cell, event |
| row-click | 当某一行被点击时会触发该事件 | row, column, event |
| row-contextmenu | 当某一行被鼠标右键点击时会触发该事件 | row, column, event |
| row-dblclick | 当某一行被双击时会触发该事件 | row, column, event |
| header-click | 当某一列的表头被点击时会触发该事件 | column, event |
| header-contextmenu | 当某一列的表头被鼠标右键点击时触发该事件 | column, event |
| sort-change | 当表格的排序条件发生变化的时候会触发该事件 | { column, prop, order } |
| filter-change | column 的 key， 如果需要使用 filter-change 事件，则需要此属性标识是哪个 column 的筛选条件 | filters |
| current-change | 当表格的当前行发生变化的时候会触发该事件，如果要高亮当前行，请打开表格的 highlight-current-row 属性 | currentRow, oldCurrentRow |
| header-dragend | 当拖动表头改变了列的宽度的时候会触发该事件 | newWidth, oldWidth, column, event |
| expand-change | 当用户对某一行展开或者关闭的时候会触发该事件（展开行时，回调的第二个参数为 expandedRows；树形表格时第二参数为 expanded） | row, (expandedRows | expanded) |
Table 方法
通过 ref 可以获取到 Tabs 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 |
|---|---|---|
| clearSelection | 用于多选表格，清空用户的选择 | — |
| getSelectionRows | 返回当前选中的行 | |
| toggleRowSelection | 用于多选表格，切换某一行的选中状态， 如果使用了第二个参数，则可直接设置这一行选中与否 | row, selected |
| toggleAllSelection | 用于多选表格，切换全选和全不选 | — |
| toggleRowExpansion | 用于可扩展的表格或树表格，如果某行被扩展，则切换。 使用第二个参数，您可以直接设置该行应该被扩展或折叠。 | row, expanded |
| setCurrentRow | 用于单选表格，设定某一行为选中行， 如果调用时不加参数，则会取消目前高亮行的选中状态 | row |
| clearSort | 用于清空排序条件，数据会恢复成未排序的状态 | — |
| clearFilter | 传入由 columnKey 组成的数组以清除指定列的过滤条件。 如果没有参数，清除所有过滤器 | columnKeys |
| doLayout | 对 Table 进行重新布局。 当表格可见性变化时，您可能需要调用此方法以获得正确的布局 | — |
| sort | 手动排序表格。 参数 prop 属性指定排序列，order 指定排序顺序。 | prop: string, order: string |
| scrollTo | 滚动到一组特定坐标 | (options: ScrollToOptions | number, yCoord?: number) |
| setScrollTop | 设置垂直滚动位置 | top |
| setScrollLeft | 设置水平滚动位置 | left |
Table Slots
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | Table-column |
| append | 插入至表格最后一行之后的内容， 如果需要对表格的内容进行无限滚动操作，可能需要用到这个 slot。 若表格有合计行，该 slot 会位于合计行之上。 | — |
| empty | 当数据为空时自定义的内容 | — |
Table-column Props
| 属性名 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| type | 对应列的类型。 如果设置了 selection 则显示多选框； 如果设置了 index 则显示该行的索引（从 1 开始计算）； 如果设置了 expand 则显示为一个可展开的按钮 | string | selection / index / expand | — |
| index | 如果设置了 type=index，可以通过传递 index 属性来自定义索引 | number / function(index) | — | — |
| label | 显示的标题 | string | — | — |
| column-key | column 的 key， column 的 key， 如果需要使用 filter-change 事件，则需要此属性标识是哪个 column 的筛选条件 | string | — | — |
| prop | 字段名称 对应列内容的字段名， 也可以使用 property 属性 | string | — | — |
| width | 对应列的宽度 | string / number | — | — |
| min-width | 对应列的最小宽度， 对应列的最小宽度， 与 width 的区别是 width 是固定的，min-width 会把剩余宽度按比例分配给设置了 min-width 的列 | string / number | — | — |
| fixed | 列是否固定在左侧或者右侧。 true 表示固定在左侧 | string / boolean | true / 'left' / 'right' | — |
| render-header | 列标题 Label 区域渲染使用的 Function | function({ column, $index }) | — | — |
| sortable | 对应列是否可以排序， 如果设置为 'custom'，则代表用户希望远程排序，需要监听 Table 的 sort-change 事件 | boolean / string | custom | false |
| sort-method | 指定数据按照哪个属性进行排序，仅当 sortable 设置为 true 的时候有效。 应该如同 Array.sort 那样返回一个 Number | function(a, b) | — | — |
| sort-by | s 指定数据按照哪个属性进行排序，仅当 sortable 设置为 true 且没有设置 sort-method 的时候有效。 如果 sort-by 为数组，则先按照第 1 个属性排序，如果第 1 个相等，再按照第 2 个排序，以此类推 | function(row, index) / string / array | — | — |
| sort-orders | 数据在排序时所使用排序策略的轮转顺序，仅当 sortable 为 true 时有效。 需传入一个数组，随着用户点击表头，该列依次按照数组中元素的顺序进行排序 | array | 数组中的元素需为以下三者之一：ascending 表示升序，descending 表示降序，null 表示还原为原始顺序 | ['ascending', 'descending', null] |
| resizable | 对应列是否可以通过拖动改变宽度（需要在 r-table 上设置 border 属性为真） | boolean | — | true |
| formatter | 用来格式化内容 | function(row, column, cellValue, index) | — | — |
| show-overflow-tooltip | 当内容过长被隐藏时显示 tooltip | boolean | object | 参考表格的 tooltip-options | — |
| align | 对齐方式 | string | left / center / right | left |
| header-align | 表头对齐方式， 若不设置该项，则使用表格的对齐方式 | string | left / center / right | — |
| class-name | 列的 className | string | — | — |
| label-class-name | 当前列标题的自定义类名 | string | — | — |
| selectable | 仅对 type=selection 的列有效，类型为 Function，Function 的返回值用来决定这一行的 CheckBox 是否可以勾选 | function(row, index) | — | — |
| reserve-selection | 仅对 type=selection 的列有效， 请注意， 需指定 row-key 来让这个功能生效。 | boolean | — | false |
| filters | 数据过滤的选项， 数组格式，数组中的元素需要有 text 和 value 属性。 数组中的每个元素都需要有 text 和 value 属性。 | Array<{text: string, value: string}> | — | — |
| filter-placement | 过滤弹出框的定位 | string | 与 Tooltip 的 placement 属性相同 | — |
| filter-multiple | 数据过滤的选项是否多选 | boolean | — | true |
| filter-method | 数据过滤使用的方法， 如果是多选的筛选项，对每一条数据会执行多次，任意一次返回 true 就会显示 | function(value, row, column) | — | — |
| filtered-value | 选中的数据过滤项，如果需要自定义表头过滤的渲染方式，可能会需要此属性。 | array | — | — |
Table-column Slots
| 插槽名 | 说明 |
|---|---|
| default | 自定义列的内容 作用域参数为 { row, column, $index } |
| header | 自定义表头的内容， 作用域参数为 s { column, $index } |
主题定制
类型定义
组件导出以下类型定义：
ts
import type {
TableSummaryMethod,
TableProps,
TableRefs,
TableColumnCls,
TableColumnStyle,
TableCellCls,
TableCellStyle,
TableTreeNode,
TableRenderRowData,
TableSort,
TableFilter,
TableColumnCtx,
TableThemeVars
} from 'ryxon'样式变量
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --r-table-border-color | var(--r-border-color-lighter) | - |
| --r-table-border | 1px solid var(--r-table-border-color) | - |
| --r-table-text-color | var(--r-text-color-regular) | - |
| --r-table-header-text-color | var(--r-text-color-secondary) | - |
| --r-table-row-hover-bg-color | var(--r-fill-color-light) | - |
| --r-table-current-row-bg-color | var(--r-primary-color-light-9) | - |
| --r-table-header-bg-color | var(--r-white) | - |
| --r-table-fixed-box-shadow | var(--r-box-shadow-light) | - |
| --r-table-bg-color | var(--r-fill-color-blank) | - |
| --r-table-tr-bg-color | var(--r-fill-color-blank) | - |
| --r-table-expanded-cell-bg-color | var(--r-fill-color-blank) | - |
| --r-table-fixed-left-column | inset 10px 0 10px -10px rgba(0, 0, 0, 0.15) | - |
| --r-table-fixed-right-column | inset -10px 0 10px -10px rgba(0, 0, 0, 0.15) | - |
| --r-table-dark-text-color | var(--r-white) | - |
| --r-table-dark-background | #4a4a4a | - |
常见问题
当使用 DOM 模板时，为什么列没有渲染？
这是因为 HTML 定义只允许一些特定元素省略关闭标签，最常见的是<input> 和 <img>。 对于任意其他元素，如果你省略了关闭标签，原生的 HTML 解析器会认为你从未关闭打开的标签。
详情请参阅 vue 文档