v-pro-table
v0.1.3
Published
基于 VXE Table 与 Element Plus 的 Vue 3 高级表格组件
Maintainers
Readme
v-pro-table
基于 VXE Table 和 Element Plus 的 Vue 3 表格组件。内置吸顶、搜索、分页、序号、状态标签、数量标签、附件、操作按钮和单元格编辑。
只提供 ESM。
安装
pnpm add v-pro-table
pnpm add vue element-plus vxe-table vxe-pc-uivue、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。
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,以及搜索字段。
<script setup lang="ts">
import { ProTable, type ProTableColumnType } from "v-pro-table";
interface Row {
id: number;
name: string;
status: number;
}
const columns: ProTableColumnType<Row>[] = [
{
field: "name",
title: "名称",
minWidth: 160,
search: {
type: "input",
bind: { placeholder: "搜索名称", clearable: true }
}
},
{
field: "status",
title: "状态",
width: 120,
renderType: "status",
statusConfig: {
statusMap: {
1: { text: "待处理", type: "warning" },
2: { text: "已完成", type: "success" }
}
}
}
];
async function fetchData(params: Record<string, unknown>) {
return {
data: [{ id: 1, name: "示例", status: 1 }],
pagination: {
page: Number(params.page ?? 1),
page_size: Number(params.page_size ?? 20),
total: 1
}
};
}
</script>
<template>
<ProTable
:columns="columns"
:api="fetchData"
show-search
:pagination="{ pageSize: 20, showWhenTotal: 1 }"
/>
</template>本地示例在 playground/。仓库内执行 pnpm dev 后打开开发服务器即可查看搜索、分页、状态、标签和附件列。
数据约定
interface ProTableListResponse<T> {
data?: T[];
pagination?: {
page?: number;
page_size?: number;
total?: number;
};
}也可以不传 api,用 v-model:data 传入表格数据。这种手动模式下,刷新只会复用当前数据。
常用属性
| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| columns | ProTableColumnType[] | — | 列配置 |
| api | (params) => Promise<ProTableListResponse> | — | 列表请求 |
| v-model:data | T[] | — | 外部数据,传入后不再自动请求 |
| requestAuto | boolean | true | 挂载后是否自动请求 |
| initParams | Record<string, unknown> | — | 每次请求附带的固定参数 |
| 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 时,会调用注入的预览方法:
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。
本地开发
pnpm install
pnpm dev
pnpm buildpnpm build 产物在 dist/:index.js、index.d.ts、style.css。发布前会自动执行构建。
许可
MIT
