跳到主要内容

Table 表格 ​

WebH5

数据表格。支持自定义列、本地排序、斑马纹、竖向边框、行多选、加载遮罩与空态,移动端自动横向滚动。

何时使用 ​

展示结构化列表数据,需要排序、选择或自定义单元格内容时;行数极大(万级)时开启 virtual 虚拟滚动。

何时不使用 ​

virtual 模式下不支持 expandable 展开行(可变行高与窗口化冲突),同时设置时 console.warn 并忽略 expandable;virtual 必须配合 maxHeight,否则不生效;行高必须固定(由 size 决定),单元格内容不可撑高行。树形数据(treeProps)与 expandable 互斥(console.warn 后忽略 expandable),与 virtual 冲突时 virtual 优先、树形忽略;树形模式排序只作用于顶层行,子行跟随父行。简单图文列表用 Card/Stack 更轻。

Props ​

名称类型默认值说明
columnsTableColumn[]-列配置:{ key, title, width?, align?: 'left'|'center'|'right', sortable?: boolean | 'custom'(服务端排序只 emit 不本地排), fixed?: 'left'|'right', filters?: { label, value }[], filterMultiple?: boolean };固定列必须指定 width;配置 filters 后列头出现筛选图标
dataobject[]"[]"行数据,每行为对象,字段名对应 columns.key
loadingbooleanfalse加载中,表体区域显示半透明遮罩与旋转圆弧
stripebooleanfalse斑马纹,间隔行使用弱化底色
borderbooleanfalse显示竖向边框
sizestring:'sm' | 'md' | 'lg'"md"尺寸,行高分别为 40 / 48 / 56
selectablebooleanfalse首列渲染多选框,表头为全选(支持半选态);树形/虚拟等组合见下方说明
selectedKeysarray"[]"已选行键数组,对应 v-model:selectedKeys
rowKeystring"id"行唯一键字段名
emptyTextstring-空态文案,默认取语言包 table.empty(zh-CN 为「暂无数据」),显式传入优先
maxHeightnumber | string-表体最大高度(数字按 px 计),超出后表体纵向滚动且表头 sticky 固定
expandablebooleanfalse可展开行,首列渲染展开箭头(在多选框列左侧),展开状态内部管理,内容用 expand 插槽
expandedRowKeysarray"undefined"受控展开行键数组,对应 v-model:expandedRowKeys;不传则内部管理
virtualbooleanfalse虚拟滚动:表体只渲染可视窗口行(上下各 5 行 overscan),需配合 maxHeight 使用;行高取 size 固定值(sm 40 / md 48 / lg 56),万级数据可流畅渲染
showSummarybooleanfalse合计行:固定在表体底部(弱化底色 + 中等字重 + 顶部 1px 分隔线);未传 summary 时数值列自动求和(该列全部为 number 或可转 number 的字符串才求和,保留原最大小数位),首个非数值列显示「合计」(语言包 table.summary)
summarystring[]-自定义合计行内容:每列一个字符串直接渲染(简单模式),传入后覆盖自动求和
treeProps{ children?: string }-树形数据:传入即开启树形模式,children 指定子级字段名(默认 'children')。首列出现缩进(每层 16px)与展开箭头,默认全部展开,点击箭头收起/展开子树(按 rowKey 内部管理);排序只作用于顶层行,子行跟随父行

Events ​

名称载荷说明
update:selectedKeys(string | number)[]选择变化时触发,配合 v-model:selectedKeys
update:expandedRowKeys(string | number)[]受控展开行变化,配合 v-model:expandedRowKeys
select(string | number)[]选择变化时触发,参数为最新键数组
sort{ key: string; order: 'asc' | 'desc' | null }点击 sortable 列头时触发,顺序循环 asc → desc → null
filter-change{ key: string; values: unknown[] }筛选面板点击确定/重置后触发,values 为该列当前生效的选中值(重置为空数组)
row-click(row: object, index: number)点击行时触发;点击行首 checkbox 不触发

Slots ​

名称说明
<column.key>动态具名插槽自定义单元格,scope { row, index, value }
expand展开行内容(需开启 expandable),渲染为跨整行宽的内嵌区域,scope { row, index }
empty自定义空态内容

示例 ​

基础用法 ​

示例加载中…

固定列(左右固定) ​

示例加载中…

固定头滚动 ​

示例加载中…

展开行详情 ​

示例加载中…

行高尺寸 ​

示例加载中…

排序(含数值与中文) ​

示例加载中…

列对齐方式 ​

示例加载中…

多选(v-model + @select) ​

示例加载中…

斑马纹与竖向边框 ​

示例加载中…

行点击事件 ​

示例加载中…

加载、空态(文本 + 自定义插槽) ​

示例加载中…

虚拟滚动(1 万行) ​

示例加载中…

自定义列插槽 + 自定义行键 ​

示例加载中…

列筛选 ​

示例加载中…

合计行 ​

示例加载中…

树形数据 ​

示例加载中…

Playground ​

加载中…

跨端版本 ​

该组件同时提供 uni-app / uni-app X 实现(H5 / 微信小程序 / App),API 可能略有差异,见 uni-app 端 Table 文档(含手机预览)。