Vben Vxe Table 表格
Vben Vxe Table 基于 vxe-table 和 Vben Form 做了二次封装,用于构建带搜索表单的列表页面。
如果文档内没有覆盖到你需要的细节,可以结合在线示例和 vxe-grid 官方 API 一起查看。
写在前面
如果现有封装不满足你的场景,可以直接使用原生 vxe-table 能力,或者在适配层中继续扩展。:::
适配器
底层表格基于 vxe-table,每个应用都可以在自己的适配层中配置默认行为、自定义渲染器以及与 UI 组件库的集成。
适配器示例
vxe-table 表格适配器
import { h } from 'vue';
import { setupVbenVxeTable, useVbenVxeGrid } from '@vben/plugins/vxe-table';
import { Button, Image } from 'ant-design-vue';
import { useVbenForm } from './form';
setupVbenVxeTable({
configVxeTable: (vxeUI) => {
vxeUI.setConfig({
grid: {
align: 'center',
border: false,
columnConfig: {
resizable: true,
},
minHeight: 180,
formConfig: {
enabled: false,
},
proxyConfig: {
autoLoad: true,
response: {
result: 'items',
total: 'total',
list: 'items',
},
showActiveMsg: true,
showResponseMsg: false,
},
round: true,
showOverflow: true,
size: 'small',
},
});
vxeUI.renderer.add('CellImage', {
renderTableDefault(_renderOpts, params) {
const { column, row } = params;
return h(Image, { src: row[column.field] });
},
});
vxeUI.renderer.add('CellLink', {
renderTableDefault(renderOpts) {
const { props } = renderOpts;
return h(
Button,
{ size: 'small', type: 'link' },
{ default: () => props?.text },
);
},
});
},
useVbenForm,
});
export { useVbenVxeGrid };
export type * from '@vben/plugins/vxe-table';基础表格
通过 useVbenVxeGrid 创建一个基础表格。
<script lang="ts" setup>
import type { VxeGridListeners, VxeGridProps } from '#/adapter/vxe-table';
import { Button, message } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { MOCK_TABLE_DATA } from '../table-data';
interface RowType {
address: string;
age: number;
id: number;
name: string;
nickname: string;
role: string;
}
const gridOptions: VxeGridProps<RowType> = {
columns: [
{ title: '序号', type: 'seq', width: 50 },
{ field: 'name', title: 'Name' },
{ field: 'age', sortable: true, title: 'Age' },
{ field: 'nickname', title: 'Nickname' },
{ field: 'role', title: 'Role' },
{ field: 'address', showOverflow: true, title: 'Address' },
],
data: MOCK_TABLE_DATA,
pagerConfig: {
enabled: false,
},
sortConfig: {
multiple: true,
},
};
const gridEvents: VxeGridListeners<RowType> = {
cellClick: ({ row }) => {
message.info(`cell-click: ${row.name}`);
},
};
const [Grid, gridApi] = useVbenVxeGrid({ gridEvents, gridOptions });
const showBorder = gridApi.useStore((state) => state.gridOptions?.border);
const showStripe = gridApi.useStore((state) => state.gridOptions?.stripe);
function changeBorder() {
gridApi.setGridOptions({
border: !showBorder.value,
});
}
function changeStripe() {
gridApi.setGridOptions({
stripe: !showStripe.value,
});
}
function changeLoading() {
gridApi.setLoading(true);
setTimeout(() => {
gridApi.setLoading(false);
}, 2000);
}
</script>
<template>
<!-- 此处的`vp-raw` 是为了适配文档的展示效果,实际使用时不需要 -->
<div class="vp-raw w-full">
<Grid>
<template #toolbar-tools>
<Button class="mr-2" type="primary" @click="changeBorder">
{{ showBorder ? '隐藏' : '显示' }}边框
</Button>
<Button class="mr-2" type="primary" @click="changeLoading">
显示loading
</Button>
<Button class="mr-2" type="primary" @click="changeStripe">
{{ showStripe ? '隐藏' : '显示' }}斑马纹
</Button>
</template>
</Grid>
</div>
</template>远程加载
通过配置 proxyConfig.ajax.query 实现远程数据加载。
<script lang="ts" setup>
import type { DemoTableApi } from '../mock-api';
import type { VxeGridProps } from '#/adapter/vxe-table';
import { Button } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { MOCK_API_DATA } from '../table-data';
interface RowType {
category: string;
color: string;
id: string;
price: string;
productName: string;
releaseDate: string;
}
// 数据实例
// const MOCK_TREE_TABLE_DATA = [
// {
// date: '2020-08-01',
// id: 10_000,
// name: 'Test1',
// parentId: null,
// size: 1024,
// type: 'mp3',
// },
// ]
const sleep = (time = 1000) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, time);
});
};
/**
* 获取示例表格数据
*/
async function getExampleTableApi(params: DemoTableApi.PageFetchParams) {
return new Promise<{ items: any; total: number }>((resolve) => {
const { page, pageSize } = params;
const items = MOCK_API_DATA.slice((page - 1) * pageSize, page * pageSize);
sleep(1000).then(() => {
resolve({
total: items.length,
items,
});
});
});
}
const gridOptions: VxeGridProps<RowType> = {
checkboxConfig: {
highlight: true,
labelField: 'name',
},
columns: [
{ title: '序号', type: 'seq', width: 50 },
{ align: 'left', title: 'Name', type: 'checkbox', width: 100 },
{ field: 'category', title: 'Category' },
{ field: 'color', title: 'Color' },
{ field: 'productName', title: 'Product Name' },
{ field: 'price', title: 'Price' },
{ field: 'releaseDate', formatter: 'formatDateTime', title: 'DateTime' },
],
exportConfig: {},
// height: 'auto', // 如果设置为 auto,则必须确保存在父节点且不允许存在相邻元素,否则会出现高度闪动问题
keepSource: true,
proxyConfig: {
ajax: {
query: async ({ page }) => {
return await getExampleTableApi({
page: page.currentPage,
pageSize: page.pageSize,
});
},
},
},
toolbarConfig: {
custom: true,
export: true,
// import: true,
refresh: true,
zoom: true,
},
};
const [Grid, gridApi] = useVbenVxeGrid({
gridOptions,
});
</script>
<template>
<div class="vp-raw w-full">
<Grid>
<template #toolbar-tools>
<Button class="mr-2" type="primary" @click="() => gridApi.query()">
刷新当前页面
</Button>
<Button type="primary" @click="() => gridApi.reload()">
刷新并返回第一页
</Button>
</template>
</Grid>
</div>
</template>树形表格
树形表格的数据源通常是扁平结构,可以通过 treeConfig 转换为树形展示。
treeConfig: {
transform: true,
parentField: 'parentId',
rowField: 'id',
},<script lang="ts" setup>
import type { VxeGridProps } from '#/adapter/vxe-table';
import { Button } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { MOCK_TREE_TABLE_DATA } from '../table-data';
interface RowType {
date: string;
id: number;
name: string;
parentId: null | number;
size: number;
type: string;
}
// 数据实例
// const MOCK_TREE_TABLE_DATA = [
// {
// date: '2020-08-01',
// id: 10_000,
// name: 'Test1',
// parentId: null,
// size: 1024,
// type: 'mp3',
// },
// {
// date: '2021-04-01',
// id: 10_050,
// name: 'Test2',
// parentId: 10_000,
// size: 0,
// type: 'mp4',
// },
// ];
const gridOptions: VxeGridProps<RowType> = {
columns: [
{ type: 'seq', width: 70 },
{ field: 'name', minWidth: 300, title: 'Name', treeNode: true },
{ field: 'size', title: 'Size' },
{ field: 'type', title: 'Type' },
{ field: 'date', title: 'Date' },
],
data: MOCK_TREE_TABLE_DATA,
pagerConfig: {
enabled: false,
},
treeConfig: {
parentField: 'parentId',
rowField: 'id',
transform: true,
},
};
const [Grid, gridApi] = useVbenVxeGrid({ gridOptions });
const expandAll = () => {
gridApi.grid?.setAllTreeExpand(true);
};
const collapseAll = () => {
gridApi.grid?.setAllTreeExpand(false);
};
</script>
<template>
<div class="vp-raw h-75 w-full">
<Grid>
<template #toolbar-tools>
<Button class="mr-2" type="primary" @click="expandAll">
展开全部
</Button>
<Button type="primary" @click="collapseAll"> 折叠全部 </Button>
</template>
</Grid>
</div>
</template>固定列
固定列可选值为 'left' | 'right' | '' | null。
<script lang="ts" setup>
import type { VxeGridProps } from '#/adapter/vxe-table';
import { Button } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { getExampleTableApi } from '../mock-api';
interface RowType {
category: string;
color: string;
id: string;
price: string;
productName: string;
releaseDate: string;
}
const gridOptions: VxeGridProps<RowType> = {
columns: [
{ fixed: 'left', title: '序号', type: 'seq', width: 50 },
{ field: 'category', title: 'Category', width: 300 },
{ field: 'color', title: 'Color', width: 300 },
{ field: 'productName', title: 'Product Name', width: 300 },
{ field: 'price', title: 'Price', width: 300 },
{
field: 'releaseDate',
formatter: 'formatDateTime',
title: 'DateTime',
width: 500,
},
{
field: 'action',
fixed: 'right',
slots: { default: 'action' },
title: '操作',
width: 120,
},
],
pagerConfig: {},
proxyConfig: {
ajax: {
query: async ({ page }) => {
return await getExampleTableApi({
page: page.currentPage,
pageSize: page.pageSize,
});
},
},
},
rowConfig: {
isHover: true,
},
};
const [Grid] = useVbenVxeGrid({ gridOptions });
</script>
<template>
<div class="vp-raw w-full">
<Grid>
<template #action>
<Button type="link">编辑</Button>
</template>
</Grid>
</div>
</template>自定义单元格
可以通过插槽或自定义渲染器实现单元格定制。
vxeUI.renderer.add('CellImage', {
renderTableDefault(_renderOpts, params) {
const { column, row } = params;
return h(Image, { src: row[column.field] } as any);
},
});
vxeUI.renderer.add('CellLink', {
renderTableDefault(renderOpts) {
const { props } = renderOpts;
return h(
Button,
{ size: 'small', type: 'link' },
{ default: () => props?.text },
);
},
});<script lang="ts" setup>
import type { VxeGridProps } from '#/adapter/vxe-table';
import { Button, Image, Switch, Tag } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { getExampleTableApi } from '../mock-api';
interface RowType {
category: string;
color: string;
id: string;
imageUrl: string;
open: boolean;
price: string;
productName: string;
releaseDate: string;
status: 'error' | 'success' | 'warning';
}
const gridOptions: VxeGridProps<RowType> = {
checkboxConfig: {
highlight: true,
labelField: 'name',
},
columns: [
{ title: '序号', type: 'seq', width: 50 },
{ field: 'category', title: 'Category', width: 100 },
{
field: 'imageUrl',
slots: { default: 'image-url' },
title: 'Image',
width: 100,
},
{
cellRender: { name: 'CellImage' },
field: 'imageUrl2',
title: 'Render Image',
width: 130,
},
{
field: 'open',
slots: { default: 'open' },
title: 'Open',
width: 100,
},
{
field: 'status',
slots: { default: 'status' },
title: 'Status',
width: 100,
},
{ field: 'color', title: 'Color', width: 100 },
{ field: 'productName', title: 'Product Name', width: 200 },
{ field: 'price', title: 'Price', width: 100 },
{
field: 'releaseDate',
formatter: 'formatDateTime',
title: 'Date',
width: 200,
},
{
cellRender: { name: 'CellLink', props: { text: '编辑' } },
field: 'action',
fixed: 'right',
title: '操作',
width: 120,
},
],
keepSource: true,
pagerConfig: {},
proxyConfig: {
ajax: {
query: async ({ page }) => {
return await getExampleTableApi({
page: page.currentPage,
pageSize: page.pageSize,
});
},
},
},
};
const [Grid] = useVbenVxeGrid({ gridOptions });
</script>
<template>
<div class="vp-raw w-full">
<Grid>
<template #image-url="{ row }">
<Image :src="row.imageUrl" height="30" width="30" />
</template>
<template #open="{ row }">
<Switch v-model="row.open" />
</template>
<template #status="{ row }">
<Tag :color="row.color">{{ row.status }}</Tag>
</template>
<template #action>
<Button type="link">编辑</Button>
</template>
</Grid>
</div>
</template>搜索表单
搜索区域底层使用的是 Vben Form。启用搜索表单后,可以通过 gridOptions.toolbarConfig.search = true 在工具栏中显示搜索面板开关按钮。
所有以 form- 开头的具名插槽都会自动转发到搜索表单。
自定义分隔条
启用搜索表单时,表单和表格主体之间默认会显示一个分隔条。可以通过 separator 调整或关闭它。
const [Grid] = useVbenVxeGrid({
formOptions: {},
gridOptions: {},
separator: false,
// separator: { show: false },
// separator: { backgroundColor: 'rgba(100,100,0,0.5)' },
});<script lang="ts" setup>
import type { VbenFormProps } from '#/adapter/form';
import type { VxeGridProps } from '#/adapter/vxe-table';
import { message } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { getExampleTableApi } from '../mock-api';
interface RowType {
category: string;
color: string;
id: string;
price: string;
productName: string;
releaseDate: string;
}
const formOptions: VbenFormProps = {
// 默认展开
collapsed: false,
schema: [
{
component: 'Input',
componentProps: {
placeholder: 'Please enter category',
},
defaultValue: '1',
fieldName: 'category',
label: 'Category',
},
{
component: 'Input',
componentProps: {
placeholder: 'Please enter productName',
},
fieldName: 'productName',
label: 'ProductName',
},
{
component: 'Input',
componentProps: {
placeholder: 'Please enter price',
},
fieldName: 'price',
label: 'Price',
},
{
component: 'Select',
componentProps: {
allowClear: true,
options: [
{
label: 'Color1',
value: '1',
},
{
label: 'Color2',
value: '2',
},
],
placeholder: '请选择',
},
fieldName: 'color',
label: 'Color',
},
{
component: 'DatePicker',
fieldName: 'datePicker',
label: 'Date',
},
],
// 控制表单是否显示折叠按钮
showCollapseButton: true,
submitButtonOptions: {
content: '查询',
},
// 是否在字段值改变时提交表单
submitOnChange: false,
// 按下回车时是否提交表单
submitOnEnter: false,
};
const gridOptions: VxeGridProps<RowType> = {
checkboxConfig: {
highlight: true,
labelField: 'name',
},
columns: [
{ title: '序号', type: 'seq', width: 50 },
{ align: 'left', title: 'Name', type: 'checkbox', width: 100 },
{ field: 'category', title: 'Category' },
{ field: 'color', title: 'Color' },
{ field: 'productName', title: 'Product Name' },
{ field: 'price', title: 'Price' },
{ field: 'releaseDate', formatter: 'formatDateTime', title: 'Date' },
],
keepSource: true,
pagerConfig: {},
proxyConfig: {
ajax: {
query: async ({ page }, formValues) => {
message.success(`Query params: ${JSON.stringify(formValues)}`);
return await getExampleTableApi({
page: page.currentPage,
pageSize: page.pageSize,
...formValues,
});
},
},
},
toolbarConfig: {
// 是否显示搜索表单控制按钮
// @ts-ignore - 正式环境时有完整的类型声明
search: true,
},
};
const [Grid] = useVbenVxeGrid({ formOptions, gridOptions });
</script>
<template>
<div class="vp-raw w-full">
<Grid />
</div>
</template>单元格编辑
通过设置 editConfig.mode = 'cell' 开启单元格编辑。
<script lang="ts" setup>
import type { VxeGridProps } from '#/adapter/vxe-table';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { getExampleTableApi } from '../mock-api';
interface RowType {
category: string;
color: string;
id: string;
price: string;
productName: string;
releaseDate: string;
}
const gridOptions: VxeGridProps<RowType> = {
columns: [
{ title: '序号', type: 'seq', width: 50 },
{ editRender: { name: 'input' }, field: 'category', title: 'Category' },
{ editRender: { name: 'input' }, field: 'color', title: 'Color' },
{
editRender: { name: 'input' },
field: 'productName',
title: 'Product Name',
},
{ field: 'price', title: 'Price' },
{ field: 'releaseDate', formatter: 'formatDateTime', title: 'Date' },
],
editConfig: {
mode: 'cell',
trigger: 'click',
},
pagerConfig: {},
proxyConfig: {
ajax: {
query: async ({ page }) => {
return await getExampleTableApi({
page: page.currentPage,
pageSize: page.pageSize,
});
},
},
},
showOverflow: true,
};
const [Grid] = useVbenVxeGrid({ gridOptions });
</script>
<template>
<div class="vp-raw w-full">
<Grid />
</div>
</template>行编辑
通过设置 editConfig.mode = 'row' 开启整行编辑。
<script lang="ts" setup>
import type { VxeGridProps } from '#/adapter/vxe-table';
import { Button, message } from 'ant-design-vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { getExampleTableApi } from '../mock-api';
interface RowType {
category: string;
color: string;
id: string;
price: string;
productName: string;
releaseDate: string;
}
const gridOptions: VxeGridProps<RowType> = {
columns: [
{ title: '序号', type: 'seq', width: 50 },
{ editRender: { name: 'input' }, field: 'category', title: 'Category' },
{ editRender: { name: 'input' }, field: 'color', title: 'Color' },
{
editRender: { name: 'input' },
field: 'productName',
title: 'Product Name',
},
{ field: 'price', title: 'Price' },
{ field: 'releaseDate', formatter: 'formatDateTime', title: 'Date' },
{ slots: { default: 'action' }, title: '操作' },
],
editConfig: {
mode: 'row',
trigger: 'click',
},
pagerConfig: {},
proxyConfig: {
ajax: {
query: async ({ page }) => {
return await getExampleTableApi({
page: page.currentPage,
pageSize: page.pageSize,
});
},
},
},
showOverflow: true,
};
const [Grid, gridApi] = useVbenVxeGrid({ gridOptions });
function hasEditStatus(row: RowType) {
return gridApi.grid?.isEditByRow(row);
}
function editRowEvent(row: RowType) {
gridApi.grid?.setEditRow(row);
}
async function saveRowEvent(row: RowType) {
await gridApi.grid?.clearEdit();
gridApi.setLoading(true);
setTimeout(() => {
gridApi.setLoading(false);
message.success({
content: `保存成功!category=${row.category}`,
});
}, 600);
}
const cancelRowEvent = (_row: RowType) => {
gridApi.grid?.clearEdit();
};
</script>
<template>
<div class="vp-raw w-full">
<Grid>
<template #action="{ row }">
<template v-if="hasEditStatus(row)">
<Button type="link" @click="saveRowEvent(row)">保存</Button>
<Button type="link" @click="cancelRowEvent(row)">取消</Button>
</template>
<template v-else>
<Button type="link" @click="editRowEvent(row)">编辑</Button>
</template>
</template>
</Grid>
</div>
</template>虚拟滚动
通过 scroll-y.enabled 和 scroll-y.gt 组合开启纵向虚拟滚动。
<script lang="ts" setup>
import type { VxeGridProps } from '#/adapter/vxe-table';
import { onMounted } from 'vue';
import { useVbenVxeGrid } from '#/adapter/vxe-table';
interface RowType {
id: number;
name: string;
role: string;
sex: string;
}
const gridOptions: VxeGridProps<RowType> = {
columns: [
{ type: 'seq', width: 70 },
{ field: 'name', title: 'Name' },
{ field: 'role', title: 'Role' },
{ field: 'sex', title: 'Sex' },
],
data: [],
height: 'auto',
pagerConfig: {
enabled: false,
},
scrollY: {
enabled: true,
gt: 0,
},
showOverflow: true,
};
const [Grid, gridApi] = useVbenVxeGrid({ gridOptions });
// 模拟行数据
const loadList = (size = 200) => {
try {
const dataList: RowType[] = [];
for (let i = 0; i < size; i++) {
dataList.push({
id: 10_000 + i,
name: `Test${i}`,
role: 'Developer',
sex: '男',
});
}
gridApi.setGridOptions({ data: dataList });
} catch (error) {
console.error('Failed to load data:', error);
// Implement user-friendly error handling
}
};
onMounted(() => {
loadList(1000);
});
</script>
<template>
<div class="vp-raw h-125 w-full">
<Grid />
</div>
</template>API
useVbenVxeGrid 返回一个数组,第一个元素是表格组件,第二个元素是表格 API。
<script setup lang="ts">
import { useVbenVxeGrid } from '#/adapter/vxe-table';
const [Grid, gridApi] = useVbenVxeGrid({
gridOptions: {},
formOptions: {},
gridEvents: {},
});
</script>
<template>
<Grid />
</template>GridApi
| 方法名 | 描述 | 类型 | 说明 |
|---|---|---|---|
| setLoading | 设置 loading 状态 | (loading: boolean) => void | - |
| setGridOptions | 更新 gridOptions | (options: Partial<VxeGridProps['gridOptions']>) => void | - |
| reload | 重新加载表格,并重置到初始分页 | (params?: Record<string, any>) => void | - |
| query | 重新查询表格,保留当前分页 | (params?: Record<string, any>) => void | - |
| grid | vxe-grid 实例 | VxeGridInstance | - |
| formApi | 搜索表单 API 实例 | FormApi | - |
| toggleSearchForm | 切换或指定搜索表单显示状态 | (show?: boolean) => boolean | 传入参数时强制设置;不传参数时在显示和隐藏之间切换,并返回当前状态 |
Props
所有属性都通过 useVbenVxeGrid 的第一个参数传入。
| 属性名 | 描述 | 类型 | 版本要求 |
|---|---|---|---|
| tableTitle | 表格标题 | string | - |
| tableTitleHelp | 表格标题帮助信息 | string | - |
| class | 外层容器的 class | string | - |
| gridClass | vxe-grid 的 class | string | - |
| gridOptions | vxe-grid 配置 | DeepPartial<VxeTableGridOptions> | - |
| gridEvents | vxe-grid 事件 | DeepPartial<VxeGridListeners> | - |
| formOptions | 搜索表单配置 | VbenFormProps | - |
| showSearchForm | 是否显示搜索表单 | boolean | - |
| separator | 搜索表单与表格主体之间的分隔条 | boolean | SeparatorOptions | >5.5.4 |
Slots
大部分插槽说明可参考 vxe-table 官方文档,这里列出封装层新增或约定的部分。
| 插槽名 | 描述 |
|---|---|
| toolbar-actions | 工具栏左侧区域,位于标题附近 |
| toolbar-tools | 工具栏右侧区域,位于内置工具按钮左侧 |
| table-title | 自定义表格标题 |

vben