Vben Vxe Table
Vben Vxe Table wraps vxe-table together with Vben Form so you can build searchable data grids with a shared API.
Adapter Example
The current renderer adapter uses renderTableDefault(...) for table cell rendering:
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 },
);
},
});Basic Usage
<script setup lang="ts">
import { useVbenVxeGrid } from '#/adapter/vxe-table';
const [Grid, gridApi] = useVbenVxeGrid({
gridOptions: {},
formOptions: {},
gridEvents: {},
});
</script>
<template>
<Grid />
</template><script lang="ts" setup>
import type { VxeGridListeners, VxeGridProps } from '#/adapter/vxe-table';
import { Button, message } from 'antdv-next';
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>Search Form Separator & Segmented Layout
When a search form is enabled, a separator is rendered between the form and the table body by default. Customize or disable it with separator:
const [Grid] = useVbenVxeGrid({
formOptions: {},
gridOptions: {},
separator: false,
// separator: { show: false },
// separator: { backgroundColor: 'rgba(100,100,0,0.5)' },
// separator: { class: 'my-2 h-px rounded-full bg-primary/40' },
});The separator is a decorative in-flow element. Styles compose in the order preset class → user class → backgroundColor → user style. The default band uses h-2 (8px) at every breakpoint and has no vertical margins. separator.fullBleed (default true in the default mode) extends the separator across the vxe-grid padding; the bleed width is measured from the actual padding, so gridClass changes (e.g. p-2 → p-3) and fullscreen are handled automatically.
Segmented Layout
segmented splits the search form and the table body into two sections with independently customizable radius and background:
| Mode | Appearance | Upper section | Lower section | Separator |
|---|---|---|---|---|
false (default) | legacy full-bleed band | transparent form area | the card itself | full-bleed band |
zone | one card, two zones | rounded in-card panel (background-deep) | the card itself | hidden by default; 1px hairline when enabled |
card | two separate cards | standalone rounded card (card background) | standalone rounded card | hidden by default, cards separated by gap |
const [Grid, gridApi] = useVbenVxeGrid({
formOptions: {},
gridOptions: {},
segmented: 'zone',
// segmented: 'card',
// sectionOptions: {
// body: { borderRadius: '12px' },
// form: { borderRadius: '12px' },
// gap: '12px',
// },
});
// Switch at runtime (or pass as props to <Grid>)
gridApi.setState({ segmented: 'card' });Companion props:
sectionOptions: the single entry for section surfaces.form/bodyonly exposebackgroundColorandborderRadius(vertical padding/border/margin are deliberately not exposed — they are not covered by vxe's height calculation);gapis the two-card spacing (CSS length, defaults to0.5rem, negatives rejected);fullscreenBackgroundColoris the root background when a two-card grid is maximized (defaults tobackground-deep).formClass: class for the outer form surface (padding, background and radius), merged after the mode preset and also applied to a customformslot. It targets a different element fromformOptions.wrapperClass(field grid columns/gaps),commonConfig.formItemClass(fields), andactionWrapperClass(actions).- Separator visibility in segmented modes:
false/truedecides directly; an object usesshowwhen present; otherwise the mode default applies (the band is only shown by default in the default mode — thezonepanel edge and thecardlayout already separate the sections, and an extra hairline would double the table header's own border line). When explicitly enabled incardmode, the separator zone addsgap / 2padding above and below the line; the card gap and the separator visibility are independent concerns. The separator has no vertical margins. Compact grid search forms use an 8px row gap instead of trailing field/action padding. Surfaces own the edge spacing: the default grid supplies the top/side inset and the form surface supplies the bottom inset; zone/card surfaces use 8px on all sides. Standalone forms retain their default spacing, andcompact: falseretains the 16px field space reserved for validation messages.
Section radii follow the theme var(--radius) by default.
Two-card body padding: the grid root has no padding, so both cards occupy the same outer bounds as other modes. The lower card carries a default 0.5rem inset, including when the toolbar or pager is absent. Override --vben-grid-body-padding on any ancestor element to adjust it, or per instance via the gridClass arbitrary-property syntax:
// global (any ancestor CSS)
:root { --vben-grid-body-padding: 12px; }
// per instance
useVbenVxeGrid({ gridOptions: {}, segmented: 'card', gridClass: '[--vben-grid-body-padding:12px]' });Do not add vertical padding to the body wrapper to adjust the top/bottom inset — it is not covered by vxe's auto height calculation and will overflow or clip the table. The toolbar or
Topwrapper supplies the top inset, and the pager orBottomwrapper supplies the bottom inset. These wrappers are included in VXE'soffsetHeightmeasurements. The default/zone modes also useTopto leave 8px between the band/panel and the table when no toolbar is rendered. Customlayoutsthat omitTop/Bottomalso omit those fallback insets. The pager follows its content height (at least 28px), avoiding the extra space from the native mini fixed height.
Layout Constraints
zone / card modes (or an explicit sectionOptions.body) validate the effective layouts (after merging global vxe config):
- the header contains only
Form; - the body contains exactly one
Table;Toolbar/Top/Bottom/Pagermay be trimmed or reordered; - the footer is empty, and
Formmust not appear in the body.
Violations are reported as explicit console errors — disable segmented mode or adjust layouts. The pager is never moved silently. When only using the default separator feature, layouts passthrough keeps working as before.
Size Changes
Layout-affecting changes (search form toggle, form collapse/expand, mode or config switches, validation messages) automatically trigger grid.recalculate(true); the full-bleed width is re-measured on gridClass, fullscreen, and breakpoint changes. No manual recalculation or grid rebuild is required.
GridApi
| Method | Description | Type |
|---|---|---|
setLoading | update loading state | (loading: boolean) => void |
setGridOptions | merge new grid options | (options: Partial<VxeGridProps['gridOptions']>) => void |
reload | reload data and reset pagination | (params?: Record<string, any>) => void |
query | query data while keeping the current page | (params?: Record<string, any>) => void |
grid | vxe-grid instance | VxeGridInstance |
formApi | search form API | FormApi |
toggleSearchForm | toggle or force the search form visible state | (show?: boolean) => boolean |
Props
| Prop | Description | Type |
|---|---|---|
tableTitle | table title | string |
tableTitleHelp | help text for the table title | string |
class | class for the outer container | string |
gridClass | class for the vxe-grid node | string |
gridOptions | vxe-grid options | DeepPartial<VxeTableGridOptions> |
gridEvents | vxe-grid event handlers | DeepPartial<VxeGridListeners> |
formOptions | search form options | VbenFormProps |
showSearchForm | whether the search form is visible | boolean |
separator | separator between the search form and table body | boolean | SeparatorOptions |
segmented | segmented layout mode (false / zone / card) | false | 'card' | 'zone' |
sectionOptions | section surfaces (background/radius for both sections, card gap, fullscreen background) | GridSectionOptions |
formClass | class for the form surface (upper section) | ClassType |
Slots
| Slot | Description |
|---|---|
toolbar-actions | left side of the toolbar, near the title |
toolbar-tools | right side of the toolbar, before built-in tool buttons |
table-title | custom table title |
All named slots starting with form- are forwarded to the search form.

dream-weave
xingyu4j