perf: improve the usage documentation of vben-vxe-table (#4829)

* perf: improve the usage documentation of vben-vxe-table
This commit is contained in:
Vben
2024-11-06 23:03:33 +08:00
committed by GitHub
parent 33ce4d3cf3
commit 4e88ef0840
31 changed files with 720 additions and 888 deletions

View File

@@ -1,2 +0,0 @@
export * from './form';
export * from './vxe-table';

View File

@@ -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';

View File

@@ -0,0 +1,4 @@
export const useVbenForm = () => {};
export const z = {};
export type VbenFormSchema = any;
export type VbenFormProps = any;

View File

@@ -0,0 +1,3 @@
export type * from '@vben/plugins/vxe-table';
export const useVbenVxeGrid = () => {};

View File

@@ -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` |

View File

@@ -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 },

View File

@@ -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,

View File

@@ -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 },

View File

@@ -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 },

View File

@@ -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 },

View File

@@ -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,

View File

@@ -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 = [
// {

View File

@@ -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 = [
// {

View File

@@ -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 },

View File

@@ -164,6 +164,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
/**
* @description 项目配置文件
* 只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置
* !!! 更改配置后请清空缓存,否则可能不生效
*/
export const overridesPreferences = defineOverridesPreferences({
// overrides
@@ -536,5 +537,4 @@ interface Preferences {
- `overridesPreferences`方法只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置。
- 任何配置项都可以覆盖,只需要在`overridesPreferences`方法内覆盖即可,不要修改默认配置文件。
:::
- 更改配置后请清空缓存,否则可能不生效。:::

View File

@@ -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`进行安装。
:::