2024-10-13 18:33:43 +08:00
|
|
|
|
---
|
|
|
|
|
outline: deep
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Vben Vxe Table 表格
|
|
|
|
|
|
2024-11-06 21:44:02 +08:00
|
|
|
|
框架提供的Table 列表组件基于 [vxe-table](https://vxetable.cn/v4/#/grid/api?apiKey=grid),结合`Vben Form 表单`进行了二次封装。
|
|
|
|
|
|
|
|
|
|
其中,表头的 **表单搜索** 部分采用了`Vben Form表单`,表格主体部分使用了`vxe-grid`组件,支持表格的分页、排序、筛选等功能。
|
|
|
|
|
|
|
|
|
|
> 如果文档内没有参数说明,可以尝试在在线示例或者在 [vxe-grid 官方API 文档](https://vxetable.cn/v4/#/grid/api?apiKey=grid) 内寻找
|
|
|
|
|
|
|
|
|
|
::: info 写在前面
|
|
|
|
|
|
|
|
|
|
如果你觉得现有组件的封装不够理想,或者不完全符合你的需求,大可以直接使用原生组件,亦或亲手封装一个适合的组件。框架提供的组件并非束缚,使用与否,完全取决于你的需求与自由。
|
|
|
|
|
|
|
|
|
|
:::
|
|
|
|
|
|
2024-11-06 23:03:33 +08:00
|
|
|
|
## 适配器
|
|
|
|
|
|
|
|
|
|
表格底层使用 [vxe-table](https://vxetable.cn/#/start/install) 进行实现,所以你可以使用 `vxe-table` 的所有功能。对于不同的 UI 框架,我们提供了适配器,以便更好的适配不同的 UI 框架。
|
|
|
|
|
|
|
|
|
|
### 适配器说明
|
|
|
|
|
|
|
|
|
|
每个应用都可以自己配置`vxe-table`的适配器,你可以根据自己的需求。下面是一个简单的配置示例:
|
|
|
|
|
|
|
|
|
|
::: details vxe-table 表格适配器
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
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: {
|
|
|
|
|
// 全局禁用vxe-table的表单配置,使用formOptions
|
|
|
|
|
enabled: false,
|
|
|
|
|
},
|
|
|
|
|
proxyConfig: {
|
|
|
|
|
autoLoad: true,
|
|
|
|
|
response: {
|
|
|
|
|
result: 'items',
|
|
|
|
|
total: 'total',
|
|
|
|
|
list: 'items',
|
|
|
|
|
},
|
|
|
|
|
showActiveMsg: true,
|
|
|
|
|
showResponseMsg: false,
|
|
|
|
|
},
|
|
|
|
|
round: true,
|
|
|
|
|
showOverflow: true,
|
|
|
|
|
size: 'small',
|
|
|
|
|
},
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// 表格配置项可以用 cellRender: { name: 'CellImage' },
|
|
|
|
|
vxeUI.renderer.add('CellImage', {
|
|
|
|
|
renderTableDefault(_renderOpts, params) {
|
|
|
|
|
const { column, row } = params;
|
|
|
|
|
return h(Image, { src: row[column.field] });
|
|
|
|
|
},
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// 表格配置项可以用 cellRender: { name: 'CellLink' },
|
|
|
|
|
vxeUI.renderer.add('CellLink', {
|
|
|
|
|
renderTableDefault(renderOpts) {
|
|
|
|
|
const { props } = renderOpts;
|
|
|
|
|
return h(
|
|
|
|
|
Button,
|
|
|
|
|
{ size: 'small', type: 'link' },
|
|
|
|
|
{ default: () => props?.text },
|
|
|
|
|
);
|
|
|
|
|
},
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// 这里可以自行扩展 vxe-table 的全局配置,比如自定义格式化
|
|
|
|
|
// vxeUI.formats.add
|
|
|
|
|
},
|
|
|
|
|
useVbenForm,
|
|
|
|
|
});
|
2024-11-06 21:44:02 +08:00
|
|
|
|
|
2024-11-06 23:03:33 +08:00
|
|
|
|
export { useVbenVxeGrid };
|
2024-11-06 21:44:02 +08:00
|
|
|
|
|
2024-11-06 23:03:33 +08:00
|
|
|
|
export type * from '@vben/plugins/vxe-table';
|
2024-11-06 21:44:02 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
## 基础表格
|
|
|
|
|
|
|
|
|
|
使用 `useVbenVxeGrid` 创建最基础的表格。
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/basic" />
|
|
|
|
|
|
|
|
|
|
## 远程加载
|
|
|
|
|
|
|
|
|
|
通过指定 `proxyConfig.ajax` 的 `query` 方法,可以实现远程加载数据。
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/remote" />
|
|
|
|
|
|
|
|
|
|
## 树形表格
|
|
|
|
|
|
2024-11-07 21:55:20 +08:00
|
|
|
|
树形表格的数据源为扁平结构,可以指定`treeConfig`配置项,实现树形表格。
|
2024-11-06 21:44:02 +08:00
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
treeConfig: {
|
|
|
|
|
transform: true, // 指定表格为树形表格
|
|
|
|
|
parentField: 'parentId', // 父节点字段名
|
|
|
|
|
rowField: 'id', // 行数据字段名
|
|
|
|
|
},
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/tree" />
|
|
|
|
|
|
|
|
|
|
## 固定表头/列
|
|
|
|
|
|
|
|
|
|
列固定可选参数: `'left' | 'right' | '' | null`
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/fixed" />
|
|
|
|
|
|
|
|
|
|
## 自定义单元格
|
|
|
|
|
|
|
|
|
|
自定义单元格有两种实现方式
|
|
|
|
|
|
|
|
|
|
- 通过 `slots` 插槽
|
|
|
|
|
- 通过 `customCell` 自定义单元格,但是要先添加渲染器
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
// 表格配置项可以用 cellRender: { name: 'CellImage' },
|
|
|
|
|
vxeUI.renderer.add('CellImage', {
|
|
|
|
|
renderDefault(_renderOpts, params) {
|
|
|
|
|
const { column, row } = params;
|
|
|
|
|
return h(Image, { src: row[column.field] } as any); // 注意此处的Image 组件,来源于Antd,需要自行引入,否则会使用js的Image类
|
|
|
|
|
},
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// 表格配置项可以用 cellRender: { name: 'CellLink' },
|
|
|
|
|
vxeUI.renderer.add('CellLink', {
|
|
|
|
|
renderDefault(renderOpts) {
|
|
|
|
|
const { props } = renderOpts;
|
|
|
|
|
return h(
|
|
|
|
|
Button,
|
|
|
|
|
{ size: 'small', type: 'link' },
|
|
|
|
|
{ default: () => props?.text },
|
|
|
|
|
);
|
|
|
|
|
},
|
|
|
|
|
});
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/custom-cell" />
|
|
|
|
|
|
|
|
|
|
## 搜索表单
|
|
|
|
|
|
|
|
|
|
**表单搜索** 部分采用了`Vben Form 表单`,参考 [Vben Form 表单文档](/components/common-ui/vben-form)。
|
|
|
|
|
|
2024-12-12 22:28:03 +08:00
|
|
|
|
当启用了表单搜索时,可以在toolbarConfig中配置`search`为`true`来让表格在工具栏区域显示一个搜索表单控制按钮。
|
|
|
|
|
|
2024-11-06 21:44:02 +08:00
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/form" />
|
|
|
|
|
|
|
|
|
|
## 单元格编辑
|
|
|
|
|
|
|
|
|
|
通过指定`editConfig.mode`为`cell`,可以实现单元格编辑。
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/edit-cell" />
|
|
|
|
|
|
|
|
|
|
## 行编辑
|
|
|
|
|
|
|
|
|
|
通过指定`editConfig.mode`为`row`,可以实现行编辑。
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/edit-row" />
|
|
|
|
|
|
|
|
|
|
## 虚拟滚动
|
|
|
|
|
|
|
|
|
|
通过 scroll-y.enabled 与 scroll-y.gt 组合开启,其中 enabled 为总开关,gt 是指当总行数大于指定行数时自动开启。
|
|
|
|
|
|
|
|
|
|
> 参考 [vxe-table 官方文档 - 虚拟滚动](https://vxetable.cn/v4/#/component/grid/scroll/vertical)。
|
|
|
|
|
|
|
|
|
|
<DemoPreview dir="demos/vben-vxe-table/virtual" />
|
2024-11-06 23:03:33 +08:00
|
|
|
|
|
|
|
|
|
## API
|
|
|
|
|
|
|
|
|
|
`useVbenVxeGrid` 返回一个数组,第一个元素是表格组件,第二个元素是表格的方法。
|
|
|
|
|
|
|
|
|
|
```vue
|
|
|
|
|
<script setup lang="ts">
|
|
|
|
|
import { useVbenVxeGrid } from '#/adapter/vxe-table';
|
|
|
|
|
|
|
|
|
|
// Grid 为表格组件
|
|
|
|
|
// gridApi 为表格的方法
|
|
|
|
|
const [Grid, gridApi] = useVbenVxeGrid({
|
|
|
|
|
gridOptions: {},
|
|
|
|
|
formOptions: {},
|
|
|
|
|
gridEvents: {},
|
|
|
|
|
// 属性
|
|
|
|
|
// 事件
|
|
|
|
|
});
|
|
|
|
|
</script>
|
|
|
|
|
|
|
|
|
|
<template>
|
|
|
|
|
<Grid />
|
|
|
|
|
</template>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### GridApi
|
|
|
|
|
|
|
|
|
|
useVbenVxeGrid 返回的第二个参数,是一个对象,包含了一些表单的方法。
|
|
|
|
|
|
2024-12-12 22:28:03 +08:00
|
|
|
|
| 方法名 | 描述 | 类型 | 说明 |
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
| setLoading | 设置loading状态 | `(loading)=>void` | - |
|
|
|
|
|
| setGridOptions | 设置vxe-table grid组件参数 | `(options: Partial<VxeGridProps['gridOptions'])=>void` | - |
|
|
|
|
|
| reload | 重载表格,会进行初始化 | `(params:any)=>void` | - |
|
|
|
|
|
| query | 重载表格,会保留当前分页 | `(params:any)=>void` | - |
|
|
|
|
|
| grid | vxe-table grid实例 | `VxeGridInstance` | - |
|
|
|
|
|
| formApi | vbenForm api实例 | `FormApi` | - |
|
|
|
|
|
| toggleSearchForm | 设置搜索表单显示状态 | `(show?: boolean)=>boolean` | 当省略参数时,则将表单在显示和隐藏两种状态之间切换 |
|
2024-11-06 23:03:33 +08:00
|
|
|
|
|
|
|
|
|
## Props
|
|
|
|
|
|
|
|
|
|
所有属性都可以传入 `useVbenVxeGrid` 的第一个参数中。
|
|
|
|
|
|
2025-03-01 22:12:15 +08:00
|
|
|
|
| 属性名 | 描述 | 类型 |
|
|
|
|
|
| -------------- | -------------------- | ------------------- |
|
|
|
|
|
| tableTitle | 表格标题 | `string` |
|
|
|
|
|
| tableTitleHelp | 表格标题帮助信息 | `string` |
|
|
|
|
|
| gridClass | grid组件的class | `string` |
|
|
|
|
|
| gridOptions | grid组件的参数 | `VxeTableGridProps` |
|
|
|
|
|
| gridEvents | grid组件的触发的事件 | `VxeGridListeners` |
|
|
|
|
|
| formOptions | 表单参数 | `VbenFormProps` |
|
|
|
|
|
| showSearchForm | 是否显示搜索表单 | `boolean` |
|
|
|
|
|
|
|
|
|
|
## Slots
|
|
|
|
|
|
|
|
|
|
大部分插槽的说明请参考 [vxe-table 官方文档](https://vxetable.cn/v4/#/grid/api),但工具栏部分由于做了一些定制封装,需使用以下插槽定制表格的工具栏:
|
|
|
|
|
|
|
|
|
|
| 插槽名 | 描述 |
|
|
|
|
|
| --------------- | -------------------------------------------- |
|
|
|
|
|
| toolbar-actions | 工具栏左侧部分(表格标题附近) |
|
|
|
|
|
| toolbar-tools | 工具栏右侧部分(vxeTable原生工具按钮的左侧) |
|
|
|
|
|
| table-title | 表格标题插槽 |
|