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

* perf: improve the usage documentation of vben-vxe-table

apps/web-antd/src/preferences.ts

@@ -3,6 +3,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
 /**
  * @description 项目配置文件
  * 只需要覆盖项目中的一部分配置，不需要的配置不用覆盖，会自动使用默认配置
+ * !!! 更改配置后请清空缓存，否则可能不生效
  */
 export const overridesPreferences = defineOverridesPreferences({
   // overrides

apps/web-ele/src/preferences.ts

@@ -3,6 +3,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
 /**
  * @description 项目配置文件
  * 只需要覆盖项目中的一部分配置，不需要的配置不用覆盖，会自动使用默认配置
+ * !!! 更改配置后请清空缓存，否则可能不生效
  */
 export const overridesPreferences = defineOverridesPreferences({
   // overrides

apps/web-naive/src/preferences.ts

@@ -3,6 +3,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
 /**
  * @description 项目配置文件
  * 只需要覆盖项目中的一部分配置，不需要的配置不用覆盖，会自动使用默认配置
+ * !!! 更改配置后请清空缓存，否则可能不生效
  */
 export const overridesPreferences = defineOverridesPreferences({
   // overrides

docs/.vitepress/config/shared.mts

@@ -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,
@@ -85,6 +88,7 @@ export const shared = defineConfig({
       GitChangelogMarkdownSection(),
       viteArchiverPlugin({ outputDir: '.vitepress' }),
       groupIconVitePlugin(),
+      await viteVxeTableImportsPlugin(),
     ],
     server: {
       fs: {

docs/.vitepress/theme/components/site-layout.vue

@@ -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',
 // });

docs/.vitepress/theme/index.ts

@@ -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';
@@ -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();
   },

docs/package.json

@@ -8,7 +8,10 @@
     "docs:preview": "vitepress preview"
   },
   "imports": {
-    "#/*": "./src/_env/*"
+    "#/*": {
+      "node": "./src/_env/node/*",
+      "default": "./src/_env/*"
+    }
   },
   "dependencies": {
     "@vben-core/shadcn-ui": "workspace:*",
@@ -26,7 +29,6 @@
     "@nolebase/vitepress-plugin-git-changelog": "catalog:",
     "@vben/vite-config": "workspace:*",
     "@vite-pwa/vitepress": "catalog:",
-    "sass": "^1.80.6",
     "vitepress": "catalog:",
     "vue": "catalog:"
   }

docs/src/_env/adapter/vxe-table.ts

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

docs/src/_env/node/adapter/form.ts

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

docs/src/_env/node/adapter/vxe-table.ts

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

docs/src/components/common-ui/vben-vxe-table.md

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