docs(@vben/docs): sync component docs with current APIs

2026-03-14 21:34:48 +08:00
parent 6c274b75b8
commit 6b3bcee582
21 changed files with 937 additions and 283 deletions
--- a/docs/src/components/common-ui/vben-vxe-table.md
+++ b/docs/src/components/common-ui/vben-vxe-table.md
@@ -4,25 +4,19 @@ outline: deep

 # Vben Vxe Table 表格

-框架提供的Table 列表组件基于 [vxe-table](https://vxetable.cn/v4/#/grid/api?apiKey=grid)，结合`Vben Form 表单`进行了二次封装。
+`Vben Vxe 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) 内寻找
+> 如果文档内没有覆盖到你需要的细节，可以结合在线示例和 [vxe-grid 官方 API](https://vxetable.cn/v4/#/grid/api?apiKey=grid) 一起查看。

 ::: info 写在前面

-如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，大可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。
-
-:::
+如果现有封装不满足你的场景，可以直接使用原生 `vxe-table` 能力，或者在适配层中继续扩展。:::

 ## 适配器

-表格底层使用 [vxe-table](https://vxetable.cn/#/start/install) 进行实现，所以你可以使用 `vxe-table` 的所有功能。对于不同的 UI 框架，我们提供了适配器，以便更好的适配不同的 UI 框架。
+底层表格基于 `vxe-table`，每个应用都可以在自己的适配层中配置默认行为、自定义渲染器以及与 UI 组件库的集成。

-### 适配器说明
-
-每个应用都可以自己配置`vxe-table`的适配器，你可以根据自己的需求。下面是一个简单的配置示例：
+### 适配器示例

 ::: details vxe-table 表格适配器

@@ -46,7 +40,6 @@ setupVbenVxeTable({
        },
        minHeight: 180,
        formConfig: {
-          // 全局禁用vxe-table的表单配置，使用formOptions
          enabled: false,
        },
        proxyConfig: {
@@ -65,7 +58,6 @@ setupVbenVxeTable({
      },
    });

-    // 表格配置项可以用 cellRender: { name: 'CellImage' },
    vxeUI.renderer.add('CellImage', {
      renderTableDefault(_renderOpts, params) {
        const { column, row } = params;
@@ -73,7 +65,6 @@ setupVbenVxeTable({
      },
    });

-    // 表格配置项可以用 cellRender: { name: 'CellLink' },
    vxeUI.renderer.add('CellLink', {
      renderTableDefault(renderOpts) {
        const { props } = renderOpts;
@@ -84,9 +75,6 @@ setupVbenVxeTable({
        );
      },
    });
-
-    // 这里可以自行扩展 vxe-table 的全局配置，比如自定义格式化
-    // vxeUI.formats.add
  },
  useVbenForm,
 });
@@ -100,55 +88,50 @@ export type * from '@vben/plugins/vxe-table';

 ## 基础表格

-使用 `useVbenVxeGrid` 创建最基础的表格。
+通过 `useVbenVxeGrid` 创建一个基础表格。

 <DemoPreview dir="demos/vben-vxe-table/basic" />

 ## 远程加载

-通过指定 `proxyConfig.ajax` 的 `query` 方法，可以实现远程加载数据。
+通过配置 `proxyConfig.ajax.query` 实现远程数据加载。

 <DemoPreview dir="demos/vben-vxe-table/remote" />

 ## 树形表格

-树形表格的数据源为扁平结构，可以指定`treeConfig`配置项，实现树形表格。
+树形表格的数据源通常是扁平结构，可以通过 `treeConfig` 转换为树形展示。

-```typescript
+```ts
 treeConfig: {
-  transform: true, // 指定表格为树形表格
-  parentField: 'parentId', // 父节点字段名
-  rowField: 'id', // 行数据字段名
+  transform: true,
+  parentField: 'parentId',
+  rowField: 'id',
 },
 ```

 <DemoPreview dir="demos/vben-vxe-table/tree" />

-## 固定表头/列
+## 固定列

-列固定可选参数： `'left' | 'right' | '' | null`
+固定列可选值为 `'left' | 'right' | '' | null`。

 <DemoPreview dir="demos/vben-vxe-table/fixed" />

 ## 自定义单元格

-自定义单元格有两种实现方式
+可以通过插槽或自定义渲染器实现单元格定制。

- 通过 `slots` 插槽
- 通过 `customCell` 自定义单元格，但是要先添加渲染器
-
-```typescript
-// 表格配置项可以用 cellRender: { name: 'CellImage' },
+```ts
 vxeUI.renderer.add('CellImage', {
-  renderDefault(_renderOpts, params) {
+  renderTableDefault(_renderOpts, params) {
    const { column, row } = params;
-    return h(Image, { src: row[column.field] } as any); // 注意此处的Image 组件，来源于Antd，需要自行引入,否则会使用js的Image类
+    return h(Image, { src: row[column.field] } as any);
  },
 });

-// 表格配置项可以用 cellRender: { name: 'CellLink' },
 vxeUI.renderer.add('CellLink', {
-  renderDefault(renderOpts) {
+  renderTableDefault(renderOpts) {
    const { props } = renderOpts;
    return h(
      Button,
@@ -163,23 +146,20 @@ vxeUI.renderer.add('CellLink', {

 ## 搜索表单

-**表单搜索** 部分采用了`Vben Form 表单`，参考 [Vben Form 表单文档](/components/common-ui/vben-form)。
+搜索区域底层使用的是 `Vben Form`。启用搜索表单后，可以通过 `gridOptions.toolbarConfig.search = true` 在工具栏中显示搜索面板开关按钮。

-当启用了表单搜索时，可以在toolbarConfig中配置`search`为`true`来让表格在工具栏区域显示一个搜索表单控制按钮。表格的所有以`form-`开头的命名插槽都会被传递给搜索表单。
+所有以 `form-` 开头的具名插槽都会自动转发到搜索表单。

-### 定制分隔条
+### 自定义分隔条

-当你启用表单搜索时，在表单和表格之间会显示一个分隔条。这个分隔条使用了默认的组件背景色，并且横向贯穿整个Vben Vxe Table在视觉上融入了页面的默认背景中。如果你在Vben Vxe Table的外层包裹了一个不同背景色的容器（如将其放在一个Card内），默认的表单和表格之间的分隔条可能就显得格格不入了，下面的代码演示了如何定制这个分隔条。
+启用搜索表单时，表单和表格主体之间默认会显示一个分隔条。可以通过 `separator` 调整或关闭它。

 ```ts
 const [Grid] = useVbenVxeGrid({
  formOptions: {},
  gridOptions: {},
-  // 完全移除分隔条
  separator: false,
-  // 你也可以使用下面的代码来移除分隔条
  // separator: { show: false },
-  // 或者使用下面的代码来改变分隔条的颜色
  // separator: { backgroundColor: 'rgba(100,100,0,0.5)' },
 });
 ```
@@ -188,40 +168,36 @@ const [Grid] = useVbenVxeGrid({

 ## 单元格编辑

-通过指定`editConfig.mode`为`cell`，可以实现单元格编辑。
+通过设置 `editConfig.mode = 'cell'` 开启单元格编辑。

 <DemoPreview dir="demos/vben-vxe-table/edit-cell" />

 ## 行编辑

-通过指定`editConfig.mode`为`row`，可以实现行编辑。
+通过设置 `editConfig.mode = 'row'` 开启整行编辑。

 <DemoPreview dir="demos/vben-vxe-table/edit-row" />

 ## 虚拟滚动

-通过 scroll-y.enabled 与 scroll-y.gt 组合开启，其中 enabled 为总开关，gt 是指当总行数大于指定行数时自动开启。
+通过 `scroll-y.enabled` 和 `scroll-y.gt` 组合开启纵向虚拟滚动。

-> 参考 [vxe-table 官方文档 - 虚拟滚动](https://vxetable.cn/v4/#/component/grid/scroll/vertical)。
+> 参考 [vxe-table 官方文档 - 虚拟滚动](https://vxetable.cn/v4/#/component/grid/scroll/vertical)

 <DemoPreview dir="demos/vben-vxe-table/virtual" />

 ## API

-`useVbenVxeGrid` 返回一个数组，第一个元素是表格组件，第二个元素是表格的方法。
+`useVbenVxeGrid` 返回一个数组，第一个元素是表格组件，第二个元素是表格 API。

 ```vue
 <script setup lang="ts">
 import { useVbenVxeGrid } from '#/adapter/vxe-table';

-// Grid 为表格组件
-// gridApi 为表格的方法
 const [Grid, gridApi] = useVbenVxeGrid({
  gridOptions: {},
  formOptions: {},
  gridEvents: {},
-  // 属性
-  // 事件
 });
 </script>

@@ -232,45 +208,42 @@ const [Grid, gridApi] = useVbenVxeGrid({

 ### 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` | - |
-| toggleSearchForm | 设置搜索表单显示状态 | `(show?: boolean)=>boolean` | 当省略参数时，则将表单在显示和隐藏两种状态之间切换 |
+| setLoading | 设置 loading 状态 | `(loading: boolean) => void` | - |
+| setGridOptions | 更新 `gridOptions` | `(options: Partial<VxeGridProps['gridOptions']>) => void` | - |
+| reload | 重新加载表格，并重置到初始分页 | `(params?: Record<string, any>) => void` | - |
+| query | 重新查询表格，保留当前分页 | `(params?: Record<string, any>) => void` | - |
+| grid | `vxe-grid` 实例 | `VxeGridInstance` | - |
+| formApi | 搜索表单 API 实例 | `FormApi` | - |
+| toggleSearchForm | 切换或指定搜索表单显示状态 | `(show?: boolean) => boolean` | 传入参数时强制设置；不传参数时在显示和隐藏之间切换，并返回当前状态 |

 ## Props

-所有属性都可以传入 `useVbenVxeGrid` 的第一个参数中。
+所有属性都通过 `useVbenVxeGrid` 的第一个参数传入。

 | 属性名 | 描述 | 类型 | 版本要求 |
 | --- | --- | --- | --- |
 | tableTitle | 表格标题 | `string` | - |
 | tableTitleHelp | 表格标题帮助信息 | `string` | - |
-| gridClass | grid组件的class | `string` | - |
-| gridOptions | grid组件的参数 | `VxeTableGridProps` | - |
-| gridEvents | grid组件的触发的事件 | `VxeGridListeners` | - |
-| formOptions | 表单参数 | `VbenFormProps` | - |
+| class | 外层容器的 class | `string` | - |
+| gridClass | `vxe-grid` 的 class | `string` | - |
+| gridOptions | `vxe-grid` 配置 | `DeepPartial<VxeTableGridOptions>` | - |
+| gridEvents | `vxe-grid` 事件 | `DeepPartial<VxeGridListeners>` | - |
+| formOptions | 搜索表单配置 | `VbenFormProps` | - |
 | showSearchForm | 是否显示搜索表单 | `boolean` | - |
-| separator | 搜索表单与表格主体之间的分隔条 | `boolean\|SeparatorOptions` | >5.5.4 |
+| separator | 搜索表单与表格主体之间的分隔条 | `boolean \| SeparatorOptions` | `>5.5.4` |

 ## Slots

-大部分插槽的说明请参考 [vxe-table 官方文档](https://vxetable.cn/v4/#/grid/api)，但工具栏部分由于做了一些定制封装，需使用以下插槽定制表格的工具栏：
+大部分插槽说明可参考 [vxe-table 官方文档](https://vxetable.cn/v4/#/grid/api)，这里列出封装层新增或约定的部分。

-| 插槽名          | 描述                                         |
-| --------------- | -------------------------------------------- |
-| toolbar-actions | 工具栏左侧部分（表格标题附近）               |
-| toolbar-tools   | 工具栏右侧部分（vxeTable原生工具按钮的左侧） |
-| table-title     | 表格标题插槽                                 |
+| 插槽名          | 描述                                 |
+| --------------- | ------------------------------------ |
+| toolbar-actions | 工具栏左侧区域，位于标题附近         |
+| toolbar-tools   | 工具栏右侧区域，位于内置工具按钮左侧 |
+| table-title     | 自定义表格标题                       |

-::: info 搜索表单的插槽
+::: info 搜索表单插槽

-对于使用了搜索表单的表格来说，所有以`form-`开头的命名插槽都会传递给表单。
-
-:::
+当启用了搜索表单时，所有以 `form-` 开头的具名插槽都会被转发给表单。:::