ProTable 高级表格 ​

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

基础用法 ​

通过 columns 描述列与可选筛选项，通过外部传入 data、loading 等受控属性渲染表格，并在 @search、@pagination-change 等事件中获取最新查询条件；row-key 与 UTable 一致，用于行主键。

多列展示、列设置与表头拖拽；查询区默认折叠；工具栏左侧为「新增 / 更多」自定义操作。

名称
编号
负责人
No Data
Total 0
  • 1
Go to

无查询表单 ​

将 search 设为 false 可关闭顶部查询区；列上即使配置了 search: true 也不会渲染筛选项。此时外部无法收到搜索事件，通常表格仅用于静态数据或简单的外部过滤。

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

No Data
Total 0
  • 1
Go to

无工具栏 ​

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

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

No Data
Total 0
  • 1
Go to

空状态 ​

数据为空时，ProTable 会展示底层 UTable 的空状态。可通过 tableProps.emptyText 透传自定义空状态文案，也可以使用 #empty 插槽自定义空状态内容和样式。

使用 #empty 插槽自定义空状态，并通过按钮切换有数据 / 无数据场景。

暂无匹配项目

可以调整筛选条件后重试，或新建一个项目。

远程数据 request ​

request 是 ProTable 最重要的 API。传入后组件会自动管理 data / loading / total，并在查询表单提交、分页变化、params 变更时重新执行，无需手动绑定 @search、@reset、@reload、@pagination-change。

request 接收的第一个参数为查询表单与 params 的合并结果，且一定包含 current、pageSize（对齐 Ant Design 规范）。params 优先级更高，会覆盖同名的查询表单字段。

返回值必须包含 data 和 success；分页场景还需传 total（不传时使用 data.length）。若 success 不为 true，表格不会更新数据。

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ProTable } from 'uniboot-ui'

type DataType = {
  id: number
  name: string
}

type Params = {
  deptId?: string
}

const params = ref<Params>({ deptId: 'rd' })

const columns = [
  { key: 'name', title: '名称', search: true },
  {
    key: 'status',
    title: '状态',
    search: true,
    valueType: 'select' as const,
    options: [
      { label: '启用', value: 1 },
      { label: '停用', value: 0 },
    ],
  },
]

async function request(
  requestParams: Params & { current: number; pageSize: number }
) {
  const msg = await fetch('/api/list', {
    method: 'POST',
    body: JSON.stringify({
      page: requestParams.current,
      pageSize: requestParams.pageSize,
      ...requestParams,
    }),
  }).then((r) => r.json())

  return {
    data: msg.result,
    success: true,
    total: msg.total,
  }
}
</script>

<template>
  <pro-table
    row-key="id"
    :columns="columns"
    :params="params"
    :request="request"
  />
</template>

可选属性：params（外部参数，变更时重新请求）、manual（不自动首屏请求，需调用 reload / fetchData）。

受控数据与状态 ​

若不使用 request，ProTable 为完全受控组件：外部负责管理查询请求、分页和加载状态，并将数据通过 data 传入。在分页变化、点击查询 / 重置、修改每页条数等时机会通过 @search、@reset、@pagination-change、@reload 事件通知外部更新。

也可在外部使用 usePaging 自行拼装：

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ProTable, usePaging } from 'uniboot-ui'

const columns = [{ key: 'name', title: '名称', search: true }]
const query = ref<Record<string, unknown>>({})

const { pager, handleSearch, handleReload, handlePaginationChange } = usePaging(
  {
    getQuery: () => query.value,
    request: async (params) => {
      const res = await fetch('/api/list', {
        method: 'POST',
        body: JSON.stringify(params),
      }).then((r) => r.json())
      return { data: res.result, success: true, total: res.total }
    },
  }
)

function onSearch(value: Record<string, unknown>) {
  Object.assign(query.value, value)
  handleSearch()
}
</script>

<template>
  <pro-table
    row-key="id"
    :columns="columns"
    :data="pager.lists"
    :loading="pager.loading"
    :total="pager.count"
    @search="onSearch"
    @reload="handleReload"
    @pagination-change="handlePaginationChange"
  />
</template>

列配置 ​

每列至少配置 key 或 prop 之一（同时存在时以 key 为准）；标题使用 title 或 label。查询区展示哪些列由 search、hideInSearch、hideInTable、order 等控制；valueType 决定筛控件类型，options 配合 select 使用。

详见下文 列配置 ProTableColumn。

将 search 设为 false 可关闭顶部查询区。传入对象时可配置默认折叠、表单项 label 宽度等；具体筛选项由列配置中的 search、valueType、fieldProps 等字段决定。

详见下文 查询配置 ProTableSearchConfig。

QueryFilter 查询区配置 ​

ProTable 内置查询区基于 QueryFilter 实现，默认显示在表格上方、工具栏之前。它负责表单布局、查询 / 重置按钮、展开 / 收起行为；ProTable 负责把列配置转换为 QueryFilter 表单项，并在点击查询时重新请求列表。

关闭或配置查询区 ​

vue
<ProTable
  :search="{
    defaultCollapsed: true,
    labelWidth: 72,
  }"
/>
配置说明
search: false完全关闭顶部查询区
search: true使用默认查询区配置
search.defaultCollapsed是否默认收起更多筛选项，默认 true
search.labelWidth查询表单项 label 宽度，默认 72px
searchButtonText覆盖查询按钮文案，默认来自国际化 查询
resetButtonText覆盖重置按钮文案，默认来自国际化 重置

哪些列会进入查询区 ​

只有列配置中显式设置 search: true 的字段会进入 QueryFilter；再通过 hideInSearch: true 排除。展示顺序由 order 控制，数字越小越靠前，未配置时按 100 处理。

ts
const columns = [
  {
    title: '名称',
    key: 'name',
    search: true,
    order: 1,
  },
  {
    title: '编号',
    key: 'code',
    search: true,
    order: 2,
  },
  {
    title: '创建时间',
    key: 'createdAt',
    search: true,
    valueType: 'daterange',
    hideInTable: true,
    order: 3,
  },
]

hideInTable: true 适合“只作为查询条件、不展示为表格列”的字段；hideInSearch: true 适合“展示为表格列、但不出现在查询区”的字段。

筛选控件类型 ​

查询区根据列的 valueType 渲染不同控件：

valueType控件说明
未设置 / inputUInput默认文本输入，placeholder 默认为 请输入
selectUSelect + UOption使用列上的 options 生成选项
dateUDatePicker单日期，默认 value-format="YYYY-MM-DD"
daterangeUDatePicker日期范围，默认 value-format="YYYY-MM-DD"

可通过 placeholder 覆盖占位文本，通过 fieldProps 透传到具体控件：

ts
const statusColumn = {
  title: '状态',
  key: 'status',
  search: true,
  valueType: 'select',
  placeholder: '请选择状态',
  options: [
    { label: '启用', value: 1 },
    { label: '禁用', value: 0 },
  ],
  fieldProps: {
    filterable: true,
    initialValue: 1,
  },
}

自定义查询表单项 0.1.9 ​

当内置 valueType 无法满足需求时，可在列上配置 searchSlot，并通过 #search-{searchSlot} 插槽自定义单个查询字段的控件。插槽作用域参数：

参数说明
column当前列配置
query完整查询 model（响应式）
fieldKey当前字段 key（key ?? prop）
modelValue当前字段值
onUpdate:modelValue更新当前字段值
setValue同 onUpdate:modelValue，便于直接作为回调
vue
<!-- 列配置 -->
{ key: 'country', title: '国家/地区', search: true, hideInTable: true,
searchSlot: 'country', }

<!-- 模板 -->
<template #search-country="{ modelValue, setValue }">
  <u-country-select
    :model-value="modelValue"
    clearable
    style="width: 100%"
    @update:model-value="setValue"
  />
</template>

未提供对应插槽时，仍会按 valueType 渲染默认控件。

名称
国家/地区
Select
状态
Please select

默认值、重置与请求参数 ​

查询模型会根据查询列自动生成 key，key 来自 key ?? prop。若列的 fieldProps.initialValue 存在，会作为初始查询值；点击重置时也会恢复到该值，否则恢复为 undefined。

点击 查询 时：

  • 当前页重置为第 1 页；
  • 抛出 @search 事件，传递序列化后的 query。

展开 / 收起与响应式布局 ​

QueryFilter 会根据容器宽度自适应列数：宽屏最多 4 列，随后降为 3 / 2 / 1 列。折叠状态下，操作区固定在首行最后一列，因此首行会展示 当前列数 - 1 个筛选项；当筛选项超过首行容量时，会自动显示 展开 / 收起 按钮。

当前 ProTable 查询区不需要手动配置栅格列数；如需完全自定义筛选 UI，可设置 search: false 后在外部自行组合 QueryFilter 或使用 useProTableRequest。

分页 pagination ​

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

详见下文 分页配置 ProTablePaginationConfig。

表格密度 density ​

通过顶层 density 属性设置表格密度，可选 loose（宽松）、default（默认）和 compact（紧凑），与工具栏密度下拉选项保持一致。组件会将其映射到底层 UTable 的 size。

vue
<ProTable density="compact" />

工具栏 options ​

工具栏右侧可通过 reload、density、setting 分别开启 刷新（Refresh2）、密度（Height 下拉：宽松 / 默认 / 紧凑，对应 UTable 的 size）与 列设置（Adjust）。顶层 density 用于设置当前密度，options.density 仅控制是否显示密度切换入口。可通过 reloadIcon、densityIcon、settingIcon 自定义图标（传入 @uniboot/icons-vue 组件）。options: false 关闭全部内置工具；传入对象时可单独控制各项能力：

能力配置项默认
刷新reload关闭
密度切换density关闭
列设置（表头筛选）setting关闭
列固定 PincolumnPin开启（需 setting 开启时生效）

详见下文 工具栏配置 ProTableOptions。

表头筛选（列设置） ​

传 options.setting: true 可在工具栏右侧展示列设置入口（Adjust 图标）。点击后弹出 列展示 面板（默认宽度约 420px），按 固定列首 / 不固定 / 固定列尾 分组管理列：

  • 勾选控制列显示 / 隐藏，无需确认，即时生效。
  • 行悬停时显示 PinTop（固定列首）、PinBottom（固定列尾）、Center（不固定）按钮。
  • options.columnPin：为 false 时隐藏上述 Pin 按钮（Center 取消固定仍可用）；默认 true。仅在开启 setting 时有意义。
  • 顶部 重置 恢复初始展示、固定与顺序。
  • 列设置入口默认 关闭，传 setting: true 可开启。
  • 源列 fixed: 'right'（如操作列）或 disableInSetting: true：勾选禁用，且不展示 Pin 按钮。
  • 列上可配置 hideInSetting（不在面板展示）。
vue
<ProTable
  :options="{
    columnPin: false, // 仅隐藏「固定列首 / 列尾」Pin，保留勾选与「不固定」
  }"
/>

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

No Data
Total 0
  • 1
Go to

行多选 rowSelection ​

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

详见下文 行选择配置 ProTableRowSelection。

布局与插槽 ​

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

  • actions：左侧主操作，如「新增」、更多下拉（见 基础用法 示例）。
  • toolBar：右侧工具区；未自定义时内置刷新、密度、列设置（由 options 控制）。
  • empty：表格空状态内容；未自定义时展示 tableProps.emptyText 或默认空文案。
  • 列插槽：列配置 columnSlot（如 actions）对应 #column-{columnSlot}，作用域与 UTableColumn 默认插槽一致。
  • 查询插槽：列配置 searchSlot（如 country）对应 #search-{searchSlot}，用于自定义单个查询字段控件。

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

实例方法 ​

在组件上使用 ref 可调用：reload、resetSearch、reloadAndReset、getSelectionRows、clearSelection、getColumnOrder、getColumnSettingState；tableRef 为底层 UTable 实例。

useProTableRequest 与工具函数 ​

若只需「查询 + 分页 + request」逻辑并自行拼接 UI，可使用 useProTableRequest（与 ProTable 内部同源），入参包含 columns 工厂函数、request、manual、defaultPageSize、beforeSearchSubmit、postData 等。

getColumnKey(col) 读取 key ?? prop（缺失时抛错）；getColumnTitle(col) 读取 title ?? label ?? 字段名。

开发与联调 ​

在 uniboot-ui 根目录执行 pnpm dev 或可使用 pnpm dev（或 play 配置）对 ProTable 做热更新调试；安装依赖需能解析 uniboot-ui 与 @uniboot/* 所用 registry（见 开发指南）。

ProTable API ​

ProTable 属性 ​

名称说明类型默认值
data表格数据源array[]
loading是否显示加载状态booleanfalse
total列表总条数number0
rowKey行主键字段名，与 UTable 一致，必填string—
defaultPageSize默认每页条数；若 pagination 为对象且含 defaultPageSize 则以后者为准number10
headerTitle工具栏左侧标题（与 title 二选一，本属性优先）string—
title同 headerTitle，未设置 headerTitle 时使用string—
searchfalse 关闭查询区；true 使用默认；对象见 查询配置boolean / objecttrue
showToolbar是否展示标题栏 / 工具栏区域booleantrue
showReload是否展示内置「刷新」（可被 options 覆盖）booleantrue
searchButtonText查询按钮文案string查询
resetButtonText重置按钮文案string重置
rowSelection行多选配置，见 行选择配置object—
paginationLayout透传 UPagination 的 layoutstringtotal, sizes, prev, pager, next, jumper
paginationfalse 隐藏分页条；true 或对象见 分页配置boolean / objecttrue
optionsfalse 关闭内置工具；对象见 工具栏配置boolean / object默认仅开启列设置拖拽排序；刷新 / 密度 / 列设置需显式配置
density表格密度，与工具栏选项一致并映射到底层 UTable 的 sizeenumdefault
showOverflowTooltip表格级超长省略，为 true 时所有列默认开启；列上 showOverflowTooltip / ellipsis 可单独覆盖，透传 UTable 同名属性boolean / object（同 Table）—
empty-cell-text单元格值为空（null / undefined / ''）时的占位文案，透传 UTable 同名属性；列上可单独覆盖string—
tableProps透传给 UTable 的额外 propsobjectobject
request远程数据请求Function—
params额外请求参数，优先级高于查询表单；变更时重新请求object—
manual为 true 时不自动发起首屏请求booleanfalse

ProTable 事件 ​

事件名说明类型
search提交查询，传递最新的 query 表单值Function
reset查询表单被重置Function
reload点击内置刷新按钮时触发Function
paginationChange分页发生改变（当前页或每页条数）Function
columnsOrderChange列展示状态变化（顺序、固定、显隐）Function

ProTable 插槽 ​

名称位置说明
tip查询区上方列表说明、告警等；未使用时不渲染
actions工具栏左侧主操作按钮区，需自行实现新建、更多等
toolBar工具栏右侧替换内置刷新 / 密度 / 列设置；未使用时展示 options 内置按钮
empty表格空状态自定义空状态内容；未使用时展示 tableProps.emptyText 或默认空文案
footer分页下方表格底栏扩展内容
column-表格列由列配置 columnSlot 决定，如 columnSlot: 'actions' → #column-actions
search-查询表单项由列配置 searchSlot 决定，如 searchSlot: 'country' → #search-country

ProTable 暴露 ​

名称说明类型
reload按当前分页与查询重新请求Function
fetchData发起远程请求（仅 request 模式）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各列是否勾选显示

列配置 ProTableColumn ​

名称说明类型默认值
key列字段，与 prop 二选一至少填其一；同时存在时以本字段为准string—
prop列字段（Element 习惯）string—
title列标题，与 label 二选一string—
label列标题 / 表单项 labelstring—
width列宽string / number—
minWidth最小列宽string / number—
fixed固定列boolean / enum—
align对齐方式enum—
ellipsis为 true 时等价开启超长省略；未设置时继承表格级 showOverflowTooltipboolean—
showOverflowTooltip是否超长省略并 tooltip；未设置时继承表格级 showOverflowTooltipboolean—
empty-cell-text空单元格占位文案；未设置时继承 ProTable / UTable 的 empty-cell-textstring—
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—
optionsvalueType 为 select 时的选项array—
placeholder查询控件占位符string—
columnSlot自定义列插槽名，如 action 对应 #column-actionstring—
searchSlot自定义查询表单项插槽名，如 country 对应 #search-country 0.1.9string—

查询配置 ProTableSearchConfig ​

名称说明类型默认值
defaultCollapsed默认是否收起更多筛选项；为 true 时只展示首行容量内的筛选项booleantrue
labelWidth查询表单项 label 宽度，如 72 或 '80px'；未设置时 ProTable 用 72pxstring / number72px
span保留字段；当前 QueryFilter 按容器宽度自动计算 4 / 3 / 2 / 1 列布局number—

分页配置 ProTablePaginationConfig ​

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

工具栏配置 ProTableOptions ​

options: false 时关闭全部内置工具栏能力；传入对象时会与内置默认值合并，传 true 可单独开启某项。

名称说明类型默认值
reload是否显示刷新按钮（靠右）booleanfalse
reloadIcon刷新按钮图标，默认 Refresh2ComponentRefresh2
density是否显示密度下拉（宽松 / 默认 / 紧凑，映射 UTable 的 size）booleanfalse
densityIcon密度按钮图标，默认 HeightComponentHeight
setting是否显示列设置（表头筛选）；勾选后即时生效booleanfalse
settingIcon列设置按钮图标，默认 AdjustComponentAdjust
columnPin列设置中是否显示「固定列首 / 固定列尾」Pin 按钮；false 时仅隐藏 Pin，保留勾选与「不固定」booleantrue
columnDrag是否允许在列设置面板中通过拖拽调整列顺序booleantrue

行选择配置 ProTableRowSelection ​

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