ProTable 高级表格
ProTable 的诞生是为了解决项目中需要写很多 table 的样板代码的问题,所以在其中封装了很多常用的逻辑。这些封装可以简单的分类为预设行为与预设逻辑。
基础用法
通过 columns 描述列与可选筛选项,通过 request 拉取分页数据;row-key 与 UTable 一致,用于行主键。
使用内存数据模拟 request:多列展示、列设置与表头拖拽;查询区默认折叠;工具栏左侧为「新增 / 更多」自定义操作。
无查询表单
将 search 设为 false 可关闭顶部查询区;列上即使配置了 search: true 也不会渲染筛选项。分页与 request 仍会按当前页、每页条数请求(query 为空对象)。
仅保留工具栏、表格与分页,适合嵌入详情页或无需筛选的只读列表。
无工具栏
将 showToolbar 设为 false 可隐藏标题栏与工具栏(含「新建」、刷新、密度等内置按钮)。常与 search: false 搭配,仅保留表格与分页,适合由页面级按钮统一承载筛选与操作。
无查询区、无工具栏,仅表格与分页,适合嵌入详情页或弹窗内的精简列表。
远程数据 request
request 在分页变化、点击查询 / 重置、修改每页条数等时机自动调用。入参含当前页 current(从 1 起)、pageSize、表单序列化后的 query;兼容字段 currentPage 与 current 相同,建议新代码只用 current。
返回值为 { data?, list?, total, success? }:data 与 list 二选一作为当前页列表;total 为总条数;success: false 时不更新表格数据(仍会结束 loading)。隐藏分页条时内部仍按分页状态请求,仅不渲染 UPagination。
<script setup lang="ts">
import { ProTable } from 'uniboot-ui'
const columns = [
{ dataIndex: 'name', title: '名称', search: true },
{
dataIndex: 'status',
title: '状态',
search: true,
valueType: 'select' as const,
options: [
{ label: '启用', value: 1 },
{ label: '停用', value: 0 },
],
},
]
async function request({ current, pageSize, query }) {
const res = await fetch('/api/list', {
method: 'POST',
body: JSON.stringify({ page: current, pageSize, ...query }),
}).then((r) => r.json())
return { data: res.data, total: res.total, success: true }
}
</script>
<template>
<pro-table
row-key="id"
header-title="列表示例"
:columns="columns"
:request="request"
/>
</template>列配置
每列至少配置 dataIndex 或 prop 之一(同时存在时以 dataIndex 为准);标题使用 title 或 label。查询区展示哪些列由 search、hideInSearch、hideInTable、order 等控制;valueType 决定筛控件类型,options 配合 select 使用。
详见下文 列配置 ProTableColumn。
查询区 search
将 search 设为 false 可关闭顶部查询区。传入对象时可配置默认折叠、收起时展示的筛选项个数、表单项 label 宽度与栅格占位等。
详见下文 查询配置 ProTableSearchConfig。
分页 pagination
pagination: false 隐藏底部分页条。传入对象时可配置默认每页条数、可选每页条数列表、仅一页时是否隐藏分页等。
详见下文 分页配置 ProTablePaginationConfig。
工具栏 options
默认在工具栏右侧展示 刷新(Refresh2)与 密度(Height 下拉:宽松 / 默认 / 紧凑,对应 UTable 的 size)。可通过 reloadIcon、densityIcon、settingIcon 自定义图标(传入 @uniboot/icons-vue 组件)。options: false 关闭全部内置工具;传入对象时可单独控制各项能力:
| 能力 | 配置项 | 默认 |
|---|---|---|
| 刷新 | reload | 开启 |
| 密度切换 | density | 开启 |
| 列设置(表头筛选) | setting | 开启 |
| 列固定 Pin | columnPin | 开启(需 setting 开启时生效) |
| 表头拖拽排序 | columnDrag | 开启 |
详见下文 工具栏配置 ProTableOptions。
表头筛选(列设置)
工具栏右侧默认展示列设置入口(Adjust 图标),传 options.setting: false 可关闭。点击后弹出 列展示 面板(默认宽度约 420px),按 固定列首 / 不固定 / 固定列尾 分组管理列:
- 勾选控制列显示 / 隐藏,无需确认,即时生效。
- 行悬停时显示 PinTop(固定列首)、PinBottom(固定列尾)、Center(不固定)按钮;SixDot 在不固定分组内用于拖拽排序(默认随
columnDrag开启,传columnDrag: false可关闭)。 options.columnPin:为false时隐藏上述 Pin 按钮(Center 取消固定仍可用);默认true。仅在开启setting时有意义。- 顶部 重置 恢复初始展示、固定与顺序。
- 列设置入口默认 开启,传
setting: false可关闭。 - 源列
fixed: 'right'(如操作列)或disableInSetting: true:勾选禁用,且不展示 Pin / 拖拽操作按钮。 - 列上可配置
hideInSetting(不在面板展示)。
<ProTable
:options="{
columnPin: false, // 仅隐藏「固定列首 / 列尾」Pin,保留勾选与「不固定」
}"
/>开启列设置后,工具栏右侧出现 Adjust 图标;勾选「商户类型」等列可即时隐藏对应表头与单元格。
表头拖拽排序
默认开启表头列拖拽排序(columnDrag 默认为 true),传 columnDrag: false 可关闭。拖拽 非固定列 的表头即可调整列顺序,fixed 列(如操作列)始终固定在左右两侧不参与拖拽。
- 列上可配置
disableInColumnDrag: true禁止单列拖拽。 - 顺序 / 固定 / 显隐变化时触发
columnsOrderChange,payload 为ProTableColumnSettingState(含order、left、center、right、fixed、visible),便于后端持久化;也可通过getColumnSettingState()主动读取。
开启列拖拽后,按住非固定列表头拖动即可调整顺序;右侧「操作」列保持固定。
行多选 rowSelection
配置 rowSelection 可开启多选列;type 当前为 'checkbox'。支持 onChange(selectedRowKeys, selectedRows),与 Ant Pro 语义一致。
详见下文 行选择配置 ProTableRowSelection。
布局与插槽
自上而下依次为:tip(可选)→ 查询区 → 工具栏(actions 左 / toolBar 右)→ 表格 → 分页 → footer(可选)。
- actions:左侧主操作,如「新增」、更多下拉(见 基础用法 示例)。
- toolBar:右侧工具区;未自定义时内置刷新、密度、列设置(由
options控制)。 - 列插槽:列配置
columnSlot(如actions)对应#column-{columnSlot},作用域与UTableColumn默认插槽一致。
插槽名称与说明见下文 ProTable 插槽。
实例方法
在组件上使用 ref 可调用:reload、resetSearch、reloadAndReset、getSelectionRows、clearSelection、getColumnOrder、getColumnSettingState;tableRef 为底层 UTable 实例。
useProTableRequest 与工具函数
若只需「查询 + 分页 + request」逻辑并自行拼接 UI,可使用 useProTableRequest(与 ProTable 内部同源),入参包含 columns 工厂函数、request、manual、defaultPageSize、beforeSearchSubmit、postData 等。
getColumnKey(col) 读取 dataIndex ?? prop(缺失时抛错);getColumnTitle(col) 读取 title ?? label ?? 字段名。
开发与联调
在 uniboot-ui 根目录执行 pnpm dev 或可使用 pnpm dev(或 play 配置)对 ProTable 做热更新调试;安装依赖需能解析 uniboot-ui 与 @uniboot/* 所用 registry(见 开发指南)。
ProTable API
ProTable 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| columns | 列定义,必填 | array | — |
| request | 远程列表请求,必填 | Function | — |
| rowKey | 行主键字段名,与 UTable 一致,必填 | string | — |
| manualRequest | 为 true 时首屏不自动请求,需调用实例 reload() | boolean | false |
| defaultPageSize | 默认每页条数;若 pagination 为对象且含 defaultPageSize 则以后者为准 | number | 10 |
| headerTitle | 工具栏左侧标题(与 title 二选一,本属性优先) | string | — |
| title | 同 headerTitle,未设置 headerTitle 时使用 | string | — |
| search | false 关闭查询区;true 使用默认;对象见 查询配置 | boolean / object | true |
| showToolbar | 是否展示标题栏 / 工具栏区域 | boolean | true |
| showReload | 是否展示内置「刷新」(可被 options 覆盖) | boolean | true |
| searchButtonText | 查询按钮文案 | string | 查询 |
| resetButtonText | 重置按钮文案 | string | 重置 |
| rowSelection | 行多选配置,见 行选择配置 | object | — |
| paginationLayout | 透传 UPagination 的 layout | string | total, sizes, prev, pager, next, jumper |
| pagination | false 隐藏分页条;true 或对象见 分页配置 | boolean / object | true |
| options | false 关闭内置工具;对象见 工具栏配置 | boolean / object | 内置开启刷新、密度、列设置与列拖拽 |
| beforeSearchSubmit | 提交前转换 query | Function | — |
| postData | 请求完成后对列表做一次映射 | Function | — |
| tableProps | 透传给 UTable 的额外 props | object | object |
ProTable 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| reload | 点击内置刷新并完成 reload 后触发 | Function |
| columnsOrderChange | 列展示状态变化(顺序、固定、显隐) | Function |
ProTable 插槽
| 名称 | 位置 | 说明 |
|---|---|---|
| tip | 查询区上方 | 列表说明、告警等;未使用时不渲染 |
| actions | 工具栏左侧 | 主操作按钮区,需自行实现新建、更多等 |
| toolBar | 工具栏右侧 | 替换内置刷新 / 密度 / 列设置;未使用时展示 options 内置按钮 |
| footer | 分页下方 | 表格底栏扩展内容 |
| column- | 表格列 | 由列配置 columnSlot 决定,如 columnSlot: 'actions' → #column-actions |
ProTable 暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| reload | 按当前分页与查询重新请求 | Function |
| resetSearch | 重置查询 model 为列上的初始值 | Function |
| reloadAndReset | 先 resetSearch 再回到第一页并请求 | Function |
| getSelectionRows | 当前选中行 | Function |
| clearSelection | 清空选择 | Function |
| getColumnOrder | 当前表格可见列从左到右顺序(order 数组) | Function |
| getColumnSettingState | 列展示完整快照(含左/中/右分组与 fixed) | Function |
列展示持久化 ProTableColumnSettingState
| 字段 | 说明 | | -------- | --------------------------------------------------------------- | -------------- | | order | 表格可见列完整顺序(左固定 + 不固定 + 右固定) | | left | 左固定区域内的列 key 顺序 | | center | 不固定区域内的列 key 顺序 | | right | 右固定区域内的列 key 顺序 | | fixed | 各列固定状态:false 不固定,'left' 左固定,'right' 右固定 | | visible | 各列是否勾选显示 | | tableRef | 底层 UTable 实例 | object |
列配置 ProTableColumn
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| dataIndex | 列字段,与 prop 二选一至少填其一;同时存在时以本字段为准 | string | — |
| prop | 列字段(Element 习惯) | string | — |
| title | 列标题,与 label 二选一 | string | — |
| label | 列标题 / 表单项 label | string | — |
| width | 列宽 | string / number | — |
| minWidth | 最小列宽 | string / number | — |
| fixed | 固定列 | boolean / enum | — |
| align | 对齐方式 | enum | — |
| ellipsis | 为 true 时等价开启超长省略 | boolean | — |
| showOverflowTooltip | 是否超长省略并 tooltip | boolean | — |
| tooltip | 表头悬停说明 | string | — |
| search | 为 true 时参与顶部查询区 | boolean | — |
| hideInSearch | 为 true 时在查询区隐藏 | boolean | — |
| hideInTable | 为 true 时仅作查询字段,不渲染表格列 | boolean | — |
| hideInSetting | 为 true 时不在列设置面板中展示 | boolean | — |
| disableInSetting | 为 true 时在列设置中展示但不可取消勾选,且不展示 Pin / 拖拽按钮 | boolean | — |
| disableInColumnDrag | 为 true 时禁止通过表头拖拽调整该列顺序 | boolean | — |
| order | 查询表单项排序,数字越小越靠前 | number | — |
| valueType | 筛控件类型 | enum | — |
| fieldProps | 透传给具体控件;可用 initialValue 作为查询默认值 | object | — |
| options | valueType 为 select 时的选项 | array | — |
| placeholder | 查询控件占位符 | string | — |
| columnSlot | 自定义列插槽名,如 action 对应 #column-action | string | — |
request 入参 ProTableRequestParams
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| current | 当前页,从 1 开始 | number | — |
| pageSize | 每页条数 | number | — |
| query | 当前查询表单序列化后的对象 | object | — |
| currentPage | 与 current 相同,兼容旧写法 | number | — |
request 返回值 ProTableRequestResult
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| data | 当前页数据,与 list 二选一 | array | — |
| list | 当前页数据(旧字段名),与 data 二选一 | array | — |
| total | 总条数 | number | — |
| success | 为 false 时不更新表格数据(仍会结束 loading) | boolean | — |
查询配置 ProTableSearchConfig
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| defaultCollapsed | 为 true 时默认只展示前若干筛选项,可展开收起 | boolean | — |
| labelWidth | 表单项 label 宽度,如 72 或 '80px' | string / number | — |
| span | 24 栅格占位,默认 6(大屏约每行 4 个) | number | 6 |
分页配置 ProTablePaginationConfig
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| defaultPageSize | 默认每页条数 | number | — |
| pageSizeOptions | 每页条数可选列表 | array | — |
| hideOnSinglePage | 仅一页时是否隐藏分页 | boolean | — |
工具栏配置 ProTableOptions
options: false 时关闭全部内置工具栏能力;传入对象时会与内置默认值合并,仅写了 columnDrag 等部分字段时,其余项(如 reload、density、setting)仍按默认开启,传 false 可单独关闭某项。
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| reload | 是否显示刷新按钮(靠右) | boolean | true |
| reloadIcon | 刷新按钮图标,默认 Refresh2 | Component | Refresh2 |
| density | 是否显示密度下拉(宽松 / 默认 / 紧凑,映射 UTable 的 size) | boolean | true |
| densityIcon | 密度按钮图标,默认 Height | Component | Height |
| setting | 是否显示列设置(表头筛选);勾选后即时生效 | boolean | true |
| settingIcon | 列设置按钮图标,默认 Adjust | Component | Adjust |
| columnPin | 列设置中是否显示「固定列首 / 固定列尾」Pin 按钮;false 时仅隐藏 Pin,保留勾选与「不固定」 | boolean | true |
| columnDrag | 是否允许拖拽排序:表头拖拽调整非固定列顺序,并在列设置「不固定」分组显示 SixDot;固定列不参与 | boolean | true |
行选择配置 ProTableRowSelection
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 选择列类型,当前为 checkbox | enum | — |
| width | 选择列宽度 | number | — |
| reserveSelection | 数据更新后是否保留选中 | boolean | — |
| selectable | 决定某行是否可选 | Function | — |
| onChange | 选中变化回调 (selectedRowKeys, selectedRows) | Function | — |