ProTable 高级表格

ProTable 的诞生是为了解决项目中需要写很多 table 的样板代码的问题,所以在其中封装了很多常用的逻辑。这些封装可以简单的分类为预设行为与预设逻辑。

基础用法

通过 columns 描述列与可选筛选项,通过 request 拉取分页数据;row-keyUTable 一致,用于行主键。

使用内存数据模拟 request:多列展示、列设置与表头拖拽;查询区默认折叠;工具栏左侧为「新增 / 更多」自定义操作。

No Data
Total 0
  • 1
Go to

无查询表单

search 设为 false 可关闭顶部查询区;列上即使配置了 search: true 也不会渲染筛选项。分页与 request 仍会按当前页、每页条数请求(query 为空对象)。

仅保留工具栏、表格与分页,适合嵌入详情页或无需筛选的只读列表。

No Data
Total 0
  • 1
Go to

无工具栏

showToolbar 设为 false 可隐藏标题栏与工具栏(含「新建」、刷新、密度等内置按钮)。常与 search: false 搭配,仅保留表格与分页,适合由页面级按钮统一承载筛选与操作。

无查询区、无工具栏,仅表格与分页,适合嵌入详情页或弹窗内的精简列表。

No Data
Total 0
  • 1
Go to

远程数据 request

request 在分页变化、点击查询 / 重置、修改每页条数等时机自动调用。入参含当前页 current(从 1 起)、pageSize、表单序列化后的 query;兼容字段 currentPagecurrent 相同,建议新代码只用 current

返回值为 { data?, list?, total, success? }datalist 二选一作为当前页列表;total 为总条数;success: false 时不更新表格数据(仍会结束 loading)。隐藏分页条时内部仍按分页状态请求,仅不渲染 UPagination

vue
<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>

列配置

每列至少配置 dataIndexprop 之一(同时存在时以 dataIndex 为准);标题使用 titlelabel。查询区展示哪些列由 searchhideInSearchhideInTableorder 等控制;valueType 决定筛控件类型,options 配合 select 使用。

详见下文 列配置 ProTableColumn

search 设为 false 可关闭顶部查询区。传入对象时可配置默认折叠、收起时展示的筛选项个数、表单项 label 宽度与栅格占位等。

详见下文 查询配置 ProTableSearchConfig

分页 pagination

pagination: false 隐藏底部分页条。传入对象时可配置默认每页条数、可选每页条数列表、仅一页时是否隐藏分页等。

详见下文 分页配置 ProTablePaginationConfig

工具栏 options

默认在工具栏右侧展示 刷新Refresh2)与 密度Height 下拉:宽松 / 默认 / 紧凑,对应 UTablesize)。可通过 reloadIcondensityIconsettingIcon 自定义图标(传入 @uniboot/icons-vue 组件)。options: false 关闭全部内置工具;传入对象时可单独控制各项能力:

能力配置项默认
刷新reload开启
密度切换density开启
列设置(表头筛选)setting开启
列固定 PincolumnPin开启(需 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(不在面板展示)。
vue
<ProTable
  :options="{
    columnPin: false, // 仅隐藏「固定列首 / 列尾」Pin,保留勾选与「不固定」
  }"
/>

开启列设置后,工具栏右侧出现 Adjust 图标;勾选「商户类型」等列可即时隐藏对应表头与单元格。

No Data
Total 0
  • 1
Go to

表头拖拽排序

默认开启表头列拖拽排序(columnDrag 默认为 true),传 columnDrag: false 可关闭。拖拽 非固定列 的表头即可调整列顺序,fixed 列(如操作列)始终固定在左右两侧不参与拖拽。

  • 列上可配置 disableInColumnDrag: true 禁止单列拖拽。
  • 顺序 / 固定 / 显隐变化时触发 columnsOrderChange,payload 为 ProTableColumnSettingState(含 orderleftcenterrightfixedvisible),便于后端持久化;也可通过 getColumnSettingState() 主动读取。

开启列拖拽后,按住非固定列表头拖动即可调整顺序;右侧「操作」列保持固定。

No Data
Total 0
  • 1
Go to

行多选 rowSelection

配置 rowSelection 可开启多选列;type 当前为 'checkbox'。支持 onChange(selectedRowKeys, selectedRows),与 Ant Pro 语义一致。

详见下文 行选择配置 ProTableRowSelection

布局与插槽

自上而下依次为:tip(可选)→ 查询区 → 工具栏(actions 左 / toolBar 右)→ 表格 → 分页 → footer(可选)。

  • actions:左侧主操作,如「新增」、更多下拉(见 基础用法 示例)。
  • toolBar:右侧工具区;未自定义时内置刷新、密度、列设置(由 options 控制)。
  • 列插槽:列配置 columnSlot(如 actions)对应 #column-{columnSlot},作用域与 UTableColumn 默认插槽一致。

插槽名称与说明见下文 ProTable 插槽

实例方法

在组件上使用 ref 可调用:reloadresetSearchreloadAndResetgetSelectionRowsclearSelectiongetColumnOrdergetColumnSettingStatetableRef 为底层 UTable 实例。

useProTableRequest 与工具函数

若只需「查询 + 分页 + request」逻辑并自行拼接 UI,可使用 useProTableRequest(与 ProTable 内部同源),入参包含 columns 工厂函数、requestmanualdefaultPageSizebeforeSearchSubmitpostData 等。

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
manualRequesttrue 时首屏不自动请求,需调用实例 reload()booleanfalse
defaultPageSize默认每页条数;若 pagination 为对象且含 defaultPageSize 则以后者为准number10
headerTitle工具栏左侧标题(与 title 二选一,本属性优先)string
titleheaderTitle,未设置 headerTitle 时使用string
searchfalse 关闭查询区;true 使用默认;对象见 查询配置boolean / objecttrue
showToolbar是否展示标题栏 / 工具栏区域booleantrue
showReload是否展示内置「刷新」(可被 options 覆盖)booleantrue
searchButtonText查询按钮文案string查询
resetButtonText重置按钮文案string重置
rowSelection行多选配置,见 行选择配置object
paginationLayout透传 UPaginationlayoutstringtotal, sizes, prev, pager, next, jumper
paginationfalse 隐藏分页条;true 或对象见 分页配置boolean / objecttrue
optionsfalse 关闭内置工具;对象见 工具栏配置boolean / object内置开启刷新、密度、列设置与列拖拽
beforeSearchSubmit提交前转换 queryFunction
postData请求完成后对列表做一次映射Function
tableProps透传给 UTable 的额外 propsobjectobject

ProTable 事件

事件名说明类型
reload点击内置刷新并完成 reload 后触发Function
columnsOrderChange列展示状态变化(顺序、固定、显隐)Function

ProTable 插槽

名称位置说明
tip查询区上方列表说明、告警等;未使用时不渲染
actions工具栏左侧主操作按钮区,需自行实现新建、更多等
toolBar工具栏右侧替换内置刷新 / 密度 / 列设置;未使用时展示 options 内置按钮
footer分页下方表格底栏扩展内容
column-表格列由列配置 columnSlot 决定,如 columnSlot: 'actions'#column-actions

ProTable 暴露

名称说明类型
reload按当前分页与查询重新请求Function
resetSearch重置查询 model 为列上的初始值Function
reloadAndResetresetSearch 再回到第一页并请求Function
getSelectionRows当前选中行Function
clearSelection清空选择Function
getColumnOrder当前表格可见列从左到右顺序(order 数组)Function
getColumnSettingState列展示完整快照(含左/中/右分组与 fixedFunction

列展示持久化 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列标题 / 表单项 labelstring
width列宽string / number
minWidth最小列宽string / number
fixed固定列boolean / enum
align对齐方式enum
ellipsistrue 时等价开启超长省略boolean
showOverflowTooltip是否超长省略并 tooltipboolean
tooltip表头悬停说明string
searchtrue 时参与顶部查询区boolean
hideInSearchtrue 时在查询区隐藏boolean
hideInTabletrue 时仅作查询字段,不渲染表格列boolean
hideInSettingtrue 时不在列设置面板中展示boolean
disableInSettingtrue 时在列设置中展示但不可取消勾选,且不展示 Pin / 拖拽按钮boolean
disableInColumnDragtrue 时禁止通过表头拖拽调整该列顺序boolean
order查询表单项排序,数字越小越靠前number
valueType筛控件类型enum
fieldProps透传给具体控件;可用 initialValue 作为查询默认值object
optionsvalueTypeselect 时的选项array
placeholder查询控件占位符string
columnSlot自定义列插槽名,如 action 对应 #column-actionstring

request 入参 ProTableRequestParams

名称说明类型默认值
current当前页,从 1 开始number
pageSize每页条数number
query当前查询表单序列化后的对象object
currentPagecurrent 相同,兼容旧写法number

request 返回值 ProTableRequestResult

名称说明类型默认值
data当前页数据,与 list 二选一array
list当前页数据(旧字段名),与 data 二选一array
total总条数number
successfalse 时不更新表格数据(仍会结束 loading)boolean

查询配置 ProTableSearchConfig

名称说明类型默认值
defaultCollapsedtrue 时默认只展示前若干筛选项,可展开收起boolean
labelWidth表单项 label 宽度,如 72'80px'string / number
span24 栅格占位,默认 6(大屏约每行 4 个)number6

分页配置 ProTablePaginationConfig

名称说明类型默认值
defaultPageSize默认每页条数number
pageSizeOptions每页条数可选列表array
hideOnSinglePage仅一页时是否隐藏分页boolean

工具栏配置 ProTableOptions

options: false 时关闭全部内置工具栏能力;传入对象时会与内置默认值合并,仅写了 columnDrag 等部分字段时,其余项(如 reloaddensitysetting)仍按默认开启,传 false 可单独关闭某项。

名称说明类型默认值
reload是否显示刷新按钮(靠右)booleantrue
reloadIcon刷新按钮图标,默认 Refresh2ComponentRefresh2
density是否显示密度下拉(宽松 / 默认 / 紧凑,映射 UTablesizebooleantrue
densityIcon密度按钮图标,默认 HeightComponentHeight
setting是否显示列设置(表头筛选);勾选后即时生效booleantrue
settingIcon列设置按钮图标,默认 AdjustComponentAdjust
columnPin列设置中是否显示「固定列首 / 固定列尾」Pin 按钮;false 时仅隐藏 Pin,保留勾选与「不固定」booleantrue
columnDrag是否允许拖拽排序:表头拖拽调整非固定列顺序,并在列设置「不固定」分组显示 SixDot;固定列不参与booleantrue

行选择配置 ProTableRowSelection

名称说明类型默认值
type选择列类型,当前为 checkboxenum
width选择列宽度number
reserveSelection数据更新后是否保留选中boolean
selectable决定某行是否可选Function
onChange选中变化回调 (selectedRowKeys, selectedRows)Function