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

2026-05-13 15:12:10 +08:00 · 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-alert.md
+++ b/docs/src/components/common-ui/vben-alert.md
@@ -4,132 +4,90 @@ outline: deep

 # Vben Alert 轻量提示框

-框架提供的一些用于轻量提示的弹窗，仅使用js代码即可快速动态创建提示而不需要在template写任何代码。
+`Alert` 提供了一组纯 JavaScript 调用的轻量提示框能力，适合快速创建 `alert`、`confirm`、`prompt` 这类简单交互。

-::: info 应用场景
+::: info 适用场景

-Alert提供的功能与Modal类似，但只适用于简单应用场景。例如临时性、动态地弹出模态确认框、输入框等。如果对弹窗有更复杂的需求，请使用VbenModal
-
-:::
+`Alert` 与 `Modal` 的能力有部分重叠，但更适合临时确认、简单提示和轻量输入场景。复杂弹窗仍然建议使用 `Vben Modal`。:::

 ::: tip 注意

-Alert提供的快捷方法alert、confirm、prompt动态创建的弹窗在已打开的情况下，不支持HMR（热更新），代码变更后需要关闭这些弹窗后重新打开。
-
-:::
-
-::: tip README
-
-下方示例代码中的，存在一些主题色未适配、样式缺失的问题，这些问题只在文档内会出现，实际使用并不会有这些问题，可忽略，不必纠结。
-
-:::
+通过 `alert`、`confirm`、`prompt` 动态创建的弹窗，在已经打开的情况下不支持 HMR 热更新。修改相关代码后，需要关闭后重新打开。:::

 ## 基础用法

-使用 `alert` 创建只有一个确认按钮的提示框。
+使用 `alert` 创建只有确认按钮的提示框。

 <DemoPreview dir="demos/vben-alert/alert" />

-使用 `confirm` 创建有确认和取消按钮的提示框。
+使用 `confirm` 创建带确认和取消按钮的提示框。

 <DemoPreview dir="demos/vben-alert/confirm" />

-使用 `prompt` 创建有确认和取消按钮、接受用户输入的提示框。
+使用 `prompt` 创建可接收用户输入的提示框。

 <DemoPreview dir="demos/vben-alert/prompt" />

 ## useAlertContext

-当弹窗的content、footer、icon使用自定义组件时，在这些组件中可以使用 `useAlertContext` 获取当前弹窗的上下文对象，用来主动控制弹窗。
+当 `content`、`footer` 或 `icon` 使用的是自定义组件时，可以在这些组件内部通过 `useAlertContext()` 获取当前弹窗上下文，并主动触发确认或取消。

 ::: tip 注意

-`useAlertContext`只能用在setup或者函数式组件中。
-
-:::
+`useAlertContext` 只能在 `setup` 或函数式组件中使用。:::

 ### Methods

-| 方法      | 描述               | 类型     | 版本要求 |
-| --------- | ------------------ | -------- | -------- |
-| doConfirm | 调用弹窗的确认操作 | ()=>void | >5.5.4   |
-| doCancel  | 调用弹窗的取消操作 | ()=>void | >5.5.4   |
+| 方法      | 描述                   | 类型         | 版本要求 |
+| --------- | ---------------------- | ------------ | -------- |
+| doConfirm | 触发当前弹窗的确认操作 | `() => void` | `>5.5.4` |
+| doCancel  | 触发当前弹窗的取消操作 | `() => void` | `>5.5.4` |

 ## 类型说明

 ```ts
-/** 预置的图标类型 */
 export type IconType = 'error' | 'info' | 'question' | 'success' | 'warning';

 export type BeforeCloseScope = {
-  /** 是否为点击确认按钮触发的关闭 */
  isConfirm: boolean;
 };

-/**
- * alert 属性
- */
 export type AlertProps = {
-  /** 关闭前的回调，如果返回false，则终止关闭 */
  beforeClose?: (
    scope: BeforeCloseScope,
  ) => boolean | Promise<boolean | undefined> | undefined;
-  /** 边框 */
  bordered?: boolean;
-  /** 按钮对齐方式 */
  buttonAlign?: 'center' | 'end' | 'start';
-  /** 取消按钮的标题 */
  cancelText?: string;
-  /** 是否居中显示 */
  centered?: boolean;
-  /** 确认按钮的标题 */
  confirmText?: string;
-  /** 弹窗容器的额外样式 */
  containerClass?: string;
-  /** 弹窗提示内容 */
  content: Component | string;
-  /** 弹窗内容的额外样式 */
  contentClass?: string;
-  /** 执行beforeClose回调期间，在内容区域显示一个loading遮罩*/
  contentMasking?: boolean;
-  /** 弹窗底部内容（与按钮在同一个容器中） */
  footer?: Component | string;
-  /** 弹窗的图标（在标题的前面） */
  icon?: Component | IconType;
-  /**
-   * 弹窗遮罩模糊效果
-   */
  overlayBlur?: number;
-  /** 是否显示取消按钮 */
  showCancel?: boolean;
-  /** 弹窗标题 */
  title?: string;
 };

-/** prompt 属性 */
 export type PromptProps<T = any> = {
-  /** 关闭前的回调，如果返回false，则终止关闭 */
  beforeClose?: (scope: {
    isConfirm: boolean;
    value: T | undefined;
  }) => boolean | Promise<boolean | undefined> | undefined;
-  /** 用于接受用户输入的组件 */
  component?: Component;
-  /** 输入组件的属性 */
  componentProps?: Recordable<any>;
-  /** 输入组件的插槽 */
-  componentSlots?: Recordable<Component>;
-  /** 默认值 */
+  componentSlots?:
+    | (() => any)
+    | Recordable<unknown>
+    | VNode
+    | VNodeArrayChildren;
  defaultValue?: T;
-  /** 输入组件的值属性名 */
  modelPropName?: string;
 } & Omit<AlertProps, 'beforeClose'>;

-/**
- * 函数签名
- * alert和confirm的函数签名相同。
- * confirm默认会显示取消按钮，而alert默认只有一个按钮
- *  */
 export function alert(options: AlertProps): Promise<void>;
 export function alert(
  message: string,
@@ -141,19 +99,10 @@ export function alert(
  options?: Partial<AlertProps>,
 ): Promise<void>;

-/**
- * 弹出输入框的函数签名。
- * beforeClose的参数会传入用户当前输入的值
- * component指定接受用户输入的组件，默认为Input
- * componentProps 为输入组件设置的属性数据
- * defaultValue 默认的值
- * modelPropName 输入组件的值属性名称。默认为modelValue
- */
 export async function prompt<T = any>(
  options: Omit<AlertProps, 'beforeClose'> & {
    beforeClose?: (
      scope: BeforeCloseScope & {
-        /** 输入组件的当前值 */
        value: T;
      },
    ) => boolean | Promise<boolean | undefined> | undefined;
--- a/docs/src/components/common-ui/vben-api-component.md
+++ b/docs/src/components/common-ui/vben-api-component.md
@@ -14,7 +14,7 @@ outline: deep

 ## 基础用法

-通过 `component` 传入其它组件的定义，并配置相关的其它属性（主要是一些名称映射）。包装组件将通过`api`获取数据（`beforerFetch`、`afterFetch`将分别在`api`运行前、运行后被调用），使用`resultField`从中提取数组，使用`valueField`、`labelField`等来从数据中提取value和label（如果提供了`childrenField`，会将其作为树形结构递归处理每一级数据），之后将处理好的数据通过`optionsPropName`指定的属性传递给目标组件。
+通过 `component` 传入其它组件的定义，并配置相关的其它属性（主要是一些名称映射）。包装组件将通过 `api` 获取数据（`beforeFetch`、`afterFetch` 将分别在 `api` 运行前、运行后被调用），使用 `resultField` 从中提取数组，使用 `valueField`、`labelField` 等来从数据中提取 value 和 label（如果提供了 `childrenField`，会将其作为树形结构递归处理每一级数据），之后将处理好的数据通过 `optionsPropName` 指定的属性传递给目标组件。

 ::: details 包装级联选择器,点击下拉时开始加载远程数据

--- a/docs/src/components/common-ui/vben-count-to-animator.md
+++ b/docs/src/components/common-ui/vben-count-to-animator.md
@@ -4,56 +4,54 @@ outline: deep

 # Vben CountToAnimator 数字动画

-框架提供的数字动画组件，支持数字动画效果。
+`CountToAnimator` 用于展示数字滚动动画效果。

-> 如果文档内没有参数说明，可以尝试在在线示例内寻找
+> 如果文档内没有覆盖到你需要的细节，可以结合在线示例一起查看。

 ::: info 写在前面

-如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，大可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。
-
-:::
+这是一个轻量数字动画组件。如果你需要完全不同的过渡控制方式，也可以直接使用原生动画方案或自行封装。:::

 ## 基础用法

-通过 `start-val` 和 `end-val`设置数字动画的开始值和结束值， 持续时间`3000`ms。
+通过 `start-val` 和 `end-val` 设置数字动画的起始值和结束值，配合 `duration` 控制动画时长。

 <DemoPreview dir="demos/vben-count-to-animator/basic" />

-## 自定义前缀及分隔符
+## 自定义前缀与分隔符

-通过 `prefix` 和 `separator` 设置数字动画的前缀和分隔符。
+通过 `prefix`、`suffix`、`separator` 和 `decimal` 可以控制展示格式。

 <DemoPreview dir="demos/vben-count-to-animator/custom" />

 ### Props

-| 属性名     | 描述           | 类型      | 默认值   |
-| ---------- | -------------- | --------- | -------- |
-| startVal   | 起始值         | `number`  | `0`      |
-| endVal     | 结束值         | `number`  | `2021`   |
-| duration   | 动画持续时间   | `number`  | `1500`   |
-| autoplay   | 自动执行       | `boolean` | `true`   |
-| prefix     | 前缀           | `string`  | -        |
-| suffix     | 后缀           | `string`  | -        |
-| separator  | 分隔符         | `string`  | `,`      |
-| color      | 字体颜色       | `string`  | -        |
-| useEasing  | 是否开启动画   | `boolean` | `true`   |
-| transition | 动画效果       | `string`  | `linear` |
-| decimals   | 保留小数点位数 | `number`  | `0`      |
+| 属性名 | 描述 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| startVal | 起始值 | `number` | `0` |
+| endVal | 结束值 | `number` | `2021` |
+| duration | 动画持续时间 | `number` | `1500` |
+| autoplay | 是否自动播放 | `boolean` | `true` |
+| prefix | 前缀 | `string` | `''` |
+| suffix | 后缀 | `string` | `''` |
+| separator | 千分位分隔符 | `string` | `','` |
+| decimal | 小数点分隔符 | `string` | `'.'` |
+| color | 文本颜色 | `string` | `''` |
+| useEasing | 是否启用过渡预设 | `boolean` | `true` |
+| transition | 过渡预设名称 | `keyof typeof TransitionPresets` | `'linear'` |
+| decimals | 保留小数位数 | `number` | `0` |

 ### Events

-| 事件名         | 描述           | 类型           |
-| -------------- | -------------- | -------------- |
-| started        | 动画已开始     | `()=>void`     |
-| finished       | 动画已结束     | `()=>void`     |
-| ~~onStarted~~  | ~~动画已开始~~ | ~~`()=>void`~~ |
-| ~~onFinished~~ | ~~动画已结束~~ | ~~`()=>void`~~ |
+| 事件名         | 描述                          | 类型             |
+| -------------- | ----------------------------- | ---------------- |
+| started        | 动画开始时触发                | `() => void`     |
+| finished       | 动画结束时触发                | `() => void`     |
+| ~~onStarted~~  | ~~已废弃，请改用 `started`~~  | ~~`() => void`~~ |
+| ~~onFinished~~ | ~~已废弃，请改用 `finished`~~ | ~~`() => void`~~ |

 ### Methods

-| 方法名 | 描述         | 类型       |
-| ------ | ------------ | ---------- |
-| start  | 开始执行动画 | `()=>void` |
-| reset  | 重置         | `()=>void` |
+| 方法名 | 描述                             | 类型         |
+| ------ | -------------------------------- | ------------ |
+| reset  | 重置为 `startVal` 并重新执行动画 | `() => void` |
--- a/docs/src/components/common-ui/vben-drawer.md
+++ b/docs/src/components/common-ui/vben-drawer.md
@@ -55,7 +55,7 @@ Drawer 内的内容一般业务中，会比较复杂，所以我们可以将 dra
 - `VbenDrawer` 组件对于参数的处理优先级是 `slot` > `props` > `state`(通过api更新的状态以及useVbenDrawer参数)。如果你已经传入了 `slot` 或者 `props`，那么 `setState` 将不会生效，这种情况下你可以通过 `slot` 或者 `props` 来更新状态。
 - 如果你使用到了 `connectedComponent` 参数，那么会存在 2 个`useVbenDrawer`, 此时，如果同时设置了相同的参数，那么以内部为准（也就是没有设置 connectedComponent 的代码）。比如 同时设置了 `onConfirm`，那么以内部的 `onConfirm` 为准。`onOpenChange`事件除外，内外都会触发。
 - 使用了`connectedComponent`参数时，可以配置`destroyOnClose`属性来决定当关闭弹窗时，是否要销毁`connectedComponent`组件（重新创建`connectedComponent`组件，这将会把其内部所有的变量、状态、数据等恢复到初始状态。）。
- 如果抽屉的默认行为不符合你的预期，可以在`src\bootstrap.ts`中修改`setDefaultDrawerProps`的参数来设置默认的属性，如默认隐藏全屏按钮，修改默认ZIndex等。
+- 如果抽屉的默认行为不符合你的预期，可以在对应应用的 `apps/<app>/src/bootstrap.ts` 中修改 `setDefaultDrawerProps` 的参数来设置默认属性，例如修改默认 `zIndex` 等。

 :::

@@ -116,7 +116,7 @@ const [Drawer, drawerApi] = useVbenDrawer({

 | 事件名 | 描述 | 类型 | 版本限制 |
 | --- | --- | --- | --- |
-| onBeforeClose | 关闭前触发，返回 `false`则禁止关闭 | `()=>boolean` | --- |
+| onBeforeClose | 关闭前触发，返回 `false` 或 Promise reject 则禁止关闭 | `()=>Promise<boolean \| undefined>\|boolean\|undefined` | >5.5.2 支持 Promise |
 | onCancel | 点击取消按钮触发 | `()=>void` | --- |
 | onClosed | 关闭动画播放完毕时触发 | `()=>void` | >5.5.2 |
 | onConfirm | 点击确认按钮触发 | `()=>void` | --- |
@@ -140,7 +140,7 @@ const [Drawer, drawerApi] = useVbenDrawer({

 | 方法 | 描述 | 类型 | 版本限制 |
 | --- | --- | --- | --- |
-| setState | 动态设置弹窗状态属性 | `(((prev: ModalState) => Partial<ModalState>)\| Partial<ModalState>)=>drawerApi` |
+| setState | 动态设置抽屉状态属性 | `(((prev: DrawerState) => Partial<DrawerState>)\| Partial<DrawerState>)=>drawerApi` |
 | open | 打开弹窗 | `()=>void` | --- |
 | close | 关闭弹窗 | `()=>void` | --- |
 | setData | 设置共享数据 | `<T>(data:T)=>drawerApi` | --- |
--- a/docs/src/components/common-ui/vben-ellipsis-text.md
+++ b/docs/src/components/common-ui/vben-ellipsis-text.md
@@ -4,31 +4,31 @@ outline: deep

 # Vben EllipsisText 省略文本

-框架提供的文本展示组件，可配置超长省略、tooltip提示、展开收起等功能。
+`EllipsisText` 用于展示超长文本，支持省略、Tooltip 提示以及点击展开收起。

-> 如果文档内没有参数说明，可以尝试在在线示例内寻找
+> 如果文档内没有覆盖到你需要的细节，可以结合在线示例一起查看。

 ## 基础用法

-通过默认插槽设置文本内容，`maxWidth`属性设置最大宽度。
+通过默认插槽提供文本内容，`maxWidth` 用于限制文本区域宽度。

 <DemoPreview dir="demos/vben-ellipsis-text/line" />

-## 可折叠的文本块
+## 可折叠文本

-通过`line`设置折叠后的行数，`expand`属性设置是否支持展开收起。
+通过 `line` 设置折叠后的最大行数，通过 `expand` 开启点击展开与收起。

 <DemoPreview dir="demos/vben-ellipsis-text/expand" />

 ## 自定义提示浮层

-通过名为`tooltip`的插槽定制提示信息。
+通过 `tooltip` 插槽自定义提示内容。

 <DemoPreview dir="demos/vben-ellipsis-text/tooltip" />

-## 自动显示 tooltip
+## 仅在省略时显示 Tooltip

-通过`tooltip-when-ellipsis`设置，仅在文本长度超出导致省略号出现时才触发 tooltip。
+通过 `tooltip-when-ellipsis` 控制仅在文本被截断时显示 Tooltip。

 <DemoPreview dir="demos/vben-ellipsis-text/auto-display" />

@@ -38,27 +38,27 @@ outline: deep

 | 属性名 | 描述 | 类型 | 默认值 |
 | --- | --- | --- | --- |
-| expand | 支持点击展开或收起 | `boolean` | `false` |
-| line | 文本最大行数 | `number` | `1` |
+| expand | 是否支持点击展开或收起 | `boolean` | `false` |
+| line | 文本最大显示行数 | `number` | `1` |
 | maxWidth | 文本区域最大宽度 | `number \| string` | `'100%'` |
-| placement | 提示浮层的位置 | `'bottom'\|'left'\|'right'\|'top'` | `'top'` |
-| tooltip | 启用文本提示 | `boolean` | `true` |
-| tooltipWhenEllipsis | 内容超出，自动启用文本提示 | `boolean` | `false` |
-| ellipsisThreshold | 设置 tooltipWhenEllipsis 后才生效，文本截断检测的像素差异阈值，越大则判断越严格，如果碰见异常情况可以自己设置阈值 | `number` | `3` |
-| tooltipBackgroundColor | 提示文本的背景颜色 | `string` | - |
-| tooltipColor | 提示文本的颜色 | `string` | - |
-| tooltipFontSize | 提示文本的大小 | `string` | - |
-| tooltipMaxWidth | 提示浮层的最大宽度。如不设置则保持与文本宽度一致 | `number` | - |
-| tooltipOverlayStyle | 提示框内容区域样式 | `CSSProperties` | `{ textAlign: 'justify' }` |
+| placement | 提示浮层位置 | `'bottom' \| 'left' \| 'right' \| 'top'` | `'top'` |
+| tooltip | 是否启用文本提示 | `boolean` | `true` |
+| tooltipWhenEllipsis | 是否仅在文本被截断时显示提示 | `boolean` | `false` |
+| ellipsisThreshold | 文本截断检测阈值，值越大判定越严格 | `number` | `3` |
+| tooltipBackgroundColor | 提示背景色 | `string` | `''` |
+| tooltipColor | 提示文字颜色 | `string` | `''` |
+| tooltipFontSize | 提示文字大小，单位 `px` | `number` | `14` |
+| tooltipMaxWidth | 提示内容最大宽度，单位 `px` | `number` | - |
+| tooltipOverlayStyle | 提示内容区域样式 | `CSSProperties` | `{ textAlign: 'justify' }` |

 ### Events

-| 事件名       | 描述         | 类型                       |
-| ------------ | ------------ | -------------------------- |
-| expandChange | 展开状态改变 | `(isExpand:boolean)=>void` |
+| 事件名       | 描述               | 类型                          |
+| ------------ | ------------------ | ----------------------------- |
+| expandChange | 展开状态变化时触发 | `(isExpand: boolean) => void` |

 ### Slots

-| 插槽名  | 描述                             |
-| ------- | -------------------------------- |
-| tooltip | 启用文本提示时，用来定制提示内容 |
+| 插槽名  | 描述                               |
+| ------- | ---------------------------------- |
+| tooltip | 开启文本提示时，用于自定义提示内容 |
--- a/docs/src/components/common-ui/vben-form.md
+++ b/docs/src/components/common-ui/vben-form.md
@@ -35,10 +35,15 @@ import type { ComponentType } from './component';
 import { setupVbenForm, useVbenForm as useForm, z } from '@vben/common-ui';
 import { $t } from '@vben/locales';

+import { initComponentAdapter } from './component';
+
+initComponentAdapter();
 setupVbenForm<ComponentType>({
  config: {
    // ant design vue组件库默认都是 v-model:value
    baseModelPropName: 'value',
+    // 一些组件库空值为 null，重置表单时需要和实际组件行为保持一致
+    emptyStateValue: null,
    // 一些组件是 v-model:checked 或者 v-model:fileList
    modelPropNameMap: {
      Checkbox: 'checked',
@@ -87,55 +92,32 @@ import type { BaseFormComponentType } from '@vben/common-ui';
 import type { Component, SetupContext } from 'vue';
 import { h } from 'vue';

-import { globalShareState, IconPicker } from '@vben/common-ui';
+import { globalShareState } from '@vben/common-ui';
 import { $t } from '@vben/locales';
-
-const AutoComplete = defineAsyncComponent(
-  () => import('ant-design-vue/es/auto-complete'),
-);
-const Button = defineAsyncComponent(() => import('ant-design-vue/es/button'));
-const Checkbox = defineAsyncComponent(
-  () => import('ant-design-vue/es/checkbox'),
-);
-const CheckboxGroup = defineAsyncComponent(() =>
-  import('ant-design-vue/es/checkbox').then((res) => res.CheckboxGroup),
-);
-const DatePicker = defineAsyncComponent(
-  () => import('ant-design-vue/es/date-picker'),
-);
-const Divider = defineAsyncComponent(() => import('ant-design-vue/es/divider'));
-const Input = defineAsyncComponent(() => import('ant-design-vue/es/input'));
-const InputNumber = defineAsyncComponent(
-  () => import('ant-design-vue/es/input-number'),
-);
-const InputPassword = defineAsyncComponent(() =>
-  import('ant-design-vue/es/input').then((res) => res.InputPassword),
-);
-const Mentions = defineAsyncComponent(
-  () => import('ant-design-vue/es/mentions'),
-);
-const Radio = defineAsyncComponent(() => import('ant-design-vue/es/radio'));
-const RadioGroup = defineAsyncComponent(() =>
-  import('ant-design-vue/es/radio').then((res) => res.RadioGroup),
-);
-const RangePicker = defineAsyncComponent(() =>
-  import('ant-design-vue/es/date-picker').then((res) => res.RangePicker),
-);
-const Rate = defineAsyncComponent(() => import('ant-design-vue/es/rate'));
-const Select = defineAsyncComponent(() => import('ant-design-vue/es/select'));
-const Space = defineAsyncComponent(() => import('ant-design-vue/es/space'));
-const Switch = defineAsyncComponent(() => import('ant-design-vue/es/switch'));
-const Textarea = defineAsyncComponent(() =>
-  import('ant-design-vue/es/input').then((res) => res.Textarea),
-);
-const TimePicker = defineAsyncComponent(
-  () => import('ant-design-vue/es/time-picker'),
-);
-const TreeSelect = defineAsyncComponent(
-  () => import('ant-design-vue/es/tree-select'),
-);
-const Upload = defineAsyncComponent(() => import('ant-design-vue/es/upload'));
-
+import {
+  AutoComplete,
+  Button,
+  Checkbox,
+  CheckboxGroup,
+  DatePicker,
+  Divider,
+  Input,
+  InputNumber,
+  InputPassword,
+  Mentions,
+  notification,
+  Radio,
+  RadioGroup,
+  RangePicker,
+  Rate,
+  Select,
+  Space,
+  Switch,
+  Textarea,
+  TimePicker,
+  TreeSelect,
+  Upload,
+} from 'ant-design-vue';

 const withDefaultPlaceholder = <T extends Component>(
  component: T,
@@ -171,7 +153,6 @@ export type ComponentType =
  | 'TimePicker'
  | 'TreeSelect'
  | 'Upload'
-  | 'IconPicker';
  | BaseFormComponentType;

 async function initComponentAdapter() {
@@ -189,7 +170,6 @@ async function initComponentAdapter() {
      return h(Button, { ...props, attrs, type: 'default' }, slots);
    },
    Divider,
-    IconPicker,
    Input: withDefaultPlaceholder(Input, 'input'),
    InputNumber: withDefaultPlaceholder(InputNumber, 'input'),
    InputPassword: withDefaultPlaceholder(InputPassword, 'input'),
--- a/docs/src/components/common-ui/vben-modal.md
+++ b/docs/src/components/common-ui/vben-modal.md
@@ -69,7 +69,7 @@ Modal 内的内容一般业务中，会比较复杂，所以我们可以将 moda

 - `VbenModal` 组件对与参数的处理优先级是 `slot` > `props` > `state`(通过api更新的状态以及useVbenModal参数)。如果你已经传入了 `slot` 或者 `props`，那么 `setState` 将不会生效，这种情况下你可以通过 `slot` 或者 `props` 来更新状态。
 - 如果你使用到了 `connectedComponent` 参数，那么会存在 2 个`useVbenModal`, 此时，如果同时设置了相同的参数，那么以内部为准（也就是没有设置 connectedComponent 的代码）。比如 同时设置了 `onConfirm`，那么以内部的 `onConfirm` 为准。`onOpenChange`事件除外，内外都会触发。另外，如果设置了`destroyOnClose`，内部Modal及其子组件会在被关闭后<b>完全销毁</b>。
- 如果弹窗的默认行为不符合你的预期，可以在`src\bootstrap.ts`中修改`setDefaultModalProps`的参数来设置默认的属性，如默认隐藏全屏按钮，修改默认ZIndex等。
+- 如果弹窗的默认行为不符合你的预期，可以在对应应用的 `apps/<app>/src/bootstrap.ts` 中修改 `setDefaultModalProps` 的参数来设置默认属性，例如默认隐藏全屏按钮、修改默认 `zIndex` 等。

 :::

--- 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-` 开头的具名插槽都会被转发给表单。:::
--- a/docs/src/components/layout-ui/page.md
+++ b/docs/src/components/layout-ui/page.md
@@ -4,41 +4,38 @@ outline: deep

 # Page 常规页面组件

-提供一个常规页面布局的组件，包括头部、内容区域、底部三个部分。
+`Page` 是页面内容区最常用的顶层布局容器，内置了标题区、内容区和底部区三部分结构。

 ::: info 写在前面

-本组件是一个基本布局组件。如果有更多的通用页面布局需求（比如双列布局等），可以根据实际需求自行封装。
-
-:::
+这是一个基础页面容器。如果你的业务页面需要更复杂的布局，例如双列、侧边操作区或自定义滚动区域，建议在 `Page` 之上继续封装。:::

 ## 基础用法

-将`Page`作为你的业务页面的根组件即可。
+直接将 `Page` 作为业务页面的根组件使用即可。

 ### Props

 | 属性名 | 描述 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- | --- |
-| title | 页面标题 | `string\|slot` | - | - |
-| description | 页面描述（标题下的内容） | `string\|slot` | - | - |
-| contentClass | 内容区域的class | `string` | - | - |
-| headerClass | 头部区域的class | `string` | - | - |
-| footerClass | 底部区域的class | `string` | - | - |
-| autoContentHeight | 自动调整内容区域的高度 | `boolean` | `false` | - |
+| title | 页面标题 | `string \| slot` | - | - |
+| description | 页面描述 | `string \| slot` | - | - |
+| contentClass | 内容区域的 class | `string` | - | - |
+| headerClass | 头部区域的 class | `string` | - | - |
+| footerClass | 底部区域的 class | `string` | - | - |
+| autoContentHeight | 根据可视内容高度自动计算内容区高度 | `boolean` | `false` | 开启后内容区会根据布局可视高度自动扣减头部和底部高度 |
+| heightOffset | 额外扣减的内容区高度偏移量 | `number` | `0` | 仅在 `autoContentHeight` 开启时生效，单位为 `px` |

 ::: tip 注意

-如果`title`、`description`、`extra`三者均未提供有效内容（通过`props`或者`slots`均可），则页面头部区域不会渲染。
-
-:::
+如果 `title`、`description`、`extra` 三者都没有提供有效内容，无论是通过 `props` 还是 `slots`，头部区域都不会渲染。:::

 ### Slots

-| 插槽名称    | 描述         |
-| ----------- | ------------ |
-| default     | 页面内容     |
-| title       | 页面标题     |
-| description | 页面描述     |
-| extra       | 页面头部右侧 |
-| footer      | 页面底部     |
+| 插槽名称    | 描述             |
+| ----------- | ---------------- |
+| default     | 页面内容         |
+| title       | 页面标题         |
+| description | 页面描述         |
+| extra       | 页面头部右侧内容 |
+| footer      | 页面底部内容     |