perf: improve the usage documentation of vben-vxe-table (#4829)
* perf: improve the usage documentation of vben-vxe-table
This commit is contained in:
@@ -1,2 +0,0 @@
|
||||
export * from './form';
|
||||
export * from './vxe-table';
|
@@ -1 +1,70 @@
|
||||
import { h } from 'vue';
|
||||
|
||||
import { setupVbenVxeTable, useVbenVxeGrid } from '@vben/plugins/vxe-table';
|
||||
|
||||
import { Button, Image } from 'ant-design-vue';
|
||||
|
||||
import { useVbenForm } from './form';
|
||||
|
||||
if (!import.meta.env.SSR) {
|
||||
setupVbenVxeTable({
|
||||
configVxeTable: (vxeUI) => {
|
||||
vxeUI.setConfig({
|
||||
grid: {
|
||||
align: 'center',
|
||||
border: false,
|
||||
columnConfig: {
|
||||
resizable: true,
|
||||
},
|
||||
|
||||
formConfig: {
|
||||
// 全局禁用vxe-table的表单配置,使用formOptions
|
||||
enabled: false,
|
||||
},
|
||||
minHeight: 180,
|
||||
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,
|
||||
});
|
||||
}
|
||||
|
||||
export { useVbenVxeGrid };
|
||||
|
||||
export type * from '@vben/plugins/vxe-table';
|
||||
|
4
docs/src/_env/node/adapter/form.ts
Normal file
4
docs/src/_env/node/adapter/form.ts
Normal file
@@ -0,0 +1,4 @@
|
||||
export const useVbenForm = () => {};
|
||||
export const z = {};
|
||||
export type VbenFormSchema = any;
|
||||
export type VbenFormProps = any;
|
3
docs/src/_env/node/adapter/vxe-table.ts
Normal file
3
docs/src/_env/node/adapter/vxe-table.ts
Normal file
@@ -0,0 +1,3 @@
|
||||
export type * from '@vben/plugins/vxe-table';
|
||||
|
||||
export const useVbenVxeGrid = () => {};
|
@@ -16,12 +16,84 @@ outline: deep
|
||||
|
||||
:::
|
||||
|
||||
::: tip README
|
||||
## 适配器
|
||||
|
||||
下方示例代码中, 出现的 `inject<UseVbenVxeGrid>` 是为了适配文档内的示例,实际使用时直接从 `'@vben/plugins/vxe-table'` 引入即可。
|
||||
表格底层使用 [vxe-table](https://vxetable.cn/#/start/install) 进行实现,所以你可以使用 `vxe-table` 的所有功能。对于不同的 UI 框架,我们提供了适配器,以便更好的适配不同的 UI 框架。
|
||||
|
||||
```typescript
|
||||
import { useVbenVxeGrid } from '@vben/plugins/vxe-table';
|
||||
### 适配器说明
|
||||
|
||||
每个应用都可以自己配置`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,
|
||||
});
|
||||
|
||||
export { useVbenVxeGrid };
|
||||
|
||||
export type * from '@vben/plugins/vxe-table';
|
||||
```
|
||||
|
||||
:::
|
||||
@@ -114,3 +186,55 @@ vxeUI.renderer.add('CellLink', {
|
||||
> 参考 [vxe-table 官方文档 - 虚拟滚动](https://vxetable.cn/v4/#/component/grid/scroll/vertical)。
|
||||
|
||||
<DemoPreview dir="demos/vben-vxe-table/virtual" />
|
||||
|
||||
## 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 返回的第二个参数,是一个对象,包含了一些表单的方法。
|
||||
|
||||
| 方法名 | 描述 | 类型 |
|
||||
| --- | --- | --- |
|
||||
| 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` |
|
||||
|
||||
### Props
|
||||
|
||||
## Props
|
||||
|
||||
所有属性都可以传入 `useVbenVxeGrid` 的第一个参数中。
|
||||
|
||||
| 属性名 | 描述 | 类型 |
|
||||
| -------------- | ------------------ | ------------------- |
|
||||
| tableTitle | 表格标题 | `string` |
|
||||
| tableTitleHelp | 表格标题帮助信息 | `string` |
|
||||
| gridClass | grid组件的class | `string` |
|
||||
| gridOptions | grid组件的参数 | `VxeTableGridProps` |
|
||||
| gridEvents | grid组件的触发的⌚️ | `VxeGridListeners` |
|
||||
| formOptions | 表单参数 | `VbenFormProps` |
|
||||
|
@@ -1,14 +1,10 @@
|
||||
<script lang="ts" setup>
|
||||
import type {
|
||||
UseVbenVxeGrid,
|
||||
VxeGridListeners,
|
||||
VxeGridProps,
|
||||
} from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
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 {
|
||||
@@ -20,10 +16,6 @@ interface RowType {
|
||||
role: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const gridOptions: VxeGridProps<RowType> = {
|
||||
columns: [
|
||||
{ title: '序号', type: 'seq', width: 50 },
|
||||
|
@@ -1,10 +1,10 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
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 {
|
||||
@@ -19,10 +19,6 @@ interface RowType {
|
||||
status: 'error' | 'success' | 'warning';
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const gridOptions: VxeGridProps<RowType> = {
|
||||
checkboxConfig: {
|
||||
highlight: true,
|
||||
|
@@ -1,7 +1,7 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
import type { VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
import { useVbenVxeGrid } from '#/adapter/vxe-table';
|
||||
|
||||
import { getExampleTableApi } from '../mock-api';
|
||||
|
||||
@@ -14,10 +14,6 @@ interface RowType {
|
||||
releaseDate: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const gridOptions: VxeGridProps<RowType> = {
|
||||
columns: [
|
||||
{ title: '序号', type: 'seq', width: 50 },
|
||||
|
@@ -1,10 +1,10 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
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 {
|
||||
@@ -16,10 +16,6 @@ interface RowType {
|
||||
releaseDate: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const gridOptions: VxeGridProps<RowType> = {
|
||||
columns: [
|
||||
{ title: '序号', type: 'seq', width: 50 },
|
||||
|
@@ -1,10 +1,10 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
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 {
|
||||
@@ -16,10 +16,6 @@ interface RowType {
|
||||
releaseDate: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const gridOptions: VxeGridProps<RowType> = {
|
||||
columns: [
|
||||
{ fixed: 'left', title: '序号', type: 'seq', width: 50 },
|
||||
|
@@ -1,11 +1,11 @@
|
||||
<script lang="ts" setup>
|
||||
import type { VbenFormProps } from '#/adapter/form';
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
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 {
|
||||
@@ -17,10 +17,6 @@ interface RowType {
|
||||
releaseDate: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const formOptions: VbenFormProps = {
|
||||
// 默认展开
|
||||
collapsed: false,
|
||||
|
@@ -1,11 +1,12 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
import type { DemoTableApi } from '../mock-api';
|
||||
|
||||
import { inject } from 'vue';
|
||||
import type { VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { Button } from 'ant-design-vue';
|
||||
|
||||
import { type DemoTableApi } from '../mock-api';
|
||||
import { useVbenVxeGrid } from '#/adapter/vxe-table';
|
||||
|
||||
import { MOCK_API_DATA } from '../table-data';
|
||||
|
||||
interface RowType {
|
||||
@@ -17,10 +18,6 @@ interface RowType {
|
||||
releaseDate: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
// 数据实例
|
||||
// const MOCK_TREE_TABLE_DATA = [
|
||||
// {
|
||||
|
@@ -1,10 +1,10 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject } from 'vue';
|
||||
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 {
|
||||
@@ -16,10 +16,6 @@ interface RowType {
|
||||
type: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
// 数据实例
|
||||
// const MOCK_TREE_TABLE_DATA = [
|
||||
// {
|
||||
|
@@ -1,7 +1,9 @@
|
||||
<script lang="ts" setup>
|
||||
import type { UseVbenVxeGrid, VxeGridProps } from '#/adapter/vxe-table';
|
||||
import type { VxeGridProps } from '#/adapter/vxe-table';
|
||||
|
||||
import { inject, onMounted } from 'vue';
|
||||
import { onMounted } from 'vue';
|
||||
|
||||
import { useVbenVxeGrid } from '#/adapter/vxe-table';
|
||||
|
||||
interface RowType {
|
||||
id: number;
|
||||
@@ -10,10 +12,6 @@ interface RowType {
|
||||
sex: string;
|
||||
}
|
||||
|
||||
const useVbenVxeGrid = inject<UseVbenVxeGrid>(
|
||||
'useVbenVxeGrid',
|
||||
) as UseVbenVxeGrid;
|
||||
|
||||
const gridOptions: VxeGridProps<RowType> = {
|
||||
columns: [
|
||||
{ type: 'seq', width: 70 },
|
||||
|
@@ -164,6 +164,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
|
||||
/**
|
||||
* @description 项目配置文件
|
||||
* 只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置
|
||||
* !!! 更改配置后请清空缓存,否则可能不生效
|
||||
*/
|
||||
export const overridesPreferences = defineOverridesPreferences({
|
||||
// overrides
|
||||
@@ -536,5 +537,4 @@ interface Preferences {
|
||||
|
||||
- `overridesPreferences`方法只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置。
|
||||
- 任何配置项都可以覆盖,只需要在`overridesPreferences`方法内覆盖即可,不要修改默认配置文件。
|
||||
|
||||
:::
|
||||
- 更改配置后请清空缓存,否则可能不生效。:::
|
||||
|
@@ -66,7 +66,9 @@ pnpm install
|
||||
|
||||
::: tip 注意
|
||||
|
||||
项目只支持使用 `pnpm` 进行依赖安装,默认会使用 `corepack` 来安装指定版本的 `pnpm`。:
|
||||
- 项目只支持使用 `pnpm` 进行依赖安装,默认会使用 `corepack` 来安装指定版本的 `pnpm`。:
|
||||
- 如果你的网络环境无法访问npm源,你可以设置系统的环境变量`COREPACK_REGISTRY=https://registry.npmmirror.com`,然后再执行`pnpm install`。
|
||||
- 如果你不想使用`corepack`,你需要禁用`corepack`,然后使用你自己的`pnpm`进行安装。
|
||||
|
||||
:::
|
||||
|
||||
|
Reference in New Issue
Block a user