Table 表格
uni-appH5微信小程序App
跨端数据表格:横向 scroll-view 承载,支持排序、多选、斑马纹、固定高度滚动、可展开行、树形数据、虚拟滚动与合计行,API 与 Web 端 Table 对齐。
何时使用
结构化数据的展示与操作:列表管理、数据对比、报表摘要。
何时不使用
卡片式、瀑布流等非线性布局;仅两三个字段的简单展示用 Descriptions。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columns | TableColumn[] | - | 列配置:{ key, title, width?, align?: 'left'|'center'|'right', sortable?: boolean | 'custom'(服务端排序只 emit 不本地排) } |
data | object[] | "[]" | 行数据,每行为对象,字段名对应 columns.key |
loading | boolean | false | 加载中,表体区域显示半透明遮罩与旋转指示 |
stripe | boolean | false | 斑马纹,间隔行使用弱化底色 |
border | boolean | false | 显示竖向边框 |
size | string:'sm' | 'md' | 'lg' | "md" | 尺寸,行高分别为 40 / 48 / 56 |
selectable | boolean | false | 首列渲染多选框,表头为全选(支持半选态) |
selectedKeys | array | "[]" | 已选行键数组,对应 v-model:selectedKeys |
rowKey | string | "id" | 行唯一键字段名 |
emptyText | string | "暂无数据" | 空态文案,默认「暂无数据」,显式传入优先 |
maxHeight | number | string | "" | 表体最大高度(数字按 px 计),超出后表体纵向滚动 |
expandable | boolean | false | 可展开行,首列渲染展开箭头,展开状态内部管理,内容用 expand 插槽;与虚拟/树形互斥 |
expandedRowKeys | array | "undefined" | 受控展开行键数组,对应 v-model:expandedRowKeys;不传则内部管理 |
virtual | boolean | false | 虚拟滚动:表体只渲染可视窗口行(上下各 5 行 overscan),需配合 maxHeight 使用;行高取 size 固定值,万级数据可流畅渲染 |
showSummary | boolean | false | 合计行:固定在表体底部;未传 summary 时数值列自动求和(保留原最大小数位),首个非数值列显示「合计」 |
summary | string[] | "undefined" | 自定义合计行内容:每列一个字符串直接渲染,传入后覆盖自动求和 |
treeProps | { children?: string } | "undefined" | 树形数据:传入即开启树形模式,children 指定子级字段名(默认 'children')。首列出现缩进与展开箭头,默认全部展开;排序只作用于顶层行,子行跟随父行;与虚拟互斥 |
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 |
row-click | (row: object, index: number) | 点击行时触发;点击行首复选框/展开箭头不触发 |
Slots
| 名称 | 说明 |
|---|---|
<column.key> | 动态具名插槽自定义单元格,scope { row, index, value } |
expand | 可展开行内容,scope { row, index } |
empty | 自定义空态内容 |
示例
基础用法
vue
<Table :columns="tableColumns" :data="tableData" />斑马纹与边框
vue
<Table :columns="tableColumns" :data="tableData" stripe border size="sm" />可排序列
vue
<Table :columns="sortColumns" :data="tableData" stripe />可选择行
vue
<Table :columns="tableColumns" :data="tableData" selectable v-model:selected-keys="s" />可展开行
vue
<Table :columns="tableColumns" :data="tableData" expandable>
<template #expand="{ row }">
<view style="padding: 8px 12px;">
<text style="font-size: 12px; color: #8a93a3;">{{ row.name }} · 分类 {{ row.cat }} · 健康分 {{ row.score }}</text>
</view>
</template>
</Table>合计行
vue
<Table :columns="tableColumns" :data="tableData" show-summary />树形数据
vue
<Table :columns="tableColumns" :data="treeTableData" :tree-props="treeCfg" row-key="id" />虚拟滚动(300 行)
vue
<Table :columns="tableColumns" :data="bigTableData" virtual max-height="240" size="sm" />空数据
vue
<Table :columns="tableColumns" :data="[]" empty-text="暂无组件数据" />