docs: add vxe-table doc (#4807)

* docs: init vxe-table demos

* style: fix vxe-table index.scss import error

* docs: fix vxe-table style & theme toggle problem

* docs: add rest demos

* docs: add vxe-table demo desc

* fix: add maximumFileSizeToCacheInBytes to fix build error

* fix: fix vxe-table set-theme build error

* docs: fix vitepress ssr render problem

* docs: add some tips for vitepress compatibility

docs/.vitepress/config/shared.mts

@@ -156,6 +156,7 @@ function pwa(): PwaOptions {
     registerType: 'autoUpdate',
     workbox: {
       globPatterns: ['**/*.{css,js,html,svg,png,ico,txt,woff2}'],
+      maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
     },
   };
 }

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

@@ -32,6 +32,21 @@ 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,7 +1,12 @@
 // 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';
@@ -15,11 +20,71 @@ import 'virtual:group-icons.css';
 import '@nolebase/vitepress-plugin-git-changelog/client/style.css';
 
 export default {
-  enhanceApp(ctx: EnhanceAppContext) {
+  async enhanceApp(ctx: EnhanceAppContext) {
     const { app } = ctx;
     app.component('VbenContributors', VbenContributors);
     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

@@ -14,6 +14,7 @@
     "@vben-core/shadcn-ui": "workspace:*",
     "@vben/common-ui": "workspace:*",
     "@vben/locales": "workspace:*",
+    "@vben/plugins": "workspace:*",
     "@vben/styles": "workspace:*",
     "ant-design-vue": "catalog:",
     "lucide-vue-next": "catalog:",
@@ -25,6 +26,7 @@
     "@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/index.ts

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

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

@@ -0,0 +1 @@
+export type * from '@vben/plugins/vxe-table';

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

@@ -4,4 +4,113 @@ outline: deep
 
 # Vben Vxe Table 表格
 
-文档待补充，如果需要使用，可先行查看 vxe-table 文档和 示例代码，内部有部分注释。
+框架提供的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 写在前面
+
+如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，大可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。
+
+:::
+
+::: tip README
+
+下方示例代码中, 出现的 `inject<UseVbenVxeGrid>` 是为了适配文档内的示例，实际使用时直接从 `'@vben/plugins/vxe-table'` 引入即可。
+
+```typescript
+import { useVbenVxeGrid } from '@vben/plugins/vxe-table';
+```
+
+:::
+
+## 基础表格
+
+使用 `useVbenVxeGrid` 创建最基础的表格。
+
+<DemoPreview dir="demos/vben-vxe-table/basic" />
+
+## 远程加载
+
+通过指定 `proxyConfig.ajax` 的 `query` 方法，可以实现远程加载数据。
+
+<DemoPreview dir="demos/vben-vxe-table/remote" />
+
+## 树形表格
+
+树形表格，的数据源为扁平结构，可以指定`treeConfig`配置项，实现树形表格。
+
+```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)。
+
+<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" />

docs/src/demos/vben-vxe-table/basic/index.vue

@@ -0,0 +1,93 @@
+<script lang="ts" setup>
+import type {
+  UseVbenVxeGrid,
+  VxeGridListeners,
+  VxeGridProps,
+} from '#/adapter/vxe-table';
+
+import { inject } from 'vue';
+
+import { Button, message } from 'ant-design-vue';
+
+import { MOCK_TABLE_DATA } from '../table-data';
+
+interface RowType {
+  address: string;
+  age: number;
+  id: number;
+  name: string;
+  nickname: string;
+  role: string;
+}
+
+const useVbenVxeGrid = inject<UseVbenVxeGrid>(
+  'useVbenVxeGrid',
+) as UseVbenVxeGrid;
+
+const gridOptions: VxeGridProps<RowType> = {
+  columns: [
+    { title: '序号', type: 'seq', width: 50 },
+    { field: 'name', title: 'Name' },
+    { field: 'age', sortable: true, title: 'Age' },
+    { field: 'nickname', title: 'Nickname' },
+    { field: 'role', title: 'Role' },
+    { field: 'address', showOverflow: true, title: 'Address' },
+  ],
+  data: MOCK_TABLE_DATA,
+  pagerConfig: {
+    enabled: false,
+  },
+  sortConfig: {
+    multiple: true,
+  },
+};
+
+const gridEvents: VxeGridListeners<RowType> = {
+  cellClick: ({ row }) => {
+    message.info(`cell-click: ${row.name}`);
+  },
+};
+
+const [Grid, gridApi] = useVbenVxeGrid({ gridEvents, gridOptions });
+
+const showBorder = gridApi.useStore((state) => state.gridOptions?.border);
+const showStripe = gridApi.useStore((state) => state.gridOptions?.stripe);
+
+function changeBorder() {
+  gridApi.setGridOptions({
+    border: !showBorder.value,
+  });
+}
+
+function changeStripe() {
+  gridApi.setGridOptions({
+    stripe: !showStripe.value,
+  });
+}
+
+function changeLoading() {
+  gridApi.setLoading(true);
+  setTimeout(() => {
+    gridApi.setLoading(false);
+  }, 2000);
+}
+</script>
+
+<template>
+  <!-- 此处的`vp-raw` 是为了适配文档的展示效果，实际使用时不需要 -->
+  <div class="vp-raw w-full">
+    <Grid>
+      <template #toolbar-tools>
+        <Button class="mr-2" type="primary" @click="changeBorder">
+          {{ showBorder ? '隐藏' : '显示' }}边框
+        </Button>
+        <Button class="mr-2" type="primary" @click="changeLoading">
+          显示loading
+        </Button>
+        <Button class="mr-2" type="primary" @click="changeStripe">
+          {{ showStripe ? '隐藏' : '显示' }}斑马纹
+        </Button>
+      </template>
+    </Grid>
+  </div>
+</template>