跳到主要内容

Table 表格 ​

uni-appH5微信小程序App

跨端数据表格:横向 scroll-view 承载,支持排序、多选、斑马纹、固定高度滚动、可展开行、树形数据、虚拟滚动与合计行,API 与 Web 端 Table 对齐。

何时使用 ​

结构化数据的展示与操作:列表管理、数据对比、报表摘要。

何时不使用 ​

卡片式、瀑布流等非线性布局;仅两三个字段的简单展示用 Descriptions。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
Table 表格 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
columnsTableColumn[]-列配置:{ key, title, width?, align?: 'left'|'center'|'right', sortable?: boolean | 'custom'(服务端排序只 emit 不本地排) }
dataobject[]"[]"行数据,每行为对象,字段名对应 columns.key
loadingbooleanfalse加载中,表体区域显示半透明遮罩与旋转指示
stripebooleanfalse斑马纹,间隔行使用弱化底色
borderbooleanfalse显示竖向边框
sizestring:'sm' | 'md' | 'lg'"md"尺寸,行高分别为 40 / 48 / 56
selectablebooleanfalse首列渲染多选框,表头为全选(支持半选态)
selectedKeysarray"[]"已选行键数组,对应 v-model:selectedKeys
rowKeystring"id"行唯一键字段名
emptyTextstring"暂无数据"空态文案,默认「暂无数据」,显式传入优先
maxHeightnumber | string""表体最大高度(数字按 px 计),超出后表体纵向滚动
expandablebooleanfalse可展开行,首列渲染展开箭头,展开状态内部管理,内容用 expand 插槽;与虚拟/树形互斥
expandedRowKeysarray"undefined"受控展开行键数组,对应 v-model:expandedRowKeys;不传则内部管理
virtualbooleanfalse虚拟滚动:表体只渲染可视窗口行(上下各 5 行 overscan),需配合 maxHeight 使用;行高取 size 固定值,万级数据可流畅渲染
showSummarybooleanfalse合计行:固定在表体底部;未传 summary 时数值列自动求和(保留原最大小数位),首个非数值列显示「合计」
summarystring[]"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="暂无组件数据" />