Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Nov 6, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions apps/web-antd/src/preferences.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
/**
* @description 项目配置文件
* 只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置
* !!! 更改配置后请清空缓存,否则可能不生效
*/
export const overridesPreferences = defineOverridesPreferences({
// overrides
Expand Down
1 change: 1 addition & 0 deletions apps/web-ele/src/preferences.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
/**
* @description 项目配置文件
* 只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置
* !!! 更改配置后请清空缓存,否则可能不生效
*/
export const overridesPreferences = defineOverridesPreferences({
// overrides
Expand Down
1 change: 1 addition & 0 deletions apps/web-naive/src/preferences.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
/**
* @description 项目配置文件
* 只需要覆盖项目中的一部分配置,不需要的配置不用覆盖,会自动使用默认配置
* !!! 更改配置后请清空缓存,否则可能不生效
*/
export const overridesPreferences = defineOverridesPreferences({
// overrides
Expand Down
6 changes: 5 additions & 1 deletion docs/.vitepress/config/shared.mts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,10 @@ import type { HeadConfig } from 'vitepress';

import { resolve } from 'node:path';

import { viteArchiverPlugin } from '@vben/vite-config';
import {
viteArchiverPlugin,
viteVxeTableImportsPlugin,
} from '@vben/vite-config';

import {
GitChangelog,
Expand Down Expand Up @@ -85,6 +88,7 @@ export const shared = defineConfig({
GitChangelogMarkdownSection(),
viteArchiverPlugin({ outputDir: '.vitepress' }),
groupIconVitePlugin(),
await viteVxeTableImportsPlugin(),
],
server: {
fs: {
Expand Down
15 changes: 0 additions & 15 deletions docs/.vitepress/theme/components/site-layout.vue
Original file line number Diff line number Diff line change
Expand Up @@ -32,21 +32,6 @@ watch(
() => nextTick(() => initZoom()),
);

function setVxeTheme(name?: string) {
const theme = !name || name === 'default' ? 'light' : name;

if (typeof document !== 'undefined') {
const documentElement = document.documentElement;
if (documentElement) {
documentElement.dataset.vxeUiTheme = theme;
}
}
}

watch(isDark, (dark) => {
setVxeTheme(dark ? 'dark' : 'light');
});

// initPreferences({
// namespace: 'docs',
// });
Expand Down
64 changes: 0 additions & 64 deletions docs/.vitepress/theme/index.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
// https://vitepress.dev/guide/custom-theme
import type { EnhanceAppContext, Theme } from 'vitepress';

import { h } from 'vue';

import { useVbenForm } from '@vben/common-ui';

import { NolebaseGitChangelogPlugin } from '@nolebase/vitepress-plugin-git-changelog/client';
import { Button, Image } from 'ant-design-vue';
import DefaultTheme from 'vitepress/theme';

import { DemoPreview } from '../components';
Expand All @@ -26,65 +21,6 @@ export default {
app.component('DemoPreview', DemoPreview);
app.use(NolebaseGitChangelogPlugin);

if (!import.meta.env.SSR) {
const plugin = await import('@vben/plugins/vxe-table');

plugin.setupVbenVxeTable({
configVxeTable: (vxeUI) => {
vxeUI.setConfig({
grid: {
align: 'center',
border: false,
columnConfig: {
resizable: true,
},
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', {
renderDefault(_renderOpts, params) {
const { column, row } = params;
return h(Image, { src: row[column.field] } as any);
},
});

// 表格配置项可以用 cellRender: { name: 'CellLink' },
vxeUI.renderer.add('CellLink', {
renderDefault(renderOpts) {
const { props } = renderOpts;
return h(
Button,
{ size: 'small', type: 'link' },
{ default: () => props?.text },
);
},
});

// 这里可以自行扩展 vxe-table 的全局配置,比如自定义格式化
// vxeUI.formats.add
},
useVbenForm,
});

app.component('VbenVxeGrid', plugin.VbenVxeGrid);
app.provide('useVbenVxeGrid', plugin.useVbenVxeGrid);
}

// 百度统计
initHmPlugin();
},
Expand Down
1 change: 0 additions & 1 deletion docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@
"@nolebase/vitepress-plugin-git-changelog": "catalog:",
"@vben/vite-config": "workspace:*",
"@vite-pwa/vitepress": "catalog:",
"sass": "^1.80.6",
"vitepress": "catalog:",
"vue": "catalog:"
}
Expand Down
67 changes: 67 additions & 0 deletions docs/src/_env/adapter/vxe-table.ts
Original file line number Diff line number Diff line change
@@ -1 +1,68 @@
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,
},

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 };

anncwb marked this conversation as resolved.
Show resolved Hide resolved
export type * from '@vben/plugins/vxe-table';
132 changes: 128 additions & 4 deletions docs/src/components/common-ui/vben-vxe-table.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,84 @@ outline: deep

:::

::: tip README
## 适配器

表格底层使用 [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,
});

下方示例代码中, 出现的 `inject<UseVbenVxeGrid>` 是为了适配文档内的示例,实际使用时直接从 `'@vben/plugins/vxe-table'` 引入即可。
export { useVbenVxeGrid };

```typescript
import { useVbenVxeGrid } from '@vben/plugins/vxe-table';
export type * from '@vben/plugins/vxe-table';
```

:::
Expand Down Expand Up @@ -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` |
14 changes: 3 additions & 11 deletions docs/src/demos/vben-vxe-table/basic/index.vue
Original file line number Diff line number Diff line change
@@ -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 {
Expand All @@ -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 },
Expand Down
Loading
Loading