# v-pro-table **Repository Path**: sun_yingbo/v-pro-table ## Basic Information - **Project Name**: v-pro-table - **Description**: 基于 VXE Table 和 Element Plus 的 Vue 3 表格组件。内置吸顶、搜索、分页、序号、状态标签、数量标签、附件、操作按钮和单元格编辑。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-27 - **Last Updated**: 2026-10-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # v-pro-table 基于 [VXE Table](https://vxetable.cn/) 和 [Element Plus](https://element-plus.org/) 的 Vue 3 表格组件。内置吸顶、搜索、分页、序号、状态标签、数量标签、附件、操作按钮和单元格编辑。 只提供 ESM。 ## 安装 ```bash pnpm add v-pro-table pnpm add vue element-plus vxe-table vxe-pc-ui ``` `vue`、`element-plus`、`vxe-table`、`vxe-pc-ui` 是 peer 依赖,需要由使用方安装并注册。`@element-plus/icons-vue`、`@vueuse/core`、`es-toolkit` 会随本包安装。 | 依赖 | 版本 | | --- | --- | | vue | ^3.5.0 | | element-plus | ^2.11.0 | | vxe-table | ^4.18.0 | | vxe-pc-ui | ^4.15.0 | ## 注册 在应用入口注册 Element Plus 和 VXE Table,并单独引入本包样式。构建工具不会自动带上这份 CSS。 ```ts import { createApp } from "vue"; import ElementPlus from "element-plus"; import "element-plus/dist/index.css"; import VxeUIBase from "vxe-pc-ui"; import "vxe-pc-ui/es/style.css"; import VxeUITable from "vxe-table"; import "vxe-table/es/style.css"; import "v-pro-table/style.css"; import App from "./App.vue"; createApp(App).use(ElementPlus).use(VxeUIBase).use(VxeUITable).mount("#app"); ``` ## 示例 `api` 返回 `{ data, pagination }`。请求参数里带有 `page`、`page_size`,以及搜索字段。 ```vue ``` 本地示例在 `playground/`。仓库内执行 `pnpm dev` 后打开开发服务器即可查看搜索、分页、状态、标签和附件列。 ## 数据约定 ```ts interface ProTableListResponse { data?: T[]; pagination?: { page?: number; page_size?: number; total?: number; }; } ``` 也可以不传 `api`,用 `v-model:data` 传入表格数据。这种手动模式下,刷新只会复用当前数据。 ## 常用属性 | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `columns` | `ProTableColumnType[]` | — | 列配置 | | `api` | `(params) => Promise` | — | 列表请求 | | `v-model:data` | `T[]` | — | 外部数据,传入后不再自动请求 | | `requestAuto` | `boolean` | `true` | 挂载后是否自动请求 | | `initParams` | `Record` | — | 每次请求附带的固定参数 | | `beforeRequest` | `(params) => params` | — | 发请求前改写参数 | | `afterResponse` | `(data) => data` | — | 写入表格前改写行数据 | | `showSearch` | `boolean` | `false` | 显示搜索区 | | `searchAutoTrigger` | `boolean` | `false` | 输入框失焦、下拉和日期变更时自动查询 | | `showIndex` | `boolean` | `true` | 显示序号列 | | `showPagination` | `boolean` | `true` | 允许分页 | | `pagination` | `ProTablePaginationConfig` | — | `pageSize`、`pageSizes`、`layout`、`background`、`showWhenTotal` | | `sticky` | `boolean` | `false` | 表头吸顶 | | `stickyTop` | `number` | `0` | 吸顶后表头距离视口顶部的距离,单位 px。页面有固定顶栏时设成顶栏高度 | | `loading` | `boolean` | — | 外部加载状态,未传时使用内部请求状态 | | `gridOptions` | `VxeGridProps` | — | 透传给 `vxe-grid`,不要在这里写 `columns` 和 `data` | | `tableClass` | `string` | — | 加到表格上的类名 | `pagination.showWhenTotal` 默认是 `10`。总数小于该值时不显示分页器。 ## 列类型 普通列直接写 VXE 列字段。需要特殊渲染时设置 `renderType`: | `renderType` | 配置 | 作用 | | --- | --- | --- | | 不填 | `search` | 文本列。`search.type` 可以是 `input`、`select`、`date-picker`、`amount-range` | | `status` | `statusConfig` | 按 `statusMap` 渲染 Element Plus 标签 | | `tag` | `tagConfig` | 渲染数量标签,默认单位是「项」 | | `attachment` | `attachmentConfig` | 渲染文件列表。`multiline` 为 true 时,多文件折叠到「更多」 | | `editable` | `editableConfig` | 行内编辑,类型为 `input`、`number`、`percent`、`select` | | `operation` | `operationConfig` | 操作按钮。`icon` 使用内置名称:`Plus`、`Edit`、`Delete`、`View`、`Download`、`Upload`、`Search`、`Share`、`Refresh` | 搜索字段默认使用列的 `field`。需要换成别的请求参数名时,设置 `search.requestField`。金额区间可以用 `search.requestFields` 拆成两个参数。 ## 插槽 | 插槽 | 参数 | 说明 | | --- | --- | --- | | `search-right` | `model`、`search`、`reset` | 搜索区右侧内容。传入后,默认搜索和重置按钮让出位置 | | `empty` | — | 空数据 | | `seq` | `row`、`index` | 自定义序号 | | `operation` | `row` | 自定义操作列 | | `status-approver` | `row`、`config`、`statusConfig`、`businessId` | 状态列配置了 `nextApprover` 时,用这个插槽渲染审批人 | | 列 `field` 同名插槽 | `row`、`column` | 覆盖对应列的默认渲染 | | `groupContent` | VXE 分组参数 | 分组行内容 | ## 实例方法 通过模板 ref 调用: | 方法 | 说明 | | --- | --- | | `refresh(resetPage?)` | 重新请求。`resetPage` 为 true 时回到第一页 | | `reset()` | 清空搜索条件并重新请求 | | `search(params?)` | 按给定条件查询 | | `getCheckboxRecords()` | 当前勾选行 | | `clearCheckboxRow()` / `clearRadioRow()` | 清空勾选或单选 | | `setAllTreeExpand(expanded)` | 展开或收起全部树节点 | | `appendTreeRoot(row)` | 追加一级节点 | | `appendTreeChild(parentRow, row)` | 追加子节点 | | `removeTreeSubtree(target)` | 删除节点及其子节点 | `gridRef` 是 VXE Grid 实例,`searchFormModel` 是当前搜索表单。 ## 注入 附件列没有 `onClick` 时,会调用注入的预览方法: ```ts import { FILE_PREVIEW_CONTEXT_KEY } from "v-pro-table"; provide(FILE_PREVIEW_CONTEXT_KEY, { previewFile(fileId: string) { console.log(fileId); } }); ``` 状态列点击后,如果列配置了 `approvalHistory` 且没有 `onClick`,会调用 `APPROVAL_HISTORY_CONTEXT_KEY` 里的 `openApprovalHistory`。 ## 本地开发 ```bash pnpm install pnpm dev pnpm build ``` `pnpm build` 产物在 `dist/`:`index.js`、`index.d.ts`、`style.css`。发布前会自动执行构建。 ## 许可 MIT