# 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