Merge remote-tracking branch 'vben/main' into vben-dev
# Conflicts: # .gitignore # .husky/pre-commit # .vscode/extensions.json # .vscode/settings.json # README.ja-JP.md # README.md # README.zh-CN.md # apps/backend-mock/api/auth/codes.ts # apps/backend-mock/api/auth/login.post.ts # apps/backend-mock/api/auth/logout.post.ts # apps/backend-mock/api/auth/refresh.post.ts # apps/backend-mock/api/menu/all.ts # apps/backend-mock/api/status.ts # apps/backend-mock/api/table/list.ts # apps/backend-mock/api/test.get.ts # apps/backend-mock/api/test.post.ts # apps/backend-mock/api/user/info.ts # apps/backend-mock/middleware/1.api.ts # apps/backend-mock/nitro.config.ts # apps/backend-mock/package.json # apps/backend-mock/routes/[...].ts # apps/backend-mock/tsconfig.json # apps/backend-mock/utils/cookie-utils.ts # apps/backend-mock/utils/jwt-utils.ts # apps/backend-mock/utils/mock-data.ts # apps/backend-mock/utils/response.ts # apps/web-antd/.env # apps/web-antd/src/adapter/component/index.ts # apps/web-antd/src/adapter/form.ts # apps/web-antd/src/api/request.ts # apps/web-antd/src/layouts/auth.vue # apps/web-antd/src/layouts/basic.vue # apps/web-antd/src/preferences.ts # apps/web-antd/src/router/guard.ts # apps/web-antd/src/router/routes/modules/demos.ts # apps/web-antd/src/store/auth.ts # apps/web-antd/src/views/demos/antd/index.vue # apps/web-antdv-next/vite.config.ts # apps/web-ele/.env # apps/web-ele/index.html # apps/web-ele/package.json # apps/web-ele/src/adapter/component/index.ts # apps/web-ele/src/adapter/form.ts # apps/web-ele/src/adapter/vxe-table.ts # apps/web-ele/src/api/request.ts # apps/web-ele/src/bootstrap.ts # apps/web-ele/src/layouts/auth.vue # apps/web-ele/src/layouts/basic.vue # apps/web-ele/src/locales/index.ts # apps/web-ele/src/locales/langs/en-US/demos.json # apps/web-ele/src/locales/langs/en-US/page.json # apps/web-ele/src/locales/langs/zh-CN/demos.json # apps/web-ele/src/locales/langs/zh-CN/page.json # apps/web-ele/src/preferences.ts # apps/web-ele/src/router/guard.ts # apps/web-ele/src/router/routes/core.ts # apps/web-ele/src/router/routes/modules/dashboard.ts # apps/web-ele/src/router/routes/modules/demos.ts # apps/web-ele/src/router/routes/modules/vben.ts # apps/web-ele/src/store/auth.ts # apps/web-ele/src/views/_core/authentication/code-login.vue # apps/web-ele/src/views/_core/authentication/forget-password.vue # apps/web-ele/src/views/_core/authentication/register.vue # apps/web-ele/src/views/dashboard/analytics/analytics-trends.vue # apps/web-ele/src/views/dashboard/analytics/analytics-visits-data.vue # apps/web-ele/src/views/dashboard/analytics/analytics-visits-sales.vue # apps/web-ele/src/views/dashboard/analytics/analytics-visits-source.vue # apps/web-ele/src/views/dashboard/analytics/analytics-visits.vue # apps/web-ele/src/views/dashboard/analytics/index.vue # apps/web-ele/src/views/demos/element/index.vue # apps/web-ele/src/views/demos/form/basic.vue # apps/web-ele/tsconfig.json # apps/web-ele/tsconfig.node.json # apps/web-naive/.env # apps/web-naive/index.html # apps/web-naive/package.json # apps/web-naive/src/adapter/component/index.ts # apps/web-naive/src/adapter/form.ts # apps/web-naive/src/adapter/vxe-table.ts # apps/web-naive/src/api/request.ts # apps/web-naive/src/bootstrap.ts # apps/web-naive/src/layouts/auth.vue # apps/web-naive/src/layouts/basic.vue # apps/web-naive/src/locales/index.ts # apps/web-naive/src/locales/langs/en-US/demos.json # apps/web-naive/src/locales/langs/en-US/page.json # apps/web-naive/src/locales/langs/zh-CN/demos.json # apps/web-naive/src/locales/langs/zh-CN/page.json # apps/web-naive/src/preferences.ts # apps/web-naive/src/router/guard.ts # apps/web-naive/src/router/routes/core.ts # apps/web-naive/src/router/routes/modules/dashboard.ts # apps/web-naive/src/router/routes/modules/demos.ts # apps/web-naive/src/router/routes/modules/vben.ts # apps/web-naive/src/store/auth.ts # apps/web-naive/src/views/_core/authentication/code-login.vue # apps/web-naive/src/views/_core/authentication/forget-password.vue # apps/web-naive/src/views/_core/authentication/register.vue # apps/web-naive/src/views/dashboard/analytics/analytics-trends.vue # apps/web-naive/src/views/dashboard/analytics/analytics-visits-data.vue # apps/web-naive/src/views/dashboard/analytics/analytics-visits-sales.vue # apps/web-naive/src/views/dashboard/analytics/analytics-visits-source.vue # apps/web-naive/src/views/dashboard/analytics/analytics-visits.vue # apps/web-naive/src/views/dashboard/analytics/index.vue # apps/web-naive/src/views/demos/form/basic.vue # apps/web-naive/src/views/demos/naive/index.vue # apps/web-naive/tsconfig.json # apps/web-naive/tsconfig.node.json # apps/web-naive/vite.config.ts # docs/.vitepress/components/demo-preview.vue # docs/.vitepress/components/preview-group.vue # docs/.vitepress/config/en.mts # docs/.vitepress/config/index.mts # docs/.vitepress/config/plugins/demo-preview.ts # docs/.vitepress/config/shared.mts # docs/.vitepress/config/zh.mts # docs/.vitepress/theme/components/site-layout.vue # docs/.vitepress/theme/components/vben-contributors.vue # docs/.vitepress/theme/styles/variables.css # docs/package.json # docs/src/_env/adapter/component.ts # docs/src/_env/adapter/form.ts # docs/src/_env/adapter/vxe-table.ts # docs/src/commercial/community.md # docs/src/components/common-ui/vben-count-to-animator.md # docs/src/components/common-ui/vben-drawer.md # docs/src/components/common-ui/vben-form.md # docs/src/components/common-ui/vben-modal.md # docs/src/components/common-ui/vben-vxe-table.md # docs/src/components/layout-ui/page.md # docs/src/demos/vben-drawer/auto-height/drawer.vue # docs/src/demos/vben-drawer/basic/index.vue # docs/src/demos/vben-drawer/dynamic/index.vue # docs/src/demos/vben-drawer/shared-data/drawer.vue # docs/src/demos/vben-drawer/shared-data/index.vue # docs/src/demos/vben-form/api/index.vue # docs/src/demos/vben-form/basic/index.vue # docs/src/demos/vben-form/custom/index.vue # docs/src/demos/vben-form/dynamic/index.vue # docs/src/demos/vben-form/query/index.vue # docs/src/demos/vben-form/rules/index.vue # docs/src/demos/vben-modal/auto-height/modal.vue # docs/src/demos/vben-modal/basic/index.vue # docs/src/demos/vben-modal/dynamic/index.vue # docs/src/demos/vben-modal/shared-data/index.vue # docs/src/demos/vben-modal/shared-data/modal.vue # docs/src/demos/vben-vxe-table/basic/index.vue # docs/src/demos/vben-vxe-table/custom-cell/index.vue # docs/src/demos/vben-vxe-table/edit-row/index.vue # docs/src/demos/vben-vxe-table/fixed/index.vue # docs/src/demos/vben-vxe-table/form/index.vue # docs/src/demos/vben-vxe-table/remote/index.vue # docs/src/demos/vben-vxe-table/tree/index.vue # docs/src/demos/vben-vxe-table/virtual/index.vue # docs/src/en/guide/essentials/development.md # docs/src/en/guide/essentials/external-module.md # docs/src/en/guide/essentials/route.md # docs/src/en/guide/essentials/server.md # docs/src/en/guide/essentials/settings.md # docs/src/en/guide/in-depth/access.md # docs/src/en/guide/in-depth/loading.md # docs/src/en/guide/in-depth/locale.md # docs/src/en/guide/in-depth/theme.md # docs/src/en/guide/introduction/quick-start.md # docs/src/en/guide/introduction/thin.md # docs/src/en/guide/introduction/vben.md # docs/src/en/guide/other/faq.md # docs/src/en/guide/project/dir.md # docs/src/en/guide/project/standard.md # docs/src/en/guide/project/tailwindcss.md # docs/src/en/index.md # docs/src/friend-links/index.md # docs/src/guide/essentials/build.md # docs/src/guide/essentials/development.md # docs/src/guide/essentials/external-module.md # docs/src/guide/essentials/route.md # docs/src/guide/essentials/server.md # docs/src/guide/essentials/settings.md # docs/src/guide/in-depth/access.md # docs/src/guide/in-depth/check-updates.md # docs/src/guide/in-depth/loading.md # docs/src/guide/in-depth/locale.md # docs/src/guide/in-depth/theme.md # docs/src/guide/introduction/quick-start.md # docs/src/guide/introduction/thin.md # docs/src/guide/introduction/vben.md # docs/src/guide/introduction/why.md # docs/src/guide/other/faq.md # docs/src/guide/project/dir.md # docs/src/guide/project/standard.md # docs/src/guide/project/tailwindcss.md # docs/src/index.md # docs/tsconfig.json # package.json # packages/@core/ui-kit/shadcn-ui/src/components/logo/logo.vue # packages/constants/src/core.ts # packages/effects/common-ui/src/components/index.ts # packages/effects/common-ui/src/ui/dashboard/analysis/analysis-overview.vue # packages/effects/common-ui/src/ui/dashboard/workbench/workbench-header.vue # packages/effects/common-ui/src/ui/dashboard/workbench/workbench-project.vue # packages/effects/layouts/src/authentication/authentication.vue # packages/effects/layouts/src/basic/layout.vue # packages/effects/layouts/src/widgets/notification/notification.vue # packages/effects/layouts/src/widgets/notification/types.ts # packages/icons/src/iconify/index.ts # packages/icons/src/svg/index.ts # packages/stores/src/modules/user.ts # playground/src/adapter/component/index.ts # playground/src/store/auth.ts # pnpm-lock.yaml # vben-admin.code-workspace
This commit is contained in:
李琦
112
docs/src/components/common-ui/vben-alert.md
Normal file
112
docs/src/components/common-ui/vben-alert.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Alert 轻量提示框
|
||||
|
||||
`Alert` 提供了一组纯 JavaScript 调用的轻量提示框能力，适合快速创建 `alert`、`confirm`、`prompt` 这类简单交互。
|
||||
|
||||
::: info 适用场景
|
||||
|
||||
`Alert` 与 `Modal` 的能力有部分重叠，但更适合临时确认、简单提示和轻量输入场景。复杂弹窗仍然建议使用 `Vben Modal`。:::
|
||||
|
||||
::: tip 注意
|
||||
|
||||
通过 `alert`、`confirm`、`prompt` 动态创建的弹窗，在已经打开的情况下不支持 HMR 热更新。修改相关代码后，需要关闭后重新打开。:::
|
||||
|
||||
## 基础用法
|
||||
|
||||
使用 `alert` 创建只有确认按钮的提示框。
|
||||
|
||||
<DemoPreview dir="demos/vben-alert/alert" />
|
||||
|
||||
使用 `confirm` 创建带确认和取消按钮的提示框。
|
||||
|
||||
<DemoPreview dir="demos/vben-alert/confirm" />
|
||||
|
||||
使用 `prompt` 创建可接收用户输入的提示框。
|
||||
|
||||
<DemoPreview dir="demos/vben-alert/prompt" />
|
||||
|
||||
## useAlertContext
|
||||
|
||||
当 `content`、`footer` 或 `icon` 使用的是自定义组件时，可以在这些组件内部通过 `useAlertContext()` 获取当前弹窗上下文，并主动触发确认或取消。
|
||||
|
||||
::: tip 注意
|
||||
|
||||
`useAlertContext` 只能在 `setup` 或函数式组件中使用。:::
|
||||
|
||||
### Methods
|
||||
|
||||
| 方法 | 描述 | 类型 | 版本要求 |
|
||||
| --------- | ---------------------- | ------------ | -------- |
|
||||
| doConfirm | 触发当前弹窗的确认操作 | `() => void` | `>5.5.4` |
|
||||
| doCancel | 触发当前弹窗的取消操作 | `() => void` | `>5.5.4` |
|
||||
|
||||
## 类型说明
|
||||
|
||||
```ts
|
||||
export type IconType = 'error' | 'info' | 'question' | 'success' | 'warning';
|
||||
|
||||
export type BeforeCloseScope = {
|
||||
isConfirm: boolean;
|
||||
};
|
||||
|
||||
export type AlertProps = {
|
||||
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;
|
||||
contentMasking?: boolean;
|
||||
footer?: Component | string;
|
||||
icon?: Component | IconType;
|
||||
overlayBlur?: number;
|
||||
showCancel?: boolean;
|
||||
title?: string;
|
||||
};
|
||||
|
||||
export type PromptProps<T = any> = {
|
||||
beforeClose?: (scope: {
|
||||
isConfirm: boolean;
|
||||
value: T | undefined;
|
||||
}) => boolean | Promise<boolean | undefined> | undefined;
|
||||
component?: Component;
|
||||
componentProps?: Recordable<any>;
|
||||
componentSlots?:
|
||||
(() => any) | Recordable<unknown> | VNode | VNodeArrayChildren;
|
||||
defaultValue?: T;
|
||||
modelPropName?: string;
|
||||
} & Omit<AlertProps, 'beforeClose'>;
|
||||
|
||||
export function alert(options: AlertProps): Promise<void>;
|
||||
export function alert(
|
||||
message: string,
|
||||
options?: Partial<AlertProps>,
|
||||
): Promise<void>;
|
||||
export function alert(
|
||||
message: string,
|
||||
title?: string,
|
||||
options?: Partial<AlertProps>,
|
||||
): Promise<void>;
|
||||
|
||||
export async function prompt<T = any>(
|
||||
options: Omit<AlertProps, 'beforeClose'> & {
|
||||
beforeClose?: (
|
||||
scope: BeforeCloseScope & {
|
||||
value: T;
|
||||
},
|
||||
) => boolean | Promise<boolean | undefined> | undefined;
|
||||
component?: Component;
|
||||
componentProps?: Recordable<any>;
|
||||
defaultValue?: T;
|
||||
modelPropName?: string;
|
||||
},
|
||||
): Promise<T | undefined>;
|
||||
```
|
||||
@@ -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 包装级联选择器,点击下拉时开始加载远程数据
|
||||
|
||||
@@ -22,7 +22,7 @@ outline: deep
|
||||
<script lang="ts" setup>
|
||||
import { ApiComponent } from '@vben/common-ui';
|
||||
|
||||
import { Cascader } from 'ant-design-vue';
|
||||
import { Cascader } from 'antdv-next';
|
||||
|
||||
const treeData: Record<string, any> = [
|
||||
{
|
||||
@@ -123,30 +123,51 @@ function fetchApi(): Promise<Record<string, any>> {
|
||||
|
||||
:::
|
||||
|
||||
## 并发和缓存
|
||||
|
||||
有些场景下可能需要使用多个ApiComponent，它们使用了相同的远程数据源（例如用在可编辑的表格中）。如果直接将请求后端接口的函数传递给api属性，则每一个实例都会访问一次接口，这会造成资源浪费，是完全没有必要的。Tanstack Query提供了并发控制、缓存、重试等诸多特性，我们可以将接口请求函数用useQuery包装一下再传递给ApiComponent，这样的话无论页面有多少个使用相同数据源的ApiComponent实例，都只会发起一次远程请求。演示效果请参考 [Playground vue-query](https://www.vben.pro/#/demos/features/vue-query)，具体代码请查看项目文件[concurrency-caching](https://github.com/vbenjs/vue-vben-admin/blob/main/playground/src/views/demos/features/vue-query/concurrency-caching.vue)
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| 属性名 | 描述 | 类型 | 默认值 | 版本要求 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| modelValue(v-model) | 当前值 | `any` | - | - |
|
||||
| component | 欲包装的组件（以下称为目标组件） | `Component` | - | - |
|
||||
| numberToString | 是否将value从数字转为string | `boolean` | `false` | - |
|
||||
| api | 获取数据的函数 | `(arg?: any) => Promise<OptionsItem[] \| Record<string, any>>` | - | - |
|
||||
| params | 传递给api的参数 | `Record<string, any>` | - | - |
|
||||
| resultField | 从api返回的结果中提取options数组的字段名 | `string` | - | - |
|
||||
| labelField | label字段名 | `string` | `label` | - |
|
||||
| childrenField | 子级数据字段名，需要层级数据的组件可用 | `string` | `` | - |
|
||||
| valueField | value字段名 | `string` | `value` | - |
|
||||
| optionsPropName | 目标组件接收options数据的属性名称 | `string` | `options` | - |
|
||||
| modelPropName | 目标组件的双向绑定属性名，默认为modelValue。部分组件可能为value | `string` | `modelValue` | - |
|
||||
| immediate | 是否立即调用api | `boolean` | `true` | - |
|
||||
| alwaysLoad | 每次`visibleEvent`事件发生时都重新请求数据 | `boolean` | `false` | - |
|
||||
| beforeFetch | 在api请求之前的回调函数 | `AnyPromiseFunction<any, any>` | - | - |
|
||||
| afterFetch | 在api请求之后的回调函数 | `AnyPromiseFunction<any, any>` | - | - |
|
||||
| options | 直接传入选项数据，也作为api返回空数据时的后备数据 | `OptionsItem[]` | - | - |
|
||||
| visibleEvent | 触发重新请求数据的事件名 | `string` | - | - |
|
||||
| loadingSlot | 目标组件的插槽名称，用来显示一个"加载中"的图标 | `string` | - | - |
|
||||
| autoSelect | 自动设置选项 | `'first' \| 'last' \| 'one'\| ((item: OptionsItem[]) => OptionsItem) \| false` | `false` | >5.5.4 |
|
||||
|
||||
#### autoSelect 自动设置选项
|
||||
|
||||
如果当前值为undefined，在选项数据成功加载之后，自动从备选项中选择一个作为当前值。默认值为`false`，即不自动选择选项。注意：该属性不应用于多选组件。可选值有：
|
||||
|
||||
- `"first"`：自动选择第一个选项
|
||||
- `"last"`：自动选择最后一个选项
|
||||
- `"one"`：有且仅有一个选项时，自动选择它
|
||||
- `自定义函数`：自定义选择逻辑，函数的参数为options，返回值为选择的选项
|
||||
- `false`：不自动选择选项
|
||||
|
||||
### Methods
|
||||
|
||||
| 方法 | 描述 | 类型 | 版本要求 |
|
||||
| --- | --- | --- | --- |
|
||||
| component | 欲包装的组件 | `Component` | - |
|
||||
| numberToString | 是否将value从数字转为string | `boolean` | `false` |
|
||||
| api | 获取数据的函数 | `(arg?: any) => Promise<OptionsItem[] \| Record<string, any>>` | - |
|
||||
| params | 传递给api的参数 | `Record<string, any>` | - |
|
||||
| resultField | 从api返回的结果中提取options数组的字段名 | `string` | - |
|
||||
| labelField | label字段名 | `string` | `label` |
|
||||
| childrenField | 子级数据字段名，需要层级数据的组件可用 | `string` | `` |
|
||||
| valueField | value字段名 | `string` | `value` |
|
||||
| optionsPropName | 组件接收options数据的属性名称 | `string` | `options` |
|
||||
| modelPropName | 组件的双向绑定属性名，默认为modelValue。部分组件可能为value | `string` | `modelValue` |
|
||||
| immediate | 是否立即调用api | `boolean` | `true` |
|
||||
| alwaysLoad | 每次`visibleEvent`事件发生时都重新请求数据 | `boolean` | `false` |
|
||||
| beforeFetch | 在api请求之前的回调函数 | `AnyPromiseFunction<any, any>` | - |
|
||||
| afterFetch | 在api请求之后的回调函数 | `AnyPromiseFunction<any, any>` | - |
|
||||
| options | 直接传入选项数据，也作为api返回空数据时的后备数据 | `OptionsItem[]` | - |
|
||||
| visibleEvent | 触发重新请求数据的事件名 | `string` | - |
|
||||
| loadingSlot | 组件的插槽名称，用来显示一个"加载中"的图标 | `string` | - |
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
| getComponentRef | 获取被包装的组件的实例 | ()=>T | >5.5.4 |
|
||||
| updateParam | 设置接口请求参数（将与params属性合并） | (newParams: Record<string, any>)=>void | >5.5.4 |
|
||||
| getOptions | 获取已加载的选项数据 | ()=>OptionsItem[] | >5.5.4 |
|
||||
| getValue | 获取当前值 | ()=>any | >5.5.4 |
|
||||
|
||||
172
docs/src/components/common-ui/vben-cropper.md
Normal file
172
docs/src/components/common-ui/vben-cropper.md
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Cropper 图片裁剪
|
||||
|
||||
`VCropper` 是一个纯原生实现的图片裁剪组件，支持自由比例和固定比例裁剪，可通过方法调用获取裁剪后的图片。
|
||||
|
||||
> 如果文档内没有参数说明，可以尝试在在线示例内寻找
|
||||
|
||||
::: info 写在前面
|
||||
|
||||
如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。
|
||||
|
||||
:::
|
||||
|
||||
## 基础用法
|
||||
|
||||
最基本的图片裁剪，支持自由比例调整。
|
||||
|
||||
<DemoPreview dir="demos/vben-cropper/basic" />
|
||||
|
||||
## 固定比例裁剪
|
||||
|
||||
通过 `aspectRatio` 属性设置裁剪比例，格式为 `"宽:高"`，如 `"1:1"`、`"16:9"`、`"3:4"` 等。
|
||||
|
||||
<DemoPreview dir="demos/vben-cropper/aspect-ratio" />
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| ------------- | ------------------------------------- | -------- | ------ |
|
||||
| `img` | 图片地址（必填） | `string` | - |
|
||||
| `width` | 容器宽度 | `number` | `500` |
|
||||
| `height` | 容器高度 | `number` | `400` |
|
||||
| `aspectRatio` | 裁剪比例，格式如 `"1:1"`、`"16:9"` 等 | `string` | - |
|
||||
|
||||
### Methods
|
||||
|
||||
通过 `ref` 调用组件方法：
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue';
|
||||
import { VCropper } from '@vben/common-ui';
|
||||
|
||||
const cropperRef = ref<InstanceType<typeof VCropper>>();
|
||||
|
||||
const handleCrop = async () => {
|
||||
const result = await cropperRef.value?.getCropImage();
|
||||
// result 为 Blob 或 base64 字符串
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
#### getCropImage
|
||||
|
||||
裁剪并获取图片。
|
||||
|
||||
```ts
|
||||
interface GetCropImageOptions {
|
||||
/** 输出图片格式 */
|
||||
format?: 'image/jpeg' | 'image/png';
|
||||
/** 压缩质量（0-1），仅对 jpeg 格式有效 */
|
||||
quality?: number;
|
||||
/** 输出类型 */
|
||||
outputType?: 'base64' | 'blob';
|
||||
/** 目标宽度（可选，不传则为原始裁剪宽度） */
|
||||
targetWidth?: number;
|
||||
/** 目标高度（可选，不传则为原始裁剪高度） */
|
||||
targetHeight?: number;
|
||||
}
|
||||
|
||||
getCropImage(
|
||||
format?: 'image/jpeg' | 'image/png',
|
||||
quality?: number,
|
||||
outputType?: 'base64' | 'blob',
|
||||
targetWidth?: number,
|
||||
targetHeight?: number,
|
||||
): Promise<Blob | string | undefined>
|
||||
```
|
||||
|
||||
**参数说明：**
|
||||
|
||||
| 参数 | 类型 | 默认值 | 描述 |
|
||||
| --- | --- | --- | --- |
|
||||
| `format` | `'image/jpeg' \| 'image/png'` | `'image/png'` | 输出图片格式 |
|
||||
| `quality` | `number` | `0.92` | 压缩质量（0-1），仅 jpeg 有效 |
|
||||
| `outputType` | `'base64' \| 'blob'` | `'blob'` | 输出类型，base64 字符串或 Blob 对象 |
|
||||
| `targetWidth` | `number` | - | 目标宽度，不传则使用原始裁剪宽度 |
|
||||
| `targetHeight` | `number` | - | 目标高度，不传则使用原始裁剪高度 |
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 裁剪操作
|
||||
|
||||
- **拖拽移动** - 拖拽裁剪框中心区域移动裁剪位置
|
||||
- **边角调整** - 拖拽四角调整裁剪框大小
|
||||
- **边缘调整** - 拖拽四边中点调整单边
|
||||
|
||||
### 比例控制
|
||||
|
||||
- **自由比例** - 不设置 `aspectRatio` 时，可自由调整任意比例
|
||||
- **固定比例** - 设置 `aspectRatio` 后，裁剪框始终保持设定比例
|
||||
|
||||
### 高清屏适配
|
||||
|
||||
组件自动适配 Retina 等高清屏幕，保证输出图片清晰无模糊。
|
||||
|
||||
### 图片适配
|
||||
|
||||
- 图片自动等比缩放以完整显示在容器内
|
||||
- 支持本地图片和网络图片
|
||||
- 网络图片需目标服务端支持 CORS 才能导出裁剪结果
|
||||
|
||||
## 使用示例
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue';
|
||||
import { VCropper } from '@vben/common-ui';
|
||||
|
||||
const cropperRef = ref<InstanceType<typeof VCropper>>();
|
||||
const imageUrl = ref('https://example.com/image.jpg');
|
||||
const croppedImage = ref('');
|
||||
|
||||
// 获取裁剪后的 Blob 对象
|
||||
const handleCropBlob = async () => {
|
||||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob');
|
||||
if (blob instanceof Blob) {
|
||||
// 上传到服务器或创建预览URL
|
||||
const url = URL.createObjectURL(blob);
|
||||
croppedImage.value = url;
|
||||
}
|
||||
};
|
||||
|
||||
// 获取裁剪后的 base64 字符串
|
||||
const handleCropBase64 = async () => {
|
||||
const base64 = await cropperRef.value?.getCropImage('image/png', 1, 'base64');
|
||||
if (typeof base64 === 'string') {
|
||||
croppedImage.value = base64;
|
||||
}
|
||||
};
|
||||
|
||||
// 导出指定尺寸
|
||||
const handleCropWithSize = async () => {
|
||||
const blob = await cropperRef.value?.getCropImage(
|
||||
'image/jpeg',
|
||||
0.9,
|
||||
'blob',
|
||||
200, // 目标宽度
|
||||
200, // 目标高度
|
||||
);
|
||||
};
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<VCropper
|
||||
ref="cropperRef"
|
||||
:img="imageUrl"
|
||||
:width="500"
|
||||
:height="400"
|
||||
aspect-ratio="1:1"
|
||||
/>
|
||||
<button @click="handleCropBlob">裁剪</button>
|
||||
<img v-if="croppedImage" :src="croppedImage" />
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
102
docs/src/components/common-ui/vben-descriptions.md
Normal file
102
docs/src/components/common-ui/vben-descriptions.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Descriptions 描述列表
|
||||
|
||||
`Descriptions` 用于成组展示只读的字段信息，常用于详情页、信息预览等场景。组件基于 shadcn-ui 构建，API 参考 Ant Design Vue 的 Descriptions，支持响应式列数、跨列、边框、垂直布局等能力。
|
||||
|
||||
> 如果文档内没有覆盖到你需要的细节，可以结合在线示例一起查看。
|
||||
|
||||
::: info 写在前面
|
||||
|
||||
组件提供两种使用方式：通过 `items` 数据驱动（推荐），或通过子组件 `VbenDescriptionsItem` 声明列表项。两者可按需选择，`items` 优先级更高。:::
|
||||
|
||||
## 基础用法
|
||||
|
||||
通过 `items` 传入字段数组，每项包含 `label` 与 `content`。默认按断点自适应列数（`xs` 1 列、`sm` 2 列、`md` 及以上 3 列）。
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/basic" />
|
||||
|
||||
## 带边框
|
||||
|
||||
设置 `bordered` 展示边框样式，配合 `title` 标题与 `#extra` 插槽（位于标题右侧的操作区域）。
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/bordered" />
|
||||
|
||||
## 垂直布局
|
||||
|
||||
通过 `layout="vertical"` 让标签位于内容上方。
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/vertical" />
|
||||
|
||||
## 不同尺寸
|
||||
|
||||
通过 `size` 设置 `small`、`middle`、`large` 三种尺寸。
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/size" />
|
||||
|
||||
## 跨列与响应式
|
||||
|
||||
单项通过 `span` 设置跨列数，`'filled'` 表示占满当前行剩余空间；`column` 支持传入按断点配置的对象实现响应式列数。
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/span" />
|
||||
|
||||
## 子组件用法
|
||||
|
||||
不传 `items` 时，可在默认插槽中使用 `VbenDescriptionsItem` 声明列表项，内容支持默认插槽或 `#content` 插槽自定义。
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/custom" />
|
||||
|
||||
## API
|
||||
|
||||
### Descriptions Props
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| items | 数据驱动的列表项；不传则读取默认插槽 | `DescriptionsItemType[]` | - |
|
||||
| bordered | 是否展示边框 | `boolean` | `false` |
|
||||
| column | 一行的列数，支持按断点配置 | `number \| Partial<Record<Breakpoint, number>>` | `{ xs: 1, sm: 2, md: 3, xxxl: 4 }` |
|
||||
| layout | 布局方式 | `'horizontal' \| 'vertical'` | `'horizontal'` |
|
||||
| size | 尺寸 | `'small' \| 'middle' \| 'large'` | `'middle'` |
|
||||
| colon | 是否显示冒号（仅非边框的水平布局生效） | `boolean` | `true` |
|
||||
| title | 标题 | `string` | - |
|
||||
| extra | 标题右侧的操作区域 | `string` | - |
|
||||
| labelStyle | 统一的标签样式 | `CSSProperties` | - |
|
||||
| contentStyle | 统一的内容样式 | `CSSProperties` | - |
|
||||
| class | 根节点自定义类名 | `string` | - |
|
||||
|
||||
### Descriptions Slots
|
||||
|
||||
| 插槽名 | 描述 |
|
||||
| ------- | ---------------------------------- |
|
||||
| title | 自定义标题 |
|
||||
| extra | 自定义标题右侧操作区域 |
|
||||
| default | 放置 `VbenDescriptionsItem` 子组件 |
|
||||
|
||||
### DescriptionsItem
|
||||
|
||||
`items` 数组中的每一项，或子组件 `VbenDescriptionsItem` 的属性。
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| label | 标签 | `string \| number \| (() => VNode) \| Component` | - |
|
||||
| content | 内容 | `string \| number \| (() => VNode) \| Component` | - |
|
||||
| span | 跨列数，`'filled'` 占满当前行剩余 | `number \| 'filled' \| Partial<Record<Breakpoint, number>>` | `1` |
|
||||
| labelStyle | 标签样式 | `CSSProperties` | - |
|
||||
| contentStyle | 内容样式 | `CSSProperties` | - |
|
||||
| key | 唯一标识 | `string \| number` | - |
|
||||
|
||||
### DescriptionsItem Slots
|
||||
|
||||
仅子组件用法可用。
|
||||
|
||||
| 插槽名 | 描述 |
|
||||
| ------- | ------------------------ |
|
||||
| default | 内容（等价于 `content`） |
|
||||
| content | 自定义内容 |
|
||||
| label | 自定义标签 |
|
||||
|
||||
::: tip Breakpoint
|
||||
|
||||
响应式断点 `Breakpoint` 取值为 `'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl'`，断点像素与 Ant Design 一致（`sm` 576、`md` 768、`lg` 992、`xl` 1200、`xxl` 1600、`xxxl` 2000）。:::
|
||||
@@ -4,53 +4,61 @@ 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-when-ellipsis` 控制仅在文本被截断时显示 Tooltip。
|
||||
|
||||
<DemoPreview dir="demos/vben-ellipsis-text/auto-display" />
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| 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` |
|
||||
| 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 | 开启文本提示时，用于自定义提示内容 |
|
||||
|
||||
165
docs/src/components/common-ui/vben-table-action.md
Normal file
165
docs/src/components/common-ui/vben-table-action.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben TableAction 表格操作
|
||||
|
||||
`TableAction` 用于在表格操作列中渲染一组操作按钮，参考 vben2 的 TableAction 设计。基于 shadcn-ui 构建，支持权限控制、气泡确认、提示、下拉「更多」、分割线等能力，可在表格内外任意场景复用。
|
||||
|
||||
> 如果文档内没有覆盖到你需要的细节，可以结合在线示例一起查看。
|
||||
|
||||
::: info 写在前面
|
||||
|
||||
组件本身不依赖任何业务逻辑（不直接读取权限 store），权限通过注入 `hasPermission` 实现，从而保持核心层零耦合、可跨框架复用。在 vxe-table 中推荐通过列插槽（`slots: { default: 'action' }`）在页面里渲染，不改变表格原有的渲染机制。:::
|
||||
|
||||
## 基础用法
|
||||
|
||||
通过 `actions` 传入操作项数组，每项包含 `text`、`onClick` 等；`danger` 标记危险操作，`divider` 显示按钮间分割线。
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/basic" />
|
||||
|
||||
## 提示
|
||||
|
||||
通过 `tooltip` 为操作项添加提示，支持字符串或 `{ content, side }` 配置。
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/tooltip" />
|
||||
|
||||
## 气泡确认
|
||||
|
||||
通过 `popConfirm` 开启点击前的气泡确认，常用于删除等危险操作。
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/popconfirm" />
|
||||
|
||||
## 更多下拉
|
||||
|
||||
通过 `dropdownActions` 将次要操作收纳到「更多」下拉中，`moreText` 可自定义按钮文案。
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/dropdown" />
|
||||
|
||||
## 权限控制
|
||||
|
||||
为操作项设置 `auth` 权限码，并注入 `hasPermission` 判断函数，无权限的操作会被隐藏。
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/permission" />
|
||||
|
||||
## 在 vxe-table 中使用
|
||||
|
||||
不改变 vxe-table 原有渲染方式，推荐在列配置中声明插槽，在页面通过插槽渲染。
|
||||
|
||||
::: tip 推荐：使用适配器封装的版本项目的 `#/adapter/vxe-table` 已对 `VbenTableAction` 做了二次封装，内部统一注入了 `hasPermission`（基于 `useAccess().hasAccessByCodes`）。因此从适配器引入时**无需再传入 `:has-permission`**，只需通过操作项的 `auth` 字段声明权限码即可。:::
|
||||
|
||||
```ts
|
||||
// data.ts —— 列配置声明插槽
|
||||
{
|
||||
align: 'center',
|
||||
field: 'operation',
|
||||
fixed: 'right',
|
||||
slots: { default: 'action' },
|
||||
title: $t('system.user.operation'),
|
||||
width: 180,
|
||||
}
|
||||
```
|
||||
|
||||
```vue
|
||||
<!-- list.vue —— 从适配器引入，权限自动注入，无需传入 has-permission -->
|
||||
<script setup lang="ts">
|
||||
import { VbenTableAction } from '#/adapter/vxe-table';
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<Grid>
|
||||
<template #action="{ row }">
|
||||
<template #action="{ row }">
|
||||
<VbenTableAction
|
||||
:actions="[
|
||||
{
|
||||
text: $t('common.detail'),
|
||||
icon: 'lucide:eye',
|
||||
onClick: () => onDetail(row),
|
||||
},
|
||||
{
|
||||
text: $t('common.edit'),
|
||||
icon: 'lucide:edit',
|
||||
onClick: () => onEdit(row),
|
||||
},
|
||||
]"
|
||||
:dropdown-actions="[
|
||||
{
|
||||
text: $t('common.delete'),
|
||||
icon: 'lucide:trash-2',
|
||||
danger: true,
|
||||
onClick: () => onDelete(row),
|
||||
auth: ['AC_100100'],
|
||||
},
|
||||
]"
|
||||
align="center"
|
||||
/>
|
||||
</template>
|
||||
</template>
|
||||
</Grid>
|
||||
</template>
|
||||
```
|
||||
|
||||
若直接从 `@vben/common-ui` 引入核心组件（不经过适配器），组件不依赖任何业务逻辑，需自行注入 `hasPermission`：
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { useAccess } from '@vben/access';
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
const { hasAccessByCodes } = useAccess();
|
||||
function hasPermission(auth?: string | string[]) {
|
||||
if (!auth) return true;
|
||||
return hasAccessByCodes(Array.isArray(auth) ? auth : [auth]);
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<VbenTableAction
|
||||
v-bind="useActions(row, onActionClick)"
|
||||
:has-permission="hasPermission"
|
||||
align="center"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### TableAction Props
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| actions | 主操作按钮 | `ActionItem[]` | `[]` |
|
||||
| dropdownActions | 「更多」下拉中的操作 | `ActionItem[]` | `[]` |
|
||||
| align | 对齐方式 | `'start' \| 'center' \| 'end'` | `'end'` |
|
||||
| divider | 按钮之间是否显示分割线 | `boolean` | `false` |
|
||||
| moreText | 「更多」按钮文案（提供时显示在图标右侧） | `string` | - |
|
||||
| hasPermission | 权限判断函数，返回 `false` 则隐藏对应 `auth` 的操作（从 `#/adapter/vxe-table` 引入时已自动注入，无需手动传入） | `(auth?: string \| string[]) => boolean` | - |
|
||||
| class | 根节点自定义类名 | `string` | - |
|
||||
|
||||
### ActionItem
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| text | 按钮文本 | `string` | - |
|
||||
| icon | 图标组件 | `string`\| `VbenIcon` | - |
|
||||
| onClick | 点击回调 | `() => void` | - |
|
||||
| auth | 权限码，配合 `hasPermission` 过滤 | `string \| string[]` | - |
|
||||
| ifShow | 是否显示 | `boolean \| (() => boolean)` | `true` |
|
||||
| disabled | 是否禁用 | `boolean` | `false` |
|
||||
| loading | 加载状态 | `boolean` | `false` |
|
||||
| danger | 危险操作（红色文字） | `boolean` | `false` |
|
||||
| tooltip | 提示 | `string \| { content: string; side?: 'top' \| 'bottom' \| 'left' \| 'right' }` | - |
|
||||
| popConfirm | 气泡确认 | `TableActionPopConfirm` | - |
|
||||
| variant | 按钮样式变体 | `ButtonVariants['variant']` | `'link'` |
|
||||
| size | 按钮尺寸 | `ButtonVariants['size']` | `'sm'` |
|
||||
| key | 唯一标识 | `string \| number` | - |
|
||||
|
||||
### TableActionPopConfirm
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| title | 提示标题 | `string` | `'Are you sure?'` |
|
||||
| okText | 确认按钮文案 | `string` | `'OK'` |
|
||||
| cancelText | 取消按钮文案 | `string` | `'Cancel'` |
|
||||
| confirm | 确认回调；未提供时回退到 `action.onClick` | `() => void` | - |
|
||||
199
docs/src/components/common-ui/vben-tiptap.md
Normal file
199
docs/src/components/common-ui/vben-tiptap.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Tiptap 富文本编辑器
|
||||
|
||||
基于 [Tiptap](https://tiptap.dev/) 构建的富文本编辑器组件，支持丰富的文本格式化、图片插入、图片上传等功能。
|
||||
|
||||
> 如果文档内没有参数说明，可以尝试在在线示例内寻找
|
||||
|
||||
::: info 写在前面
|
||||
|
||||
如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。
|
||||
|
||||
:::
|
||||
|
||||
## 基础用法
|
||||
|
||||
<DemoPreview dir="demos/vben-tiptap/basic" />
|
||||
|
||||
## 组件列表
|
||||
|
||||
### VbenTiptap
|
||||
|
||||
富文本编辑器主组件。
|
||||
|
||||
### VbenTiptapPreview
|
||||
|
||||
富文本内容预览组件，用于只读展示编辑器内容。
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 属性名 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| `modelValue` (v-model) | 编辑器内容（HTML字符串） | `string` | `''` |
|
||||
| `editable` | 是否可编辑 | `boolean` | `true` |
|
||||
| `toolbar` | 是否显示工具栏 | `boolean` | `true` |
|
||||
| `previewable` | 是否显示预览按钮 | `boolean` | `true` |
|
||||
| `placeholder` | 占位提示文本 | `string` | - |
|
||||
| `minHeight` | 最小高度 | `number \| string` | `240` |
|
||||
| `maxHeight` | 最大高度 | `number \| string` | `400` |
|
||||
| `extensions` | 自定义 Tiptap 扩展配置 | `Extensions` | - |
|
||||
| `imageUpload` | 图片上传配置 | `ImageUploadOptions` | - |
|
||||
|
||||
### Events
|
||||
|
||||
| 事件名 | 说明 | 参数类型 |
|
||||
| -------- | -------------- | ----------------------- |
|
||||
| `change` | 内容变化时触发 | `VbenTiptapChangeEvent` |
|
||||
|
||||
#### VbenTiptapChangeEvent
|
||||
|
||||
```ts
|
||||
interface VbenTiptapChangeEvent {
|
||||
html: string; // HTML 内容
|
||||
json: JSONContent; // JSON 结构内容
|
||||
text: string; // 纯文本内容
|
||||
}
|
||||
```
|
||||
|
||||
### ImageUploadOptions
|
||||
|
||||
图片上传配置项：
|
||||
|
||||
```ts
|
||||
interface ImageUploadOptions {
|
||||
/** 允许的文件类型，默认 'image/*' */
|
||||
accept?: string;
|
||||
/** 最大文件大小(字节)，默认 5MB */
|
||||
maxSize?: number;
|
||||
/** 上传失败回调，未提供时使用 alert 弹窗提示 */
|
||||
onUploadError?: (error: unknown) => void;
|
||||
/** 上传函数，返回图片 URL */
|
||||
upload: (
|
||||
file: File,
|
||||
onProgress?: (percent: number) => void,
|
||||
) => Promise<string>;
|
||||
}
|
||||
```
|
||||
|
||||
### VbenTiptapPreview Props
|
||||
|
||||
| 属性名 | 说明 | 类型 | 默认值 |
|
||||
| ----------- | ------------------ | ------------------ | ------ |
|
||||
| `content` | 要预览的 HTML 内容 | `string` | `''` |
|
||||
| `minHeight` | 最小高度 | `number \| string` | `160` |
|
||||
| `class` | 自定义类名 | `any` | - |
|
||||
|
||||
## 工具栏功能
|
||||
|
||||
编辑器工具栏提供以下功能：
|
||||
|
||||
### 格式化
|
||||
|
||||
- **撤销/重做** - 撤销或重做编辑操作
|
||||
- **清除格式** - 清除选中文本的所有格式
|
||||
- **粗体** - 加粗文本
|
||||
- **斜体** - 斜体文本
|
||||
- **下划线** - 下划线文本
|
||||
- **删除线** - 删除线文本
|
||||
- **行内代码** - 行内代码标记
|
||||
|
||||
### 结构
|
||||
|
||||
- **标题** - 段落、H1-H4 标题切换
|
||||
- **有序列表** - 有序编号列表
|
||||
- **无序列表** - 无序符号列表
|
||||
- **引用块** - 引用块样式
|
||||
- **代码块** - 多行代码块
|
||||
|
||||
### 链接与图片
|
||||
|
||||
- **插入链接** - 插入或编辑超链接
|
||||
- **移除链接** - 移除选中文本的链接
|
||||
- **插入图片** - 通过 URL 插入图片
|
||||
|
||||
### 样式
|
||||
|
||||
- **文字颜色** - 设置文字颜色（预设色板）
|
||||
- **背景颜色** - 设置文字背景高亮颜色
|
||||
|
||||
### 对齐
|
||||
|
||||
- **左对齐** - 文本左对齐
|
||||
- **居中对齐** - 文本居中对齐
|
||||
- **右对齐** - 文本右对齐
|
||||
|
||||
### 其他
|
||||
|
||||
- **预览** - 在弹窗中预览编辑内容
|
||||
|
||||
## 图片上传
|
||||
|
||||
<DemoPreview dir="demos/vben-tiptap/image-upload" />
|
||||
|
||||
当配置 `imageUpload` 时，工具栏的图片按钮会变为下拉菜单，包含「本地上传」和「URL 插入」两个选项。
|
||||
|
||||
### 上传方式
|
||||
|
||||
支持三种图片上传方式：
|
||||
|
||||
1. **文件选择** - 点击工具栏本地上传按钮
|
||||
2. **拖拽上传** - 直接拖拽图片到编辑器区域
|
||||
3. **粘贴上传** - 粘贴图片到编辑器
|
||||
|
||||
### 上传进度显示
|
||||
|
||||
上传过程中会显示：
|
||||
|
||||
- **加载指示器** - 旋转动画指示上传进行中
|
||||
- **进度条** - 当上传函数提供 `onProgress` 回调时，显示进度条
|
||||
|
||||
### 文件校验
|
||||
|
||||
- `accept` - 指定允许的文件类型（MIME类型）
|
||||
- `maxSize` - 最大文件大小限制（字节）
|
||||
- 校验失败时会触发 `onUploadError` 回调或默认 alert 提示
|
||||
|
||||
::: warning 注意事项
|
||||
|
||||
- 仅支持单张图片上传，多图拖拽/粘贴时会提示并仅处理第一张
|
||||
- 上传中不要保存编辑器内容（`getHTML()`），因为此时图片 URL 为临时 blob URL
|
||||
- 自定义 `extensions` 时，图片上传功能将不显示（因为可能缺少 uploadImage 命令）
|
||||
|
||||
:::
|
||||
|
||||
## 自定义扩展
|
||||
|
||||
通过 `extensions` 属性可以传入自定义的 Tiptap 扩展配置：
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { VbenTiptap } from '@vben/plugins/tiptap';
|
||||
import StarterKit from '@tiptap/starter-kit';
|
||||
import Underline from '@tiptap/extension-underline';
|
||||
|
||||
const extensions = [
|
||||
StarterKit,
|
||||
Underline,
|
||||
// 其他扩展...
|
||||
];
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<VbenTiptap v-model="content" :extensions="extensions" />
|
||||
</template>
|
||||
```
|
||||
|
||||
::: warning 自定义扩展注意事项
|
||||
|
||||
使用自定义 `extensions` 时：
|
||||
|
||||
- 默认扩展配置将不会生效
|
||||
- 图片上传功能不可用（工具栏不显示上传选项）
|
||||
- 需自行配置所需的编辑器功能
|
||||
|
||||
:::
|
||||
36
docs/src/demos/vben-alert/alert/index.vue
Normal file
36
docs/src/demos/vben-alert/alert/index.vue
Normal file
@@ -0,0 +1,36 @@
|
||||
<script lang="ts" setup>
|
||||
import { h } from 'vue';
|
||||
|
||||
import { alert, VbenButton } from '@vben/common-ui';
|
||||
|
||||
import { Result } from 'antdv-next';
|
||||
|
||||
function showAlert() {
|
||||
alert('This is an alert message');
|
||||
}
|
||||
|
||||
function showIconAlert() {
|
||||
alert({
|
||||
content: 'This is an alert message with icon',
|
||||
icon: 'success',
|
||||
});
|
||||
}
|
||||
|
||||
function showCustomAlert() {
|
||||
alert({
|
||||
buttonAlign: 'center',
|
||||
content: h(Result, {
|
||||
status: 'success',
|
||||
subTitle: '已成功创建订单。订单ID：2017182818828182881',
|
||||
title: '操作成功',
|
||||
}),
|
||||
});
|
||||
}
|
||||
</script>
|
||||
<template>
|
||||
<div class="flex gap-4">
|
||||
<VbenButton @click="showAlert">Alert</VbenButton>
|
||||
<VbenButton @click="showIconAlert">Alert With Icon</VbenButton>
|
||||
<VbenButton @click="showCustomAlert">Alert With Custom Content</VbenButton>
|
||||
</div>
|
||||
</template>
|
||||
75
docs/src/demos/vben-alert/confirm/index.vue
Normal file
75
docs/src/demos/vben-alert/confirm/index.vue
Normal file
@@ -0,0 +1,75 @@
|
||||
<script lang="ts" setup>
|
||||
import { h, ref } from 'vue';
|
||||
|
||||
import { alert, confirm, VbenButton } from '@vben/common-ui';
|
||||
|
||||
import { Checkbox, message } from 'antdv-next';
|
||||
|
||||
function showConfirm() {
|
||||
confirm('This is an alert message')
|
||||
.then(() => {
|
||||
alert('Confirmed');
|
||||
})
|
||||
.catch(() => {
|
||||
alert('Canceled');
|
||||
});
|
||||
}
|
||||
|
||||
function showIconConfirm() {
|
||||
confirm({
|
||||
content: 'This is an alert message with icon',
|
||||
icon: 'success',
|
||||
});
|
||||
}
|
||||
|
||||
function showfooterConfirm() {
|
||||
const checked = ref(false);
|
||||
confirm({
|
||||
cancelText: '不要虾扯蛋',
|
||||
confirmText: '是的，我们都是NPC',
|
||||
content:
|
||||
'刚才发生的事情，为什么我似乎早就经历过一般？\n我甚至能在事情发生过程中潜意识里预知到接下来会发生什么。\n\n听起来挺玄乎的，你有过这种感觉吗？',
|
||||
footer: () =>
|
||||
h(
|
||||
Checkbox,
|
||||
{
|
||||
checked: checked.value,
|
||||
class: 'flex-1',
|
||||
'onUpdate:checked': (v) => (checked.value = v),
|
||||
},
|
||||
'不再提示',
|
||||
),
|
||||
icon: 'question',
|
||||
title: '未解之谜',
|
||||
}).then(() => {
|
||||
if (checked.value) {
|
||||
message.success('我不会再拿这个问题烦你了');
|
||||
} else {
|
||||
message.info('下次还要继续问你哟');
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function showAsyncConfirm() {
|
||||
confirm({
|
||||
beforeClose({ isConfirm }) {
|
||||
if (isConfirm) {
|
||||
// 这里可以执行一些异步操作。如果最终返回了false，将阻止关闭弹窗
|
||||
return new Promise((resolve) => setTimeout(resolve, 2000));
|
||||
}
|
||||
},
|
||||
content: 'This is an alert message with async confirm',
|
||||
icon: 'success',
|
||||
}).then(() => {
|
||||
alert('Confirmed');
|
||||
});
|
||||
}
|
||||
</script>
|
||||
<template>
|
||||
<div class="flex gap-4">
|
||||
<VbenButton @click="showConfirm">Confirm</VbenButton>
|
||||
<VbenButton @click="showIconConfirm">Confirm With Icon</VbenButton>
|
||||
<VbenButton @click="showfooterConfirm">Confirm With Footer</VbenButton>
|
||||
<VbenButton @click="showAsyncConfirm">Async Confirm</VbenButton>
|
||||
</div>
|
||||
</template>
|
||||
118
docs/src/demos/vben-alert/prompt/index.vue
Normal file
118
docs/src/demos/vben-alert/prompt/index.vue
Normal file
@@ -0,0 +1,118 @@
|
||||
<script lang="ts" setup>
|
||||
import { h } from 'vue';
|
||||
|
||||
import { alert, prompt, useAlertContext, VbenButton } from '@vben/common-ui';
|
||||
|
||||
import { BadgeJapaneseYen } from '@lucide/vue';
|
||||
import { Input, RadioGroup, Select } from 'antdv-next';
|
||||
|
||||
function showPrompt() {
|
||||
prompt({
|
||||
content: '请输入一些东西',
|
||||
})
|
||||
.then((val) => {
|
||||
alert(`已收到你的输入：${val}`);
|
||||
})
|
||||
.catch(() => {
|
||||
alert('Canceled');
|
||||
});
|
||||
}
|
||||
|
||||
function showSlotsPrompt() {
|
||||
prompt({
|
||||
component: () => {
|
||||
// 获取弹窗上下文。注意：只能在setup或者函数式组件中调用
|
||||
const { doConfirm } = useAlertContext();
|
||||
return h(
|
||||
Input,
|
||||
{
|
||||
onKeydown(e: KeyboardEvent) {
|
||||
if (e.key === 'Enter') {
|
||||
e.preventDefault();
|
||||
// 调用弹窗提供的确认方法
|
||||
doConfirm();
|
||||
}
|
||||
},
|
||||
placeholder: '请输入',
|
||||
prefix: '充值金额：',
|
||||
type: 'number',
|
||||
},
|
||||
{
|
||||
addonAfter: () => h(BadgeJapaneseYen),
|
||||
},
|
||||
);
|
||||
},
|
||||
content:
|
||||
'此弹窗演示了如何使用自定义插槽，并且可以使用useAlertContext获取到弹窗的上下文。\n在输入框中按下回车键会触发确认操作。',
|
||||
icon: 'question',
|
||||
modelPropName: 'value',
|
||||
}).then((val) => {
|
||||
if (val) alert(`你输入的是${val}`);
|
||||
});
|
||||
}
|
||||
|
||||
function showSelectPrompt() {
|
||||
prompt({
|
||||
component: Select,
|
||||
componentProps: {
|
||||
options: [
|
||||
{ label: 'Option A', value: 'Option A' },
|
||||
{ label: 'Option B', value: 'Option B' },
|
||||
{ label: 'Option C', value: 'Option C' },
|
||||
],
|
||||
placeholder: '请选择',
|
||||
// 弹窗会设置body的pointer-events为none，这回影响下拉框的点击事件
|
||||
popupClassName: 'pointer-events-auto',
|
||||
},
|
||||
content: '此弹窗演示了如何使用component传递自定义组件',
|
||||
icon: 'question',
|
||||
modelPropName: 'value',
|
||||
}).then((val) => {
|
||||
if (val) {
|
||||
alert(`你选择了${val}`);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function sleep(ms: number) {
|
||||
return new Promise((resolve) => setTimeout(resolve, ms));
|
||||
}
|
||||
|
||||
function showAsyncPrompt() {
|
||||
prompt({
|
||||
async beforeClose(scope) {
|
||||
if (scope.isConfirm) {
|
||||
if (scope.value) {
|
||||
// 模拟异步操作，如果不成功，可以返回false
|
||||
await sleep(2000);
|
||||
} else {
|
||||
alert('请选择一个选项');
|
||||
return false;
|
||||
}
|
||||
}
|
||||
},
|
||||
component: RadioGroup,
|
||||
componentProps: {
|
||||
class: 'flex flex-col',
|
||||
options: [
|
||||
{ label: 'Option 1', value: 'option1' },
|
||||
{ label: 'Option 2', value: 'option2' },
|
||||
{ label: 'Option 3', value: 'option3' },
|
||||
],
|
||||
},
|
||||
content: '选择一个选项后再点击[确认]',
|
||||
icon: 'question',
|
||||
modelPropName: 'value',
|
||||
}).then((val) => {
|
||||
alert(`${val} 已设置。`);
|
||||
});
|
||||
}
|
||||
</script>
|
||||
<template>
|
||||
<div class="flex gap-4">
|
||||
<VbenButton @click="showPrompt">Prompt</VbenButton>
|
||||
<VbenButton @click="showSlotsPrompt"> Prompt With slots </VbenButton>
|
||||
<VbenButton @click="showSelectPrompt">Prompt With Select</VbenButton>
|
||||
<VbenButton @click="showAsyncPrompt">Prompt With Async</VbenButton>
|
||||
</div>
|
||||
</template>
|
||||
@@ -1,7 +1,7 @@
|
||||
<script lang="ts" setup>
|
||||
import { ApiComponent } from '@vben/common-ui';
|
||||
|
||||
import { Cascader } from 'ant-design-vue';
|
||||
import { Cascader } from 'antdv-next';
|
||||
|
||||
const treeData: Record<string, any> = [
|
||||
{
|
||||
|
||||
102
docs/src/demos/vben-cropper/aspect-ratio/index.vue
Normal file
102
docs/src/demos/vben-cropper/aspect-ratio/index.vue
Normal file
@@ -0,0 +1,102 @@
|
||||
<script lang="ts" setup>
|
||||
import { onBeforeUnmount, ref } from 'vue';
|
||||
|
||||
import { VCropper } from '@vben/common-ui';
|
||||
|
||||
const cropperRef = ref<InstanceType<typeof VCropper>>();
|
||||
const aspectRatio = ref('1:1');
|
||||
const imageUrl = ref('https://picsum.photos/seed/cropper-ratio/800/600');
|
||||
const croppedImage = ref('');
|
||||
|
||||
const aspectOptions = [
|
||||
{ label: '1:1 (正方形)', value: '1:1' },
|
||||
{ label: '16:9 (宽屏)', value: '16:9' },
|
||||
{ label: '4:3 (标准)', value: '4:3' },
|
||||
{ label: '3:4 (竖版)', value: '3:4' },
|
||||
{ label: '3:2 (照片)', value: '3:2' },
|
||||
];
|
||||
|
||||
// 释放旧的 object URL 以避免内存泄漏
|
||||
const revokeCroppedImage = () => {
|
||||
if (croppedImage.value?.startsWith('blob:')) {
|
||||
URL.revokeObjectURL(croppedImage.value);
|
||||
}
|
||||
};
|
||||
|
||||
const handleCrop = async () => {
|
||||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob');
|
||||
if (blob instanceof Blob) {
|
||||
// 释放旧的 URL
|
||||
revokeCroppedImage();
|
||||
croppedImage.value = URL.createObjectURL(blob);
|
||||
}
|
||||
};
|
||||
|
||||
const handleReset = () => {
|
||||
// 释放 URL
|
||||
revokeCroppedImage();
|
||||
croppedImage.value = '';
|
||||
imageUrl.value = `https://picsum.photos/seed/cropper-${Date.now()}/800/600`;
|
||||
};
|
||||
|
||||
// 组件卸载时清理
|
||||
onBeforeUnmount(() => {
|
||||
revokeCroppedImage();
|
||||
});
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<div class="mb-4">
|
||||
<label class="text-sm text-gray-500 mr-2">选择比例:</label>
|
||||
<select v-model="aspectRatio" class="px-3 py-1 border rounded text-sm">
|
||||
<option
|
||||
v-for="option in aspectOptions"
|
||||
:key="option.value"
|
||||
:value="option.value"
|
||||
>
|
||||
{{ option.label }}
|
||||
</option>
|
||||
</select>
|
||||
</div>
|
||||
|
||||
<VCropper
|
||||
ref="cropperRef"
|
||||
:img="imageUrl"
|
||||
:width="500"
|
||||
:height="300"
|
||||
:aspect-ratio="aspectRatio"
|
||||
/>
|
||||
|
||||
<div class="mt-4 flex gap-2">
|
||||
<button
|
||||
class="px-4 py-2 bg-blue-500 rounded hover:bg-blue-600"
|
||||
@click="handleCrop"
|
||||
>
|
||||
裁剪图片
|
||||
</button>
|
||||
<button
|
||||
class="px-4 py-2 bg-gray-500 rounded hover:bg-gray-600"
|
||||
@click="handleReset"
|
||||
>
|
||||
重置
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div v-if="croppedImage" class="mt-4">
|
||||
<p class="text-sm text-gray-500 mb-2">
|
||||
裁剪结果 (比例: {{ aspectRatio }}):
|
||||
</p>
|
||||
<img :src="croppedImage" class="max-w-full rounded border" />
|
||||
</div>
|
||||
|
||||
<div class="mt-4">
|
||||
<p class="text-sm text-gray-500">提示:</p>
|
||||
<ul class="mt-2 text-xs text-gray-400 list-disc pl-4">
|
||||
<li>设置固定比例后，裁剪框始终维持该比例</li>
|
||||
<li>切换比例会自动重新计算裁剪框大小</li>
|
||||
<li>比例格式为 "宽:高"，如 "16:9"</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
70
docs/src/demos/vben-cropper/basic/index.vue
Normal file
70
docs/src/demos/vben-cropper/basic/index.vue
Normal file
@@ -0,0 +1,70 @@
|
||||
<script lang="ts" setup>
|
||||
import { onBeforeUnmount, ref } from 'vue';
|
||||
|
||||
import { VCropper } from '@vben/common-ui';
|
||||
|
||||
const cropperRef = ref<InstanceType<typeof VCropper>>();
|
||||
const imageUrl = ref('https://picsum.photos/seed/cropper-demo/800/600');
|
||||
const croppedImage = ref('');
|
||||
|
||||
// 释放旧的 object URL 以避免内存泄漏
|
||||
const revokeCroppedImage = () => {
|
||||
if (croppedImage.value?.startsWith('blob:')) {
|
||||
URL.revokeObjectURL(croppedImage.value);
|
||||
}
|
||||
};
|
||||
|
||||
const handleCrop = async () => {
|
||||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob');
|
||||
if (blob instanceof Blob) {
|
||||
// 释放旧的 URL
|
||||
revokeCroppedImage();
|
||||
croppedImage.value = URL.createObjectURL(blob);
|
||||
}
|
||||
};
|
||||
|
||||
const handleReset = () => {
|
||||
// 释放 URL
|
||||
revokeCroppedImage();
|
||||
croppedImage.value = '';
|
||||
// 重新加载图片以重置裁剪框
|
||||
imageUrl.value = `https://picsum.photos/seed/cropper-${Date.now()}/800/600`;
|
||||
};
|
||||
|
||||
// 组件卸载时清理
|
||||
onBeforeUnmount(() => {
|
||||
revokeCroppedImage();
|
||||
});
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<VCropper ref="cropperRef" :img="imageUrl" :width="500" :height="300" />
|
||||
<div class="mt-4 flex gap-2">
|
||||
<button
|
||||
class="px-4 py-2 bg-blue-500 rounded hover:bg-blue-600"
|
||||
@click="handleCrop"
|
||||
>
|
||||
裁剪图片
|
||||
</button>
|
||||
<button
|
||||
class="px-4 py-2 bg-gray-500 rounded hover:bg-gray-600"
|
||||
@click="handleReset"
|
||||
>
|
||||
重置
|
||||
</button>
|
||||
</div>
|
||||
<div v-if="croppedImage" class="mt-4">
|
||||
<p class="text-sm text-gray-500 mb-2">裁剪结果:</p>
|
||||
<img :src="croppedImage" class="max-w-full rounded border" />
|
||||
</div>
|
||||
<div class="mt-4">
|
||||
<p class="text-sm text-gray-500">提示:</p>
|
||||
<ul class="mt-2 text-xs text-gray-400 list-disc pl-4">
|
||||
<li>拖拽裁剪框中心区域可移动裁剪位置</li>
|
||||
<li>拖拽四角或四边可调整裁剪框大小</li>
|
||||
<li>默认为自由比例，可调整为任意比例</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
18
docs/src/demos/vben-descriptions/basic/index.vue
Normal file
18
docs/src/demos/vben-descriptions/basic/index.vue
Normal file
@@ -0,0 +1,18 @@
|
||||
<script lang="ts" setup>
|
||||
import { VbenDescriptions } from '@vben/common-ui';
|
||||
|
||||
const items = [
|
||||
{ content: 'Vben', label: '用户名' },
|
||||
{ content: '13800138000', label: '手机号' },
|
||||
{ content: '中国 · 杭州', label: '居住地' },
|
||||
{ content: '前端工程师', label: '职位' },
|
||||
{
|
||||
content: '这是一段较长的备注信息，用于演示跨列展示。',
|
||||
label: '备注',
|
||||
span: 3,
|
||||
},
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<VbenDescriptions :items="items" />
|
||||
</template>
|
||||
22
docs/src/demos/vben-descriptions/bordered/index.vue
Normal file
22
docs/src/demos/vben-descriptions/bordered/index.vue
Normal file
@@ -0,0 +1,22 @@
|
||||
<script lang="ts" setup>
|
||||
import { VbenDescriptions } from '@vben/common-ui';
|
||||
|
||||
const items = [
|
||||
{ content: 'Vben', label: '用户名' },
|
||||
{ content: '13800138000', label: '手机号' },
|
||||
{ content: '正常', label: '状态' },
|
||||
{ content: '中国 · 杭州', label: '居住地' },
|
||||
{
|
||||
content: '浙江省杭州市西湖区某某街道某某小区 1 幢 2 单元',
|
||||
label: '地址',
|
||||
span: 3,
|
||||
},
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<VbenDescriptions bordered title="用户信息" :items="items">
|
||||
<template #extra>
|
||||
<span style="color: #1677ff; cursor: pointer">编辑</span>
|
||||
</template>
|
||||
</VbenDescriptions>
|
||||
</template>
|
||||
17
docs/src/demos/vben-descriptions/custom/index.vue
Normal file
17
docs/src/demos/vben-descriptions/custom/index.vue
Normal file
@@ -0,0 +1,17 @@
|
||||
<script lang="ts" setup>
|
||||
import { VbenDescriptions, VbenDescriptionsItem } from '@vben/common-ui';
|
||||
</script>
|
||||
<template>
|
||||
<!-- 通过子组件 VbenDescriptionsItem 声明列表项 -->
|
||||
<VbenDescriptions bordered :column="2">
|
||||
<VbenDescriptionsItem label="用户名">Vben</VbenDescriptionsItem>
|
||||
<VbenDescriptionsItem label="状态">
|
||||
<span style="color: #52c41a">● 正常</span>
|
||||
</VbenDescriptionsItem>
|
||||
<VbenDescriptionsItem label="备注" :span="2">
|
||||
<template #content>
|
||||
<span style="color: #888">通过 #content 插槽自定义内容</span>
|
||||
</template>
|
||||
</VbenDescriptionsItem>
|
||||
</VbenDescriptions>
|
||||
</template>
|
||||
35
docs/src/demos/vben-descriptions/size/index.vue
Normal file
35
docs/src/demos/vben-descriptions/size/index.vue
Normal file
@@ -0,0 +1,35 @@
|
||||
<script lang="ts" setup>
|
||||
import { VbenDescriptions } from '@vben/common-ui';
|
||||
|
||||
const items = [
|
||||
{ content: 'Vben', label: '用户名' },
|
||||
{ content: '13800138000', label: '手机号' },
|
||||
{ content: '中国 · 杭州', label: '居住地' },
|
||||
{ content: '前端工程师', label: '职位' },
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<div class="flex gap-4 flex-col">
|
||||
<VbenDescriptions
|
||||
size="small"
|
||||
bordered
|
||||
title="Small"
|
||||
:column="2"
|
||||
:items="items"
|
||||
/>
|
||||
<VbenDescriptions
|
||||
size="middle"
|
||||
bordered
|
||||
title="Middle"
|
||||
:column="2"
|
||||
:items="items"
|
||||
/>
|
||||
<VbenDescriptions
|
||||
size="large"
|
||||
bordered
|
||||
title="Large"
|
||||
:column="2"
|
||||
:items="items"
|
||||
/>
|
||||
</div>
|
||||
</template>
|
||||
17
docs/src/demos/vben-descriptions/span/index.vue
Normal file
17
docs/src/demos/vben-descriptions/span/index.vue
Normal file
@@ -0,0 +1,17 @@
|
||||
<script lang="ts" setup>
|
||||
import type { DescriptionsItemType } from '@vben/common-ui';
|
||||
|
||||
import { VbenDescriptions } from '@vben/common-ui';
|
||||
|
||||
const items: DescriptionsItemType[] = [
|
||||
{ content: '1', label: 'A' },
|
||||
{ content: '2（span: 2）', label: 'B', span: 2 },
|
||||
{ content: '3', label: 'C' },
|
||||
{ content: '占满当前行剩余空间', label: 'D（span: filled）', span: 'filled' },
|
||||
{ content: '5', label: 'E' },
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<!-- 列数随断点变化：xs 1 列、sm 2 列、md 及以上 3 列 -->
|
||||
<VbenDescriptions bordered :column="{ md: 3, sm: 2, xs: 1 }" :items="items" />
|
||||
</template>
|
||||
15
docs/src/demos/vben-descriptions/vertical/index.vue
Normal file
15
docs/src/demos/vben-descriptions/vertical/index.vue
Normal file
@@ -0,0 +1,15 @@
|
||||
<script lang="ts" setup>
|
||||
import type { DescriptionsItemType } from '@vben/common-ui';
|
||||
|
||||
import { VbenDescriptions } from '@vben/common-ui';
|
||||
|
||||
const items: DescriptionsItemType[] = [
|
||||
{ content: 'Vben', label: '用户名' },
|
||||
{ content: '13800138000', label: '手机号' },
|
||||
{ content: '中国 · 杭州', label: '居住地' },
|
||||
{ content: '这是一段较长的备注信息。', label: '备注', span: 3 },
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<VbenDescriptions bordered layout="vertical" :items="items" />
|
||||
</template>
|
||||
16
docs/src/demos/vben-ellipsis-text/auto-display/index.vue
Normal file
16
docs/src/demos/vben-ellipsis-text/auto-display/index.vue
Normal file
@@ -0,0 +1,16 @@
|
||||
<script lang="ts" setup>
|
||||
import { EllipsisText } from '@vben/common-ui';
|
||||
|
||||
const text = `
|
||||
Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。
|
||||
`;
|
||||
</script>
|
||||
<template>
|
||||
<EllipsisText :line="2" :tooltip-when-ellipsis="true">
|
||||
{{ text }}
|
||||
</EllipsisText>
|
||||
|
||||
<EllipsisText :line="3" :tooltip-when-ellipsis="true">
|
||||
{{ text }}
|
||||
</EllipsisText>
|
||||
</template>
|
||||
168
docs/src/demos/vben-form/value-format/index.vue
Normal file
168
docs/src/demos/vben-form/value-format/index.vue
Normal file
@@ -0,0 +1,168 @@
|
||||
<script lang="ts" setup>
|
||||
import { computed, nextTick, onMounted, ref } from 'vue';
|
||||
|
||||
import { Button, Card, message, Space, Tag } from 'antdv-next';
|
||||
|
||||
import { useVbenForm } from '#/adapter/form';
|
||||
|
||||
interface ValueFormatFormValues {
|
||||
firstName?: string;
|
||||
lastName?: string;
|
||||
tags?: string[];
|
||||
}
|
||||
|
||||
function encodeValueFormatValues(values: Readonly<ValueFormatFormValues>) {
|
||||
return {
|
||||
fullName: [values.firstName, values.lastName].filter(Boolean).join(' '),
|
||||
tags: (values.tags ?? []).join(','),
|
||||
};
|
||||
}
|
||||
|
||||
type ValueFormatSubmitValues = ReturnType<typeof encodeValueFormatValues>;
|
||||
|
||||
function decodeValueFormatValues(
|
||||
values: Readonly<ValueFormatSubmitValues>,
|
||||
): ValueFormatFormValues {
|
||||
const [firstName = '', ...lastNameParts] = values.fullName
|
||||
.trim()
|
||||
.split(/\s+/);
|
||||
return {
|
||||
firstName,
|
||||
lastName: lastNameParts.join(' '),
|
||||
tags: values.tags ? values.tags.split(',') : [],
|
||||
};
|
||||
}
|
||||
|
||||
const transformedValues = ref<Partial<ValueFormatSubmitValues>>({});
|
||||
const liveValues = ref<Partial<ValueFormatFormValues>>({});
|
||||
|
||||
const [Form, formApi] = useVbenForm({
|
||||
codec: {
|
||||
decode: decodeValueFormatValues,
|
||||
encode: encodeValueFormatValues,
|
||||
},
|
||||
commonConfig: {
|
||||
componentProps: {
|
||||
class: 'w-full',
|
||||
},
|
||||
},
|
||||
handleSubmit,
|
||||
handleValuesChange,
|
||||
schema: [
|
||||
{
|
||||
component: 'Input',
|
||||
fieldName: 'firstName',
|
||||
help: '与姓氏一起编码为 fullName',
|
||||
label: '名字',
|
||||
},
|
||||
{
|
||||
component: 'Input',
|
||||
fieldName: 'lastName',
|
||||
help: '与名字一起编码为 fullName',
|
||||
label: '姓氏',
|
||||
},
|
||||
{
|
||||
component: 'Select',
|
||||
componentProps: {
|
||||
mode: 'multiple',
|
||||
options: [
|
||||
{ label: '管理员', value: 'admin' },
|
||||
{ label: '审核员', value: 'reviewer' },
|
||||
{ label: '访客', value: 'guest' },
|
||||
],
|
||||
placeholder: '请选择标签',
|
||||
},
|
||||
fieldName: 'tags',
|
||||
help: '数组编码为逗号分隔字符串',
|
||||
label: '标签',
|
||||
},
|
||||
],
|
||||
wrapperClass: 'grid-cols-1 md:grid-cols-2',
|
||||
});
|
||||
|
||||
const liveValuesPreview = computed(() => formatJsonPreview(liveValues.value));
|
||||
|
||||
const transformedValuesPreview = computed(() => {
|
||||
return formatJsonPreview(transformedValues.value);
|
||||
});
|
||||
|
||||
function formatJsonPreview(value: unknown) {
|
||||
return JSON.stringify(value, null, 2);
|
||||
}
|
||||
|
||||
async function handleInspectValues() {
|
||||
await syncPreviewValues();
|
||||
message.success('已刷新 getValues 输出');
|
||||
}
|
||||
|
||||
async function handleSetSubmitValues() {
|
||||
await formApi.setSubmitValues({
|
||||
fullName: 'Ada Lovelace',
|
||||
tags: 'admin,reviewer',
|
||||
});
|
||||
await syncPreviewValues();
|
||||
message.success('已通过 codec.decode 回填提交值');
|
||||
}
|
||||
|
||||
function handleSubmit(values: ValueFormatSubmitValues) {
|
||||
transformedValues.value = values;
|
||||
message.success({
|
||||
content: `getValues output: ${JSON.stringify(values)}`,
|
||||
});
|
||||
}
|
||||
|
||||
function handleValuesChange(
|
||||
values: Readonly<ValueFormatFormValues>,
|
||||
_fieldsChanged: string[],
|
||||
getFormattedValues: () => ValueFormatSubmitValues,
|
||||
) {
|
||||
liveValues.value = { ...values };
|
||||
transformedValues.value = getFormattedValues();
|
||||
}
|
||||
|
||||
async function syncPreviewValues(values?: Readonly<ValueFormatFormValues>) {
|
||||
const rawValues = values ?? (await formApi.getRawValues());
|
||||
liveValues.value = { ...rawValues };
|
||||
transformedValues.value = await formApi.getValues();
|
||||
}
|
||||
|
||||
onMounted(async () => {
|
||||
await nextTick();
|
||||
await syncPreviewValues();
|
||||
});
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="space-y-4">
|
||||
<div class="flex flex-wrap gap-2">
|
||||
<Tag color="processing">encode：生成完整提交值</Tag>
|
||||
<Tag color="success">decode：恢复完整表单值</Tag>
|
||||
<Tag color="warning">多字段转换原子执行</Tag>
|
||||
</div>
|
||||
|
||||
<Card title="Codec 示例">
|
||||
<template #extra>
|
||||
<Space wrap>
|
||||
<Button @click="handleSetSubmitValues">从提交值回填</Button>
|
||||
<Button type="primary" @click="handleInspectValues">
|
||||
查看 getValues 输出
|
||||
</Button>
|
||||
</Space>
|
||||
</template>
|
||||
<Form />
|
||||
</Card>
|
||||
|
||||
<div class="grid gap-4 lg:grid-cols-2">
|
||||
<Card title="getRawValues() 输出（组件值）">
|
||||
<pre class="bg-muted overflow-auto rounded-md p-4 text-sm">{{
|
||||
liveValuesPreview
|
||||
}}</pre>
|
||||
</Card>
|
||||
<Card title="getValues / submit 输出（codec.encode 后）">
|
||||
<pre class="bg-muted overflow-auto rounded-md p-4 text-sm">{{
|
||||
transformedValuesPreview
|
||||
}}</pre>
|
||||
</Card>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
36
docs/src/demos/vben-modal/animation-type/index.vue
Normal file
36
docs/src/demos/vben-modal/animation-type/index.vue
Normal file
@@ -0,0 +1,36 @@
|
||||
<script lang="ts" setup>
|
||||
import { useVbenModal, VbenButton } from '@vben/common-ui';
|
||||
|
||||
const [SlideModal, slideModalApi] = useVbenModal({
|
||||
animationType: 'slide',
|
||||
});
|
||||
|
||||
const [ScaleModal, scaleModalApi] = useVbenModal({
|
||||
animationType: 'scale',
|
||||
});
|
||||
|
||||
function openSlideModal() {
|
||||
slideModalApi.open();
|
||||
}
|
||||
|
||||
function openScaleModal() {
|
||||
scaleModalApi.open();
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="space-y-4">
|
||||
<div class="flex gap-4">
|
||||
<VbenButton @click="openSlideModal">滑动动画</VbenButton>
|
||||
<VbenButton @click="openScaleModal">缩放动画</VbenButton>
|
||||
</div>
|
||||
|
||||
<SlideModal title="滑动动画示例" class="w-125">
|
||||
<p>这是使用滑动动画的弹窗，从顶部向下滑动进入。</p>
|
||||
</SlideModal>
|
||||
|
||||
<ScaleModal title="缩放动画示例" class="w-125">
|
||||
<p>这是使用缩放动画的弹窗，以缩放淡入淡出的方式显示。</p>
|
||||
</ScaleModal>
|
||||
</div>
|
||||
</template>
|
||||
28
docs/src/demos/vben-table-action/basic/index.vue
Normal file
28
docs/src/demos/vben-table-action/basic/index.vue
Normal file
@@ -0,0 +1,28 @@
|
||||
<script lang="ts" setup>
|
||||
import type { ActionItem } from '@vben/common-ui';
|
||||
|
||||
import { ref } from 'vue';
|
||||
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
const last = ref('无');
|
||||
|
||||
const actions: ActionItem[] = [
|
||||
{ key: 'edit', onClick: () => (last.value = '编辑'), text: '编辑' },
|
||||
{ key: 'detail', onClick: () => (last.value = '详情'), text: '详情' },
|
||||
{
|
||||
danger: true,
|
||||
key: 'delete',
|
||||
onClick: () => (last.value = '删除'),
|
||||
text: '删除',
|
||||
},
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<div>
|
||||
<VbenTableAction :actions="actions" align="start" divider />
|
||||
<p style="margin-top: 8px; font-size: 13px; opacity: 0.7">
|
||||
最近点击：{{ last }}
|
||||
</p>
|
||||
</div>
|
||||
</template>
|
||||
44
docs/src/demos/vben-table-action/dropdown/index.vue
Normal file
44
docs/src/demos/vben-table-action/dropdown/index.vue
Normal file
@@ -0,0 +1,44 @@
|
||||
<script lang="ts" setup>
|
||||
import type { ActionItem } from '@vben/common-ui';
|
||||
|
||||
import { ref } from 'vue';
|
||||
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
const last = ref('无');
|
||||
|
||||
const actions: ActionItem[] = [
|
||||
{ key: 'edit', onClick: () => (last.value = '编辑'), text: '编辑' },
|
||||
];
|
||||
|
||||
const dropdownActions: ActionItem[] = [
|
||||
{ key: 'copy', onClick: () => (last.value = '复制'), text: '复制' },
|
||||
{ key: 'export', onClick: () => (last.value = '导出'), text: '导出' },
|
||||
{
|
||||
danger: true,
|
||||
key: 'remove',
|
||||
// 下拉项同样支持气泡确认
|
||||
popConfirm: {
|
||||
cancelText: '取消',
|
||||
confirm: () => (last.value = '已移除'),
|
||||
okText: '确认',
|
||||
title: '确定移除吗？',
|
||||
},
|
||||
text: '移除',
|
||||
},
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<div>
|
||||
<VbenTableAction
|
||||
:actions="actions"
|
||||
:dropdown-actions="dropdownActions"
|
||||
align="start"
|
||||
divider
|
||||
more-text="更多"
|
||||
/>
|
||||
<p style="margin-top: 8px; font-size: 13px; opacity: 0.7">
|
||||
最近点击：{{ last }}
|
||||
</p>
|
||||
</div>
|
||||
</template>
|
||||
28
docs/src/demos/vben-table-action/permission/index.vue
Normal file
28
docs/src/demos/vben-table-action/permission/index.vue
Normal file
@@ -0,0 +1,28 @@
|
||||
<script lang="ts" setup>
|
||||
import type { ActionItem } from '@vben/common-ui';
|
||||
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
// 模拟当前用户拥有的权限码
|
||||
const allow = new Set(['user:detail', 'user:edit']);
|
||||
|
||||
function hasPermission(auth?: string | string[]) {
|
||||
if (!auth) return true;
|
||||
const codes = Array.isArray(auth) ? auth : [auth];
|
||||
return codes.some((code) => allow.has(code));
|
||||
}
|
||||
|
||||
const actions: ActionItem[] = [
|
||||
{ auth: 'user:edit', key: 'edit', text: '编辑' },
|
||||
{ auth: 'user:detail', key: 'detail', text: '详情' },
|
||||
// 无 user:delete 权限，按钮被隐藏
|
||||
{ auth: 'user:delete', danger: true, key: 'delete', text: '删除（无权限）' },
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<VbenTableAction
|
||||
:actions="actions"
|
||||
:has-permission="hasPermission"
|
||||
align="start"
|
||||
/>
|
||||
</template>
|
||||
32
docs/src/demos/vben-table-action/popconfirm/index.vue
Normal file
32
docs/src/demos/vben-table-action/popconfirm/index.vue
Normal file
@@ -0,0 +1,32 @@
|
||||
<script lang="ts" setup>
|
||||
import type { ActionItem } from '@vben/common-ui';
|
||||
|
||||
import { ref } from 'vue';
|
||||
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
const last = ref('无');
|
||||
|
||||
const actions: ActionItem[] = [
|
||||
{ key: 'edit', onClick: () => (last.value = '编辑'), text: '编辑' },
|
||||
{
|
||||
danger: true,
|
||||
key: 'delete',
|
||||
popConfirm: {
|
||||
cancelText: '取消',
|
||||
confirm: () => (last.value = '已删除'),
|
||||
okText: '确认',
|
||||
title: '确定删除这一行吗？',
|
||||
},
|
||||
text: '删除',
|
||||
},
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<div>
|
||||
<VbenTableAction :actions="actions" align="start" />
|
||||
<p style="margin-top: 8px; font-size: 13px; opacity: 0.7">
|
||||
最近操作：{{ last }}
|
||||
</p>
|
||||
</div>
|
||||
</template>
|
||||
17
docs/src/demos/vben-table-action/tooltip/index.vue
Normal file
17
docs/src/demos/vben-table-action/tooltip/index.vue
Normal file
@@ -0,0 +1,17 @@
|
||||
<script lang="ts" setup>
|
||||
import type { ActionItem } from '@vben/common-ui';
|
||||
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
const actions: ActionItem[] = [
|
||||
{ key: 'edit', text: '编辑', tooltip: '编辑这一行' },
|
||||
{
|
||||
key: 'detail',
|
||||
text: '详情',
|
||||
tooltip: { content: '查看详情', side: 'top' },
|
||||
},
|
||||
];
|
||||
</script>
|
||||
<template>
|
||||
<VbenTableAction :actions="actions" align="start" />
|
||||
</template>
|
||||
19
docs/src/demos/vben-tiptap/basic/index.vue
Normal file
19
docs/src/demos/vben-tiptap/basic/index.vue
Normal file
@@ -0,0 +1,19 @@
|
||||
<script lang="ts" setup>
|
||||
import { ref } from 'vue';
|
||||
|
||||
import { VbenTiptap } from '@vben/plugins/tiptap';
|
||||
|
||||
const content = ref('<p>开始编辑你的内容...</p>');
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<VbenTiptap v-model="content" />
|
||||
<div class="mt-4">
|
||||
<p class="text-sm text-gray-500">当前内容:</p>
|
||||
<pre class="mt-2 p-2 bg-gray-100 rounded text-xs overflow-auto max-h-40">
|
||||
{{ content }}
|
||||
</pre>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
45
docs/src/demos/vben-tiptap/image-upload/index.vue
Normal file
45
docs/src/demos/vben-tiptap/image-upload/index.vue
Normal file
@@ -0,0 +1,45 @@
|
||||
<script lang="ts" setup>
|
||||
import { ref } from 'vue';
|
||||
|
||||
import { type ImageUploadOptions, VbenTiptap } from '@vben/plugins/tiptap';
|
||||
|
||||
const content = ref('');
|
||||
|
||||
// Mock upload function with progress simulation
|
||||
const imageUpload: ImageUploadOptions = {
|
||||
accept: 'image/jpeg,image/png,image/gif,image/webp',
|
||||
maxSize: 5 * 1024 * 1024, // 5MB
|
||||
upload: async (_file, onProgress) => {
|
||||
// Simulate upload progress
|
||||
for (let i = 0; i <= 100; i += 10) {
|
||||
await new Promise((resolve) => setTimeout(resolve, 100));
|
||||
onProgress?.(i);
|
||||
}
|
||||
|
||||
// Return a mock image URL (using picsum for demo)
|
||||
return `https://picsum.photos/seed/${Date.now()}/800/400`;
|
||||
},
|
||||
onUploadError: (error) => {
|
||||
console.error('Upload error:', error);
|
||||
},
|
||||
};
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<VbenTiptap
|
||||
v-model="content"
|
||||
:image-upload="imageUpload"
|
||||
placeholder="尝试拖拽或粘贴图片..."
|
||||
/>
|
||||
<div class="mt-4">
|
||||
<p class="text-sm text-gray-500">提示:</p>
|
||||
<ul class="mt-2 text-xs text-gray-400 list-disc pl-4">
|
||||
<li>点击工具栏图片按钮可选择本地上传或 URL 插入</li>
|
||||
<li>拖拽图片到编辑器区域可直接上传</li>
|
||||
<li>粘贴图片也会触发上传</li>
|
||||
<li>上传过程中会显示进度条</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
73
docs/src/en/components/common-ui/vben-alert.md
Normal file
73
docs/src/en/components/common-ui/vben-alert.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Alert
|
||||
|
||||
`Alert` provides lightweight JavaScript-driven dialogs for simple `alert`, `confirm`, and `prompt` style interactions.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Use `alert` for a single confirm button dialog:
|
||||
|
||||
<DemoPreview dir="demos/vben-alert/alert" />
|
||||
|
||||
Use `confirm` for confirm/cancel interactions:
|
||||
|
||||
<DemoPreview dir="demos/vben-alert/confirm" />
|
||||
|
||||
Use `prompt` when you need simple user input:
|
||||
|
||||
<DemoPreview dir="demos/vben-alert/prompt" />
|
||||
|
||||
## useAlertContext
|
||||
|
||||
If `content`, `footer`, or `icon` is rendered through a custom component, you can call `useAlertContext()` inside that component to access the current dialog actions.
|
||||
|
||||
| Method | Description | Type |
|
||||
| ----------- | -------------------------- | ------------ |
|
||||
| `doConfirm` | trigger the confirm action | `() => void` |
|
||||
| `doCancel` | trigger the cancel action | `() => void` |
|
||||
|
||||
## Core Types
|
||||
|
||||
```ts
|
||||
export type IconType = 'error' | 'info' | 'question' | 'success' | 'warning';
|
||||
|
||||
export type BeforeCloseScope = {
|
||||
isConfirm: boolean;
|
||||
};
|
||||
|
||||
export type AlertProps = {
|
||||
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;
|
||||
contentMasking?: boolean;
|
||||
footer?: Component | string;
|
||||
icon?: Component | IconType;
|
||||
overlayBlur?: number;
|
||||
showCancel?: boolean;
|
||||
title?: string;
|
||||
};
|
||||
|
||||
export type PromptProps<T = any> = {
|
||||
beforeClose?: (scope: {
|
||||
isConfirm: boolean;
|
||||
value: T | undefined;
|
||||
}) => boolean | Promise<boolean | undefined> | undefined;
|
||||
component?: Component;
|
||||
componentProps?: Recordable<any>;
|
||||
componentSlots?:
|
||||
(() => any) | Recordable<unknown> | VNode | VNodeArrayChildren;
|
||||
defaultValue?: T;
|
||||
modelPropName?: string;
|
||||
} & Omit<AlertProps, 'beforeClose'>;
|
||||
```
|
||||
69
docs/src/en/components/common-ui/vben-api-component.md
Normal file
69
docs/src/en/components/common-ui/vben-api-component.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben ApiComponent
|
||||
|
||||
`ApiComponent` is a wrapper used to attach remote-option loading behavior to an existing component while preserving the original component usage pattern.
|
||||
|
||||
## Common Usage
|
||||
|
||||
The current wrapper flow is:
|
||||
|
||||
- pass the target component through `component`
|
||||
- fetch remote data through `api`
|
||||
- transform data through `beforeFetch` and `afterFetch`
|
||||
- map remote fields through `resultField`, `valueField`, `labelField`, and `childrenField`
|
||||
- pass normalized options to the target component through `optionsPropName`
|
||||
|
||||
```vue
|
||||
<script lang="ts" setup>
|
||||
import { ApiComponent } from '@vben/common-ui';
|
||||
|
||||
import { Cascader } from 'antdv-next';
|
||||
|
||||
function fetchApi() {
|
||||
return Promise.resolve([
|
||||
{
|
||||
label: 'Zhejiang',
|
||||
value: 'zhejiang',
|
||||
children: [{ label: 'Hangzhou', value: 'hangzhou' }],
|
||||
},
|
||||
]);
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<ApiComponent
|
||||
:api="fetchApi"
|
||||
:component="Cascader"
|
||||
:immediate="false"
|
||||
children-field="children"
|
||||
loading-slot="suffixIcon"
|
||||
visible-event="onDropdownVisibleChange"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
## Current Props
|
||||
|
||||
| Prop | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `component` | wrapped target component | `Component` |
|
||||
| `api` | remote request function | `(arg?: any) => Promise<any>` |
|
||||
| `params` | extra request params | `Record<string, any>` |
|
||||
| `beforeFetch` | hook before request | `AnyPromiseFunction` |
|
||||
| `afterFetch` | hook after request | `AnyPromiseFunction` |
|
||||
| `visibleEvent` | event name used to lazy-load data | `string` |
|
||||
| `loadingSlot` | slot name used to render the loading icon | `string` |
|
||||
| `modelPropName` | model prop name of the wrapped component | `string` |
|
||||
| `autoSelect` | auto-pick the first / last / only option, or use a custom function | `'first' \| 'last' \| 'one' \| ((items) => item) \| false` |
|
||||
|
||||
## Exposed Methods
|
||||
|
||||
| Method | Description |
|
||||
| ------------------------ | -------------------------------------- |
|
||||
| `getComponentRef()` | returns the wrapped component instance |
|
||||
| `updateParam(newParams)` | merges and updates request params |
|
||||
| `getOptions()` | returns loaded options |
|
||||
| `getValue()` | returns the current bound value |
|
||||
51
docs/src/en/components/common-ui/vben-count-to-animator.md
Normal file
51
docs/src/en/components/common-ui/vben-count-to-animator.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben CountToAnimator
|
||||
|
||||
`CountToAnimator` renders animated number transitions.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Use `start-val`, `end-val`, and `duration` to control the animation range and timing.
|
||||
|
||||
<DemoPreview dir="demos/vben-count-to-animator/basic" />
|
||||
|
||||
## Formatting
|
||||
|
||||
Use `prefix`, `suffix`, `separator`, and `decimal` to control how the number is displayed.
|
||||
|
||||
<DemoPreview dir="demos/vben-count-to-animator/custom" />
|
||||
|
||||
## Props
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `startVal` | starting value | `number` | `0` |
|
||||
| `endVal` | ending value | `number` | `2021` |
|
||||
| `duration` | animation duration in ms | `number` | `1500` |
|
||||
| `autoplay` | start automatically | `boolean` | `true` |
|
||||
| `prefix` | value prefix | `string` | `''` |
|
||||
| `suffix` | value suffix | `string` | `''` |
|
||||
| `separator` | thousands separator | `string` | `','` |
|
||||
| `decimal` | decimal separator | `string` | `'.'` |
|
||||
| `color` | text color | `string` | `''` |
|
||||
| `useEasing` | enable transition preset easing | `boolean` | `true` |
|
||||
| `transition` | transition preset name | `keyof typeof TransitionPresets` | `'linear'` |
|
||||
| `decimals` | decimal places to keep | `number` | `0` |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Description | Type |
|
||||
| ------------ | ------------------------------- | ------------ |
|
||||
| `started` | fired when the animation starts | `() => void` |
|
||||
| `finished` | fired when the animation ends | `() => void` |
|
||||
| `onStarted` | deprecated alias of `started` | `() => void` |
|
||||
| `onFinished` | deprecated alias of `finished` | `() => void` |
|
||||
|
||||
## Exposed Methods
|
||||
|
||||
| Method | Description | Type |
|
||||
| ------- | --------------------------------- | ------------ |
|
||||
| `reset` | reset to `startVal` and run again | `() => void` |
|
||||
159
docs/src/en/components/common-ui/vben-cropper.md
Normal file
159
docs/src/en/components/common-ui/vben-cropper.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Cropper Image Cropping
|
||||
|
||||
`VCropper` is a pure native image cropping component that supports both free and fixed aspect ratio cropping, with method-based access to cropped results.
|
||||
|
||||
> If some details are not obvious from the docs, check the live demos as well.
|
||||
|
||||
::: info Note
|
||||
|
||||
If you feel the current component implementation doesn't meet your needs, you can use native components directly or create your own component. The components provided by the framework are not constraints - use them at your discretion.
|
||||
|
||||
:::
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Basic image cropping with free aspect ratio adjustment.
|
||||
|
||||
<DemoPreview dir="demos/vben-cropper/basic" />
|
||||
|
||||
## Fixed Aspect Ratio
|
||||
|
||||
Set the cropping ratio via the `aspectRatio` prop. The format is `"width:height"`, e.g. `"1:1"`, `"16:9"`, `"3:4"`.
|
||||
|
||||
<DemoPreview dir="demos/vben-cropper/aspect-ratio" />
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| Property | Description | Type | Default |
|
||||
| ------------- | ---------------------------------- | -------- | ------- |
|
||||
| `img` | Image URL (required) | `string` | - |
|
||||
| `width` | Container width | `number` | `500` |
|
||||
| `height` | Container height | `number` | `400` |
|
||||
| `aspectRatio` | Crop ratio, e.g. `"1:1"`, `"16:9"` | `string` | - |
|
||||
|
||||
### Methods
|
||||
|
||||
Call component methods via `ref`:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue';
|
||||
import { VCropper } from '@vben/common-ui';
|
||||
|
||||
const cropperRef = ref<InstanceType<typeof VCropper>>();
|
||||
|
||||
const handleCrop = async () => {
|
||||
const result = await cropperRef.value?.getCropImage();
|
||||
// result is a Blob or base64 string
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
#### getCropImage
|
||||
|
||||
Crop and retrieve the image.
|
||||
|
||||
```ts
|
||||
getCropImage(
|
||||
format?: 'image/jpeg' | 'image/png',
|
||||
quality?: number,
|
||||
outputType?: 'base64' | 'blob',
|
||||
targetWidth?: number,
|
||||
targetHeight?: number,
|
||||
): Promise<Blob | string | undefined>
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `format` | `'image/jpeg' \| 'image/png'` | `'image/png'` | Output image format |
|
||||
| `quality` | `number` | `0.92` | Compression quality (0-1), only effective for jpeg |
|
||||
| `outputType` | `'base64' \| 'blob'` | `'blob'` | Output type, base64 string or Blob object |
|
||||
| `targetWidth` | `number` | - | Target width, defaults to original crop width if omitted |
|
||||
| `targetHeight` | `number` | - | Target height, defaults to original crop height if omitted |
|
||||
|
||||
## Features
|
||||
|
||||
### Cropping Operations
|
||||
|
||||
- **Drag to Move** - Drag the center area of the crop box to move its position
|
||||
- **Corner Resize** - Drag the four corners to resize the crop box
|
||||
- **Edge Resize** - Drag the midpoints of edges to adjust a single side
|
||||
|
||||
### Aspect Ratio Control
|
||||
|
||||
- **Free Ratio** - Without `aspectRatio`, adjust the crop box to any ratio
|
||||
- **Fixed Ratio** - With `aspectRatio` set, the crop box maintains the specified ratio
|
||||
|
||||
### HiDPI Support
|
||||
|
||||
The component automatically adapts to Retina and other high-DPI screens, ensuring crisp output images.
|
||||
|
||||
### Image Fitting
|
||||
|
||||
- Images are automatically scaled to fit within the container
|
||||
- Supports both local and remote images
|
||||
- Remote images require CORS support from the server to export cropped results
|
||||
|
||||
## Usage Example
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue';
|
||||
import { VCropper } from '@vben/common-ui';
|
||||
|
||||
const cropperRef = ref<InstanceType<typeof VCropper>>();
|
||||
const imageUrl = ref('https://example.com/image.jpg');
|
||||
const croppedImage = ref('');
|
||||
|
||||
// Get cropped Blob
|
||||
const handleCropBlob = async () => {
|
||||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob');
|
||||
if (blob instanceof Blob) {
|
||||
// Upload to server or create preview URL
|
||||
const url = URL.createObjectURL(blob);
|
||||
croppedImage.value = url;
|
||||
}
|
||||
};
|
||||
|
||||
// Get cropped base64 string
|
||||
const handleCropBase64 = async () => {
|
||||
const base64 = await cropperRef.value?.getCropImage('image/png', 1, 'base64');
|
||||
if (typeof base64 === 'string') {
|
||||
croppedImage.value = base64;
|
||||
}
|
||||
};
|
||||
|
||||
// Export with specific dimensions
|
||||
const handleCropWithSize = async () => {
|
||||
const blob = await cropperRef.value?.getCropImage(
|
||||
'image/jpeg',
|
||||
0.9,
|
||||
'blob',
|
||||
200, // target width
|
||||
200, // target height
|
||||
);
|
||||
};
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<VCropper
|
||||
ref="cropperRef"
|
||||
:img="imageUrl"
|
||||
:width="500"
|
||||
:height="400"
|
||||
aspect-ratio="1:1"
|
||||
/>
|
||||
<button @click="handleCropBlob">Crop</button>
|
||||
<img v-if="croppedImage" :src="croppedImage" />
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
102
docs/src/en/components/common-ui/vben-descriptions.md
Normal file
102
docs/src/en/components/common-ui/vben-descriptions.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Descriptions
|
||||
|
||||
`Descriptions` displays a group of read-only fields, commonly used on detail pages and information previews. It is built on shadcn-ui with an API modeled after Ant Design Vue's Descriptions, supporting responsive columns, column spanning, borders, and vertical layout.
|
||||
|
||||
> If the documentation does not cover the details you need, please refer to the online examples.
|
||||
|
||||
::: info Before you start
|
||||
|
||||
The component supports two usages: data-driven via `items` (recommended), or declaring entries with the `VbenDescriptionsItem` child component. `items` takes precedence when both are provided. :::
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Pass an array of fields via `items`, each with a `label` and `content`. Columns adapt to breakpoints by default (1 column on `xs`, 2 on `sm`, 3 on `md` and above).
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/basic" />
|
||||
|
||||
## Bordered
|
||||
|
||||
Set `bordered` for a bordered style, combined with the `title` prop and the `#extra` slot (an action area on the right of the title).
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/bordered" />
|
||||
|
||||
## Vertical Layout
|
||||
|
||||
Use `layout="vertical"` to place labels above their content.
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/vertical" />
|
||||
|
||||
## Sizes
|
||||
|
||||
Use `size` to switch between `small`, `middle`, and `large`.
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/size" />
|
||||
|
||||
## Span & Responsive
|
||||
|
||||
Set `span` on an item to span multiple columns; `'filled'` fills the remaining space of the current row. `column` accepts a breakpoint-keyed object for responsive columns.
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/span" />
|
||||
|
||||
## Child Component Usage
|
||||
|
||||
When `items` is omitted, declare entries with `VbenDescriptionsItem` in the default slot. Content can be customized via the default slot or the `#content` slot.
|
||||
|
||||
<DemoPreview dir="demos/vben-descriptions/custom" />
|
||||
|
||||
## API
|
||||
|
||||
### Descriptions Props
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| items | Data-driven entries; reads the default slot when omitted | `DescriptionsItemType[]` | - |
|
||||
| bordered | Whether to show borders | `boolean` | `false` |
|
||||
| column | Columns per row, supports breakpoint config | `number \| Partial<Record<Breakpoint, number>>` | `{ xs: 1, sm: 2, md: 3, xxxl: 4 }` |
|
||||
| layout | Layout direction | `'horizontal' \| 'vertical'` | `'horizontal'` |
|
||||
| size | Size | `'small' \| 'middle' \| 'large'` | `'middle'` |
|
||||
| colon | Show colon (only for non-bordered horizontal layout) | `boolean` | `true` |
|
||||
| title | Title | `string` | - |
|
||||
| extra | Action area on the right of the title | `string` | - |
|
||||
| labelStyle | Shared label style | `CSSProperties` | - |
|
||||
| contentStyle | Shared content style | `CSSProperties` | - |
|
||||
| class | Custom class for the root node | `string` | - |
|
||||
|
||||
### Descriptions Slots
|
||||
|
||||
| Slot | Description |
|
||||
| ------- | ------------------------------------- |
|
||||
| title | Custom title |
|
||||
| extra | Custom action area beside the title |
|
||||
| default | Place `VbenDescriptionsItem` children |
|
||||
|
||||
### DescriptionsItem
|
||||
|
||||
Each entry in `items`, or the props of the `VbenDescriptionsItem` child component.
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| label | Label | `string \| number \| (() => VNode) \| Component` | - |
|
||||
| content | Content | `string \| number \| (() => VNode) \| Component` | - |
|
||||
| span | Columns to span, `'filled'` fills the rest of the row | `number \| 'filled' \| Partial<Record<Breakpoint, number>>` | `1` |
|
||||
| labelStyle | Label style | `CSSProperties` | - |
|
||||
| contentStyle | Content style | `CSSProperties` | - |
|
||||
| key | Unique key | `string \| number` | - |
|
||||
|
||||
### DescriptionsItem Slots
|
||||
|
||||
Available only for the child component usage.
|
||||
|
||||
| Slot | Description |
|
||||
| ------- | --------------------------------- |
|
||||
| default | Content (equivalent to `content`) |
|
||||
| content | Custom content |
|
||||
| label | Custom label |
|
||||
|
||||
::: tip Breakpoint
|
||||
|
||||
The responsive `Breakpoint` is one of `'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl'`, with pixel values aligned with Ant Design (`sm` 576, `md` 768, `lg` 992, `xl` 1200, `xxl` 1600, `xxxl` 2000). :::
|
||||
79
docs/src/en/components/common-ui/vben-drawer.md
Normal file
79
docs/src/en/components/common-ui/vben-drawer.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Drawer
|
||||
|
||||
`Vben Drawer` is the shared drawer wrapper used by the framework. It supports auto-height layout, loading state, connected components, and an imperative API similar to the modal API.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```ts
|
||||
const [Drawer, drawerApi] = useVbenDrawer({
|
||||
// props
|
||||
// events
|
||||
});
|
||||
```
|
||||
|
||||
<DemoPreview dir="demos/vben-drawer/basic" />
|
||||
|
||||
## Current Usage Notes
|
||||
|
||||
- If you use `connectedComponent`, the inner and outer components share data through `drawerApi.setData()` and `drawerApi.getData()`.
|
||||
- Default drawer behavior can be adjusted in `apps/<app>/src/bootstrap.ts` through `setDefaultDrawerProps(...)`.
|
||||
- `setState(...)` works on `DrawerState`, not `ModalState`.
|
||||
|
||||
## Shared Data Types
|
||||
|
||||
The recommended approach is to declare the data type once in the connected component and expose `drawerApi`. The outer call then infers the data contract from `connectedComponent`:
|
||||
|
||||
```ts
|
||||
// Connected component
|
||||
const [Drawer, drawerApi] = useVbenDrawer<EditData>();
|
||||
defineExpose({ drawerApi });
|
||||
|
||||
// Outer component, EditData is inferred
|
||||
const [Drawer, drawerApi] = useVbenDrawer({
|
||||
connectedComponent: EditDrawer,
|
||||
});
|
||||
```
|
||||
|
||||
Use `useVbenDrawer<EditData>()` explicitly when the component type cannot expose the contract. For larger features, pre-bind one reusable contract in a separate module:
|
||||
|
||||
```ts
|
||||
export const useEditDrawer = createVbenDrawer<EditData>();
|
||||
```
|
||||
|
||||
The precedence is explicit generic, connected component inference, then `unknown`. Plain SFCs support inference through `defineExpose`; generic SFCs, functional components, and components widened to `Component` should use an explicit generic or contract factory. `getData()` returns `undefined` before `setData()` is called. Include `null` or partial payloads in the data type when they are valid business values.
|
||||
|
||||
## Key Props
|
||||
|
||||
| Prop | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `appendToMain` | mount inside the main content area instead of `body` | `boolean` |
|
||||
| `connectedComponent` | connect an inner component to the drawer wrapper | `Component` |
|
||||
| `closeIconPlacement` | position of the close icon | `'left' \| 'right'` |
|
||||
| `placement` | drawer side | `'left' \| 'right' \| 'top' \| 'bottom'` |
|
||||
| `overlayBlur` | blur amount for the overlay | `number` |
|
||||
| `submitting` | lock drawer interactions while submitting | `boolean` |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `onBeforeClose` | called before close; returning `false` or rejecting prevents close | `() => Promise<boolean \| undefined> \| boolean \| undefined` |
|
||||
| `onOpenChange` | called when open state changes | `(isOpen: boolean) => void` |
|
||||
| `onOpened` | called after open animation completes | `() => void` |
|
||||
| `onClosed` | called after close animation completes | `() => void` |
|
||||
|
||||
## drawerApi
|
||||
|
||||
| Method | Description |
|
||||
| ----------------------- | -------------------------------------- |
|
||||
| `setState(...)` | updates drawer state |
|
||||
| `open()` | opens the drawer |
|
||||
| `close()` | closes the drawer |
|
||||
| `setData(data: TData)` | stores typed shared data |
|
||||
| `getData()` | returns `TData \| undefined` |
|
||||
| `lock(isLocked = true)` | locks the drawer into submitting state |
|
||||
| `unlock()` | alias for `lock(false)` |
|
||||
42
docs/src/en/components/common-ui/vben-ellipsis-text.md
Normal file
42
docs/src/en/components/common-ui/vben-ellipsis-text.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben EllipsisText
|
||||
|
||||
`EllipsisText` displays long text with truncation, tooltip support, and optional expand/collapse behavior.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Pass the text through the default slot and limit the visual width with `maxWidth`.
|
||||
|
||||
<DemoPreview dir="demos/vben-ellipsis-text/line" />
|
||||
|
||||
## Current Props
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `expand` | allow click-to-expand behavior | `boolean` | `false` |
|
||||
| `line` | max visible line count | `number` | `1` |
|
||||
| `maxWidth` | max width of the text area | `number \| string` | `'100%'` |
|
||||
| `placement` | tooltip placement | `'bottom' \| 'left' \| 'right' \| 'top'` | `'top'` |
|
||||
| `tooltip` | enable tooltip | `boolean` | `true` |
|
||||
| `tooltipWhenEllipsis` | only show tooltip when text is actually truncated | `boolean` | `false` |
|
||||
| `ellipsisThreshold` | pixel threshold used when checking truncation | `number` | `3` |
|
||||
| `tooltipBackgroundColor` | tooltip background color | `string` | `''` |
|
||||
| `tooltipColor` | tooltip text color | `string` | `''` |
|
||||
| `tooltipFontSize` | tooltip font size in px | `number` | `14` |
|
||||
| `tooltipMaxWidth` | tooltip max width in px | `number` | - |
|
||||
| `tooltipOverlayStyle` | tooltip content style | `CSSProperties` | `{ textAlign: 'justify' }` |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `expandChange` | fired when expand state changes | `(isExpand: boolean) => void` |
|
||||
|
||||
## Slots
|
||||
|
||||
| Slot | Description |
|
||||
| --------- | ---------------------- |
|
||||
| `tooltip` | custom tooltip content |
|
||||
365
docs/src/en/components/common-ui/vben-form.md
Normal file
365
docs/src/en/components/common-ui/vben-form.md
Normal file
@@ -0,0 +1,365 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Form
|
||||
|
||||
::: warning Field Slot Breaking Change
|
||||
|
||||
Named field slot control bindings are now grouped under `slotProps.componentProps`. The old binding forwards form metadata such as `field`, `formApi`, and `values` to the rendered control, which can produce invalid attributes and Vue runtime warnings.
|
||||
|
||||
```vue
|
||||
<!-- Old usage -->
|
||||
<Input v-bind="slotProps" />
|
||||
|
||||
<!-- New usage -->
|
||||
<Input v-bind="slotProps.componentProps" />
|
||||
```
|
||||
|
||||
Migrate every field slot from `v-bind="slotProps"` to `v-bind="slotProps.componentProps"`. Root metadata remains available for template logic through `field`, `componentField`, `modelValue`, `name`, `disabled`, `isInValid`, `values`, and `formApi`, but it is no longer forwarded automatically to the rendered control.
|
||||
|
||||
In this release, starting a Vben application or Playground development server prints this migration warning in the terminal, and loading the page prints the same warning in the browser console. The warning is excluded from production builds and is planned for removal in the next release.
|
||||
|
||||
:::
|
||||
|
||||
`Vben Form` is the shared form abstraction used across different UI-library variants such as `Ant Design Vue`, `Element Plus`, `Naive UI`, and other adapters added inside this repository.
|
||||
|
||||
It uses [TanStack Form](https://tanstack.com/form/latest/docs/framework/vue/overview) internally for state and validation lifecycles, with [Zod 4](https://zod.dev/v4) schemas. Application code should continue using `useVbenForm`, `FormApi`, and the adapter layer instead of depending on the raw TanStack instance.
|
||||
|
||||
Read the [Zod 4 and TanStack Form migration guide](/en/guide/in-depth/zod-v4-form-migration) before upgrading an existing project.
|
||||
|
||||
> If some details are not obvious from the docs, check the live demos as well.
|
||||
|
||||
## Adapter Setup
|
||||
|
||||
Each app keeps its own adapter layer under `src/adapter/form.ts` and `src/adapter/component/index.ts`.
|
||||
|
||||
The current adapter pattern is:
|
||||
|
||||
- initialize the shared component adapter first
|
||||
- call `setupVbenForm(...)`
|
||||
- map special `v-model:*` prop names through `modelPropNameMap`
|
||||
- keep the form empty state aligned with the actual UI library behavior
|
||||
|
||||
### Form Adapter Example
|
||||
|
||||
```ts
|
||||
import type {
|
||||
FormValues,
|
||||
VbenFormProps as FormProps,
|
||||
VbenFormSchema as FormSchema,
|
||||
} from '@vben/common-ui';
|
||||
|
||||
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: {
|
||||
baseModelPropName: 'value',
|
||||
emptyStateValue: null,
|
||||
modelPropNameMap: {
|
||||
Checkbox: 'checked',
|
||||
Radio: 'checked',
|
||||
Switch: 'checked',
|
||||
Upload: 'fileList',
|
||||
},
|
||||
},
|
||||
rules: {
|
||||
required: (value, _params, ctx) => {
|
||||
if (value === undefined || value === null || value.length === 0) {
|
||||
return $t('ui.formRules.required', [ctx.label]);
|
||||
}
|
||||
return true;
|
||||
},
|
||||
selectRequired: (value, _params, ctx) => {
|
||||
if (value === undefined || value === null) {
|
||||
return $t('ui.formRules.selectRequired', [ctx.label]);
|
||||
}
|
||||
return true;
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
function useVbenForm<TValues extends FormValues = FormValues>(
|
||||
options: FormProps<ComponentType, Record<never, never>, TValues>,
|
||||
) {
|
||||
return useForm<TValues, ComponentType, Record<never, never>>(options);
|
||||
}
|
||||
|
||||
export { useVbenForm, z };
|
||||
export type VbenFormSchema<TValues extends FormValues = FormValues> =
|
||||
FormSchema<ComponentType, Record<never, never>, TValues>;
|
||||
export type VbenFormProps<TValues extends FormValues = FormValues> = FormProps<
|
||||
ComponentType,
|
||||
Record<never, never>,
|
||||
TValues
|
||||
>;
|
||||
```
|
||||
|
||||
### Component Adapter Example
|
||||
|
||||
```ts
|
||||
import type { Component, SetupContext } from 'vue';
|
||||
|
||||
import type { BaseFormComponentType } from '@vben/common-ui';
|
||||
|
||||
import { h } from 'vue';
|
||||
|
||||
import { globalShareState } from '@vben/common-ui';
|
||||
import { $t } from '@vben/locales';
|
||||
import {
|
||||
AutoComplete,
|
||||
Button,
|
||||
Checkbox,
|
||||
CheckboxGroup,
|
||||
DatePicker,
|
||||
Divider,
|
||||
Input,
|
||||
InputNumber,
|
||||
InputPassword,
|
||||
Mentions,
|
||||
notification,
|
||||
Radio,
|
||||
RadioGroup,
|
||||
RangePicker,
|
||||
Rate,
|
||||
Select,
|
||||
Space,
|
||||
Switch,
|
||||
Textarea,
|
||||
TimePicker,
|
||||
TreeSelect,
|
||||
Upload,
|
||||
} from 'antdv-next';
|
||||
|
||||
const withDefaultPlaceholder = <T extends Component>(
|
||||
component: T,
|
||||
type: 'input' | 'select',
|
||||
) => {
|
||||
return (props: any, { attrs, slots }: Omit<SetupContext, 'expose'>) => {
|
||||
const placeholder = props?.placeholder || $t(`ui.placeholder.${type}`);
|
||||
return h(component, { ...props, ...attrs, placeholder }, slots);
|
||||
};
|
||||
};
|
||||
|
||||
export type ComponentType =
|
||||
| 'AutoComplete'
|
||||
| 'Checkbox'
|
||||
| 'CheckboxGroup'
|
||||
| 'DatePicker'
|
||||
| 'DefaultButton'
|
||||
| 'Divider'
|
||||
| 'Input'
|
||||
| 'InputNumber'
|
||||
| 'InputPassword'
|
||||
| 'Mentions'
|
||||
| 'PrimaryButton'
|
||||
| 'Radio'
|
||||
| 'RadioGroup'
|
||||
| 'RangePicker'
|
||||
| 'Rate'
|
||||
| 'Select'
|
||||
| 'Space'
|
||||
| 'Switch'
|
||||
| 'Textarea'
|
||||
| 'TimePicker'
|
||||
| 'TreeSelect'
|
||||
| 'Upload'
|
||||
| BaseFormComponentType;
|
||||
|
||||
async function initComponentAdapter() {
|
||||
const components: Partial<Record<ComponentType, Component>> = {
|
||||
AutoComplete,
|
||||
Checkbox,
|
||||
CheckboxGroup,
|
||||
DatePicker,
|
||||
DefaultButton: (props, { attrs, slots }) => {
|
||||
return h(Button, { ...props, attrs, type: 'default' }, slots);
|
||||
},
|
||||
Divider,
|
||||
Input: withDefaultPlaceholder(Input, 'input'),
|
||||
InputNumber: withDefaultPlaceholder(InputNumber, 'input'),
|
||||
InputPassword: withDefaultPlaceholder(InputPassword, 'input'),
|
||||
Mentions: withDefaultPlaceholder(Mentions, 'input'),
|
||||
PrimaryButton: (props, { attrs, slots }) => {
|
||||
return h(Button, { ...props, attrs, type: 'primary' }, slots);
|
||||
},
|
||||
Radio,
|
||||
RadioGroup,
|
||||
RangePicker,
|
||||
Rate,
|
||||
Select: withDefaultPlaceholder(Select, 'select'),
|
||||
Space,
|
||||
Switch,
|
||||
Textarea: withDefaultPlaceholder(Textarea, 'input'),
|
||||
TimePicker,
|
||||
TreeSelect: withDefaultPlaceholder(TreeSelect, 'select'),
|
||||
Upload,
|
||||
};
|
||||
|
||||
globalShareState.setComponents(components);
|
||||
globalShareState.defineMessage({
|
||||
copyPreferencesSuccess: (title, content) => {
|
||||
notification.success({
|
||||
description: content,
|
||||
message: title,
|
||||
placement: 'bottomRight',
|
||||
});
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export { initComponentAdapter };
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Create the form through `useVbenForm`:
|
||||
|
||||
<DemoPreview dir="demos/vben-form/basic" />
|
||||
|
||||
## Typed Values and Slots
|
||||
|
||||
Use `useVbenForm<TFormValues, TSubmitValues>` to declare component-facing form values and submission values separately. Schema, slots, selectors, and `setValues` use `TFormValues`; `getValues()` and `submit()` return `Promise<TSubmitValues>`, while `submit()` only accepts an optional native `Event`; the first `handleSubmit` argument is `TSubmitValues`. Pass one generic when both shapes are identical.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { useVbenForm } from '#/adapter/form';
|
||||
|
||||
interface AccountFormValues {
|
||||
email: string;
|
||||
nickname: string;
|
||||
}
|
||||
|
||||
const [Form, formApi] = useVbenForm<AccountFormValues>({
|
||||
handleSubmit(values) {
|
||||
return addAccount(values); // AccountFormValues
|
||||
},
|
||||
schema: [
|
||||
{ component: 'Input', fieldName: 'email', label: 'Email' },
|
||||
{ component: 'Input', fieldName: 'nickname', label: 'Nickname' },
|
||||
],
|
||||
});
|
||||
|
||||
async function fillForm() {
|
||||
await formApi.setValues({ email: 'user@example.com' });
|
||||
return formApi.getValues(); // Promise<AccountFormValues>
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<Form>
|
||||
<template #email="{ componentField, field, formApi, values }">
|
||||
<!-- field.state.value and componentField.modelValue are strings -->
|
||||
<input v-bind="componentField" :data-email="values.email" />
|
||||
<button type="button" @click="formApi.clearValidation('email')">
|
||||
Clear
|
||||
</button>
|
||||
</template>
|
||||
<template #default="{ formApi, shapes, values }">
|
||||
<button type="button" @click="formApi.submit()">
|
||||
Submit {{ shapes.length }} fields for {{ values.email }}
|
||||
</button>
|
||||
</template>
|
||||
</Form>
|
||||
</template>
|
||||
```
|
||||
|
||||
Named field slots expose grouped control bindings through `componentProps`, together with `field`, `componentField`, `modelValue`, `name`, `disabled`, `isInValid`, `values`, and `formApi`. The default slot exposes `shapes`, `values`, and `formApi`; action slots expose `values` and `formApi`.
|
||||
|
||||
Use a precise form-value interface without a string index signature to infer each field value. A broad type such as `Record<string, unknown>` keeps the complete slot-prop structure instead of degrading the whole scope to `any`, but field values can only use the declared index value type.
|
||||
|
||||
## Field Slots
|
||||
|
||||
Control bindings are grouped under `componentProps`. It contains the model value, matching `update:*` event, schema/common/dependency props, and disabled state:
|
||||
|
||||
```vue
|
||||
<Form>
|
||||
<template #fieldName="slotProps">
|
||||
<Input v-bind="slotProps.componentProps" />
|
||||
</template>
|
||||
</Form>
|
||||
```
|
||||
|
||||
Root metadata remains available for template logic through `field`, `componentField`, `modelValue`, `name`, `disabled`, `isInValid`, `values`, and `formApi`; it is not forwarded automatically to the rendered control.
|
||||
|
||||
## Form Codec
|
||||
|
||||
Use the form-level `codec` when component values and the backend payload have different shapes. `encode` converts the complete `TFormValues` object to `TSubmitValues`; `decode` performs the inverse conversion. Multi-field splits and merges are atomic and do not depend on schema order or string-path writes.
|
||||
|
||||
Define `codec` directly in the `useVbenForm` options. Annotate only the form-value input of `encode`; `TSubmitValues` is inferred from its return object and flows into `decode`, `getValues()`, and submit callbacks:
|
||||
|
||||
```ts
|
||||
const [Form, formApi] = useVbenForm({
|
||||
codec: {
|
||||
decode(values) {
|
||||
return { period: [values.startTime, values.endTime] };
|
||||
},
|
||||
encode(values: Readonly<FormValues>) {
|
||||
return {
|
||||
endTime: values.period[1],
|
||||
startTime: values.period[0],
|
||||
};
|
||||
},
|
||||
},
|
||||
schema,
|
||||
});
|
||||
```
|
||||
|
||||
<DemoPreview dir="demos/vben-form/value-format" />
|
||||
|
||||
`schema.valueFormat`, `fieldMappingTime`, and `arrayToStringFields` remain runtime-compatible but are deprecated. When a codec is configured it takes precedence and deprecated transforms are ignored.
|
||||
|
||||
## Performance Benchmarks
|
||||
|
||||
The form benchmarks cover component initialization, single-field and batch updates, reset, Zod validation, dynamic schemas, dependencies, codec encoding and snapshots, plus array editing, row mutations, and child-schema updates. Run the complete benchmark suite with:
|
||||
|
||||
```bash
|
||||
pnpm test:benchmark
|
||||
```
|
||||
|
||||
To run only the form benchmarks, pass both files explicitly:
|
||||
|
||||
```bash
|
||||
pnpm exec vitest bench --run packages/@core/ui-kit/form-ui/__tests__/form-component-performance.benchmark.ts packages/@core/ui-kit/form-ui/__tests__/form-performance.benchmark.ts
|
||||
```
|
||||
|
||||
Use benchmark results to compare relative changes on the same machine and runtime; do not treat one run's absolute timings as portable thresholds. Stop CPU-intensive development servers first and keep the Node.js version consistent. Benchmark files are not included in the regular `test:unit` command.
|
||||
|
||||
::: warning Mounted form context
|
||||
|
||||
`formApi.form` is the `FormContextApi` injected after `<Form />` mounts. Do not destructure or cache `form` from the second `useVbenForm` return value during setup, because that captures the pre-mount empty reference. Prefer mount-aware public methods such as `getRawValues()`, `setFieldError()`, `setFieldValue()`, and `validate()` for business actions. Access fine-grained subscription methods on `formApi.form` only from an already-mounted form context.
|
||||
|
||||
:::
|
||||
|
||||
## Key API Notes
|
||||
|
||||
- `useVbenForm` returns `[Form, formApi]`
|
||||
- `useVbenForm<TFormValues, TSubmitValues>` keeps component values and submission values distinct
|
||||
- prefer `reset`, `submit`, `validateAndSubmit`, and `clearValidation`
|
||||
- `resetForm`, `submitForm`, `validateAndSubmitForm`, and `resetValidate` remain deprecated aliases that warn once in development
|
||||
- `clearValidation` invalidates in-flight async results before clearing errors
|
||||
- `formApi.getFieldComponentRef()` and `formApi.getFocusedField()` are available in current versions
|
||||
- `handleValuesChange(values, fieldsChanged)` receives readonly `TFormValues` before codec or legacy formatting
|
||||
- its third `getFormattedValues` argument formats lazily, so raw-only change handlers avoid clone and transform work
|
||||
- `getRawValues()` returns only an independent raw snapshot, `getValues()` returns only the formatted payload, and `getValueSnapshot()` returns both
|
||||
- `handleSubmit(values, rawValues)` receives the formatted payload and its corresponding raw snapshot
|
||||
- `fieldMappingTime`, `arrayToStringFields`, and `schema.valueFormat` are deprecated compatibility options
|
||||
- `codec.encode` defines the `getValues()` payload and `codec.decode` powers complete `setSubmitValues()` fills
|
||||
- `formApi.form` exposes the mounted `FormContextApi`; do not destructure or cache it before `<Form />` mounts
|
||||
- prefer `formApi.form.useFieldValue`, `useFieldValues`, and `useFieldError` for fine-grained subscriptions; use `useValues` only when the whole form is required
|
||||
- `useSelector` remains the compatibility selector for combined `{ values, errors, meta }` state
|
||||
- legacy `setupVbenForm({ defineRules })` still works, warns once in development, and is silent in production; use `rules` for new code
|
||||
- prefer `dependencies: { triggerFields, resolve(context) }` for one atomic dynamic-state patch; legacy dependency callbacks remain supported but are deprecated and warn once in development
|
||||
- top-level `componentProps`, `help`, and `renderComponentContent` functions receive `FormSchemaContext`; value-dependent rendering belongs in `dependencies.resolve`
|
||||
- use `formFieldProps.validateOn` with `blur` and/or `change`; submit always validates, and `asyncDebounceMs` debounces async validators
|
||||
- use `changeEventFallback: true` only for components that emit `change` without an `update:*` event
|
||||
|
||||
## Reference
|
||||
|
||||
For the complete Chinese API tables and more examples, see the Chinese component page if you need the full parameter matrix.
|
||||
79
docs/src/en/components/common-ui/vben-modal.md
Normal file
79
docs/src/en/components/common-ui/vben-modal.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Modal
|
||||
|
||||
`Vben Modal` is the shared modal wrapper used by the framework. It supports draggable behavior, fullscreen mode, auto-height handling, loading state, connected components, and an imperative API.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```ts
|
||||
const [Modal, modalApi] = useVbenModal({
|
||||
// props
|
||||
// events
|
||||
});
|
||||
```
|
||||
|
||||
<DemoPreview dir="demos/vben-modal/basic" />
|
||||
|
||||
## Current Usage Notes
|
||||
|
||||
- If you use `connectedComponent`, the inner and outer components share data through `modalApi.setData()` and `modalApi.getData()`.
|
||||
- When `connectedComponent` is present, avoid pushing extra modal props through the connected side. Prefer `useVbenModal(...)` or `modalApi.setState(...)`.
|
||||
- Default modal behavior can be adjusted in `apps/<app>/src/bootstrap.ts` through `setDefaultModalProps(...)`.
|
||||
|
||||
## Shared Data Types
|
||||
|
||||
The recommended approach is to declare the data type once in the connected component and expose `modalApi`. The outer call then infers the data contract from `connectedComponent`:
|
||||
|
||||
```ts
|
||||
// Connected component
|
||||
const [Modal, modalApi] = useVbenModal<EditData>();
|
||||
defineExpose({ modalApi });
|
||||
|
||||
// Outer component, EditData is inferred
|
||||
const [Modal, modalApi] = useVbenModal({
|
||||
connectedComponent: EditModal,
|
||||
});
|
||||
```
|
||||
|
||||
Use `useVbenModal<EditData>()` explicitly when the component type cannot expose the contract. For larger features, pre-bind one reusable contract in a separate module:
|
||||
|
||||
```ts
|
||||
export const useEditModal = createVbenModal<EditData>();
|
||||
```
|
||||
|
||||
The precedence is explicit generic, connected component inference, then `unknown`. Plain SFCs support inference through `defineExpose`; generic SFCs, functional components, and components widened to `Component` should use an explicit generic or contract factory. `getData()` returns `undefined` before `setData()` is called. Include `null` or partial payloads in the data type when they are valid business values.
|
||||
|
||||
## Key Props
|
||||
|
||||
| Prop | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `appendToMain` | mount inside the main content area instead of `body` | `boolean` |
|
||||
| `connectedComponent` | connect an inner component to the modal wrapper | `Component` |
|
||||
| `animationType` | modal enter/leave animation | `'slide' \| 'scale'` |
|
||||
| `fullscreenButton` | show or hide the fullscreen toggle | `boolean` |
|
||||
| `overlayBlur` | blur amount for the overlay | `number` |
|
||||
| `submitting` | lock modal interactions while submitting | `boolean` |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `onBeforeClose` | called before close; returning `false` or rejecting prevents close | `() => Promise<boolean \| undefined> \| boolean \| undefined` |
|
||||
| `onOpenChange` | called when open state changes | `(isOpen: boolean) => void` |
|
||||
| `onOpened` | called after open animation completes | `() => void` |
|
||||
| `onClosed` | called after close animation completes | `() => void` |
|
||||
|
||||
## modalApi
|
||||
|
||||
| Method | Description |
|
||||
| ----------------------- | ------------------------------------- |
|
||||
| `setState(...)` | updates modal state |
|
||||
| `open()` | opens the modal |
|
||||
| `close()` | closes the modal |
|
||||
| `setData(data: TData)` | stores typed shared data |
|
||||
| `getData()` | returns `TData \| undefined` |
|
||||
| `lock(isLocked = true)` | locks the modal into submitting state |
|
||||
| `unlock()` | alias for `lock(false)` |
|
||||
165
docs/src/en/components/common-ui/vben-table-action.md
Normal file
165
docs/src/en/components/common-ui/vben-table-action.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben TableAction
|
||||
|
||||
`TableAction` renders a group of action buttons for table operation columns, inspired by the TableAction component from vben2. Built on shadcn-ui, it supports permission control, popconfirm, tooltips, a "more" dropdown, and dividers, and can be reused inside or outside tables.
|
||||
|
||||
> If the documentation does not cover the details you need, please refer to the online examples.
|
||||
|
||||
::: info Before you start
|
||||
|
||||
The component carries no business logic (it does not read the permission store directly); permissions are handled by injecting `hasPermission`, keeping the core layer decoupled and reusable across frameworks. Inside vxe-table, the recommended approach is to render it via a column slot (`slots: { default: 'action' }`) on the page, without changing the table's original rendering mechanism. :::
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Pass an array of action items via `actions`, each with `text`, `onClick`, etc. `danger` marks destructive actions, and `divider` shows separators between buttons.
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/basic" />
|
||||
|
||||
## Tooltip
|
||||
|
||||
Add a tooltip to an action via `tooltip`, accepting a string or a `{ content, side }` object.
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/tooltip" />
|
||||
|
||||
## PopConfirm
|
||||
|
||||
Use `popConfirm` to require confirmation before the action runs, commonly used for destructive actions like delete.
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/popconfirm" />
|
||||
|
||||
## More Dropdown
|
||||
|
||||
Use `dropdownActions` to collapse secondary actions into a "more" dropdown. `moreText` customizes the button label.
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/dropdown" />
|
||||
|
||||
## Permission Control
|
||||
|
||||
Set an `auth` code on an action and inject a `hasPermission` resolver; actions without permission are hidden.
|
||||
|
||||
<DemoPreview dir="demos/vben-table-action/permission" />
|
||||
|
||||
## Usage with vxe-table
|
||||
|
||||
Without changing vxe-table's rendering mechanism, declare a slot in the column config and render it on the page.
|
||||
|
||||
::: tip Recommended: use the adapter-wrapped version The project's `#/adapter/vxe-table` re-wraps `VbenTableAction` and injects `hasPermission` internally (based on `useAccess().hasAccessByCodes`). So when you import it from the adapter, **you no longer need to pass `:has-permission`** — just declare permission codes via the `auth` field of each action. :::
|
||||
|
||||
```ts
|
||||
// data.ts — declare a slot in the column config
|
||||
{
|
||||
align: 'center',
|
||||
field: 'operation',
|
||||
fixed: 'right',
|
||||
slots: { default: 'action' },
|
||||
title: $t('system.user.operation'),
|
||||
width: 180,
|
||||
}
|
||||
```
|
||||
|
||||
```vue
|
||||
<!-- list.vue — import from the adapter; permission is auto-injected, no has-permission needed -->
|
||||
<script setup lang="ts">
|
||||
import { VbenTableAction } from '#/adapter/vxe-table';
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<Grid>
|
||||
<template #action="{ row }">
|
||||
<template #action="{ row }">
|
||||
<VbenTableAction
|
||||
:actions="[
|
||||
{
|
||||
text: $t('common.detail'),
|
||||
icon: 'lucide:eye',
|
||||
onClick: () => onDetail(row),
|
||||
},
|
||||
{
|
||||
text: $t('common.edit'),
|
||||
icon: 'lucide:edit',
|
||||
onClick: () => onEdit(row),
|
||||
},
|
||||
]"
|
||||
:dropdown-actions="[
|
||||
{
|
||||
text: $t('common.delete'),
|
||||
icon: 'lucide:trash-2',
|
||||
danger: true,
|
||||
onClick: () => onDelete(row),
|
||||
auth: ['AC_100100'],
|
||||
},
|
||||
]"
|
||||
align="center"
|
||||
/>
|
||||
</template>
|
||||
</template>
|
||||
</Grid>
|
||||
</template>
|
||||
```
|
||||
|
||||
If you import the core component directly from `@vben/common-ui` (without going through the adapter), the component carries no business logic and you need to inject `hasPermission` yourself:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { useAccess } from '@vben/access';
|
||||
import { VbenTableAction } from '@vben/common-ui';
|
||||
|
||||
const { hasAccessByCodes } = useAccess();
|
||||
function hasPermission(auth?: string | string[]) {
|
||||
if (!auth) return true;
|
||||
return hasAccessByCodes(Array.isArray(auth) ? auth : [auth]);
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<VbenTableAction
|
||||
v-bind="useActions(row, onActionClick)"
|
||||
:has-permission="hasPermission"
|
||||
align="center"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### TableAction Props
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| actions | Main action buttons | `ActionItem[]` | `[]` |
|
||||
| dropdownActions | Actions inside the "more" dropdown | `ActionItem[]` | `[]` |
|
||||
| align | Alignment | `'start' \| 'center' \| 'end'` | `'end'` |
|
||||
| divider | Whether to show separators between buttons | `boolean` | `false` |
|
||||
| moreText | Label for the "more" button (shown beside the icon) | `string` | - |
|
||||
| hasPermission | Permission resolver; returning `false` hides the action with that `auth` (auto-injected when imported from `#/adapter/vxe-table`, no need to pass manually) | `(auth?: string \| string[]) => boolean` | - |
|
||||
| class | Custom class for the root node | `string` | - |
|
||||
|
||||
### ActionItem
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| text | Button text | `string` | - |
|
||||
| icon | Icon component | `string` \| `VbenIcon` | - |
|
||||
| onClick | Click callback | `() => void` | - |
|
||||
| auth | Permission code, filtered by `hasPermission` | `string \| string[]` | - |
|
||||
| ifShow | Whether to show | `boolean \| (() => boolean)` | `true` |
|
||||
| disabled | Whether disabled | `boolean` | `false` |
|
||||
| loading | Loading state | `boolean` | `false` |
|
||||
| danger | Destructive action (red text) | `boolean` | `false` |
|
||||
| tooltip | Tooltip | `string \| { content: string; side?: 'top' \| 'bottom' \| 'left' \| 'right' }` | - |
|
||||
| popConfirm | PopConfirm | `TableActionPopConfirm` | - |
|
||||
| variant | Button variant | `ButtonVariants['variant']` | `'link'` |
|
||||
| size | Button size | `ButtonVariants['size']` | `'sm'` |
|
||||
| key | Unique key | `string \| number` | - |
|
||||
|
||||
### TableActionPopConfirm
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| title | Confirm title | `string` | `'Are you sure?'` |
|
||||
| okText | Confirm button text | `string` | `'OK'` |
|
||||
| cancelText | Cancel button text | `string` | `'Cancel'` |
|
||||
| confirm | Confirm callback; falls back to `action.onClick` if omitted | `() => void` | - |
|
||||
199
docs/src/en/components/common-ui/vben-tiptap.md
Normal file
199
docs/src/en/components/common-ui/vben-tiptap.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Tiptap Rich Text Editor
|
||||
|
||||
A rich text editor component built on [Tiptap](https://tiptap.dev/), supporting rich text formatting, image insertion, and image upload features.
|
||||
|
||||
> If some details are not obvious from the docs, check the live demos as well.
|
||||
|
||||
::: info Note
|
||||
|
||||
If you feel the current component implementation doesn't meet your needs, you can use native components directly or create your own component. The components provided by the framework are not constraints - use them at your discretion.
|
||||
|
||||
:::
|
||||
|
||||
## Basic Usage
|
||||
|
||||
<DemoPreview dir="demos/vben-tiptap/basic" />
|
||||
|
||||
## Component List
|
||||
|
||||
### VbenTiptap
|
||||
|
||||
Main rich text editor component.
|
||||
|
||||
### VbenTiptapPreview
|
||||
|
||||
Read-only preview component for displaying editor content.
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| Property | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `modelValue` (v-model) | Editor content (HTML string) | `string` | `''` |
|
||||
| `editable` | Whether the editor is editable | `boolean` | `true` |
|
||||
| `toolbar` | Whether to show the toolbar | `boolean` | `true` |
|
||||
| `previewable` | Whether to show the preview button | `boolean` | `true` |
|
||||
| `placeholder` | Placeholder text | `string` | - |
|
||||
| `minHeight` | Minimum height | `number \| string` | `240` |
|
||||
| `maxHeight` | Maximum height | `number \| string` | `400` |
|
||||
| `extensions` | Custom Tiptap extensions | `Extensions` | - |
|
||||
| `imageUpload` | Image upload configuration | `ImageUploadOptions` | - |
|
||||
|
||||
### Events
|
||||
|
||||
| Event | Description | Parameters |
|
||||
| -------- | ------------------------------ | ----------------------- |
|
||||
| `change` | Triggered when content changes | `VbenTiptapChangeEvent` |
|
||||
|
||||
#### VbenTiptapChangeEvent
|
||||
|
||||
```ts
|
||||
interface VbenTiptapChangeEvent {
|
||||
html: string; // HTML content
|
||||
json: JSONContent; // JSON structure
|
||||
text: string; // Plain text content
|
||||
}
|
||||
```
|
||||
|
||||
### ImageUploadOptions
|
||||
|
||||
Image upload configuration:
|
||||
|
||||
```ts
|
||||
interface ImageUploadOptions {
|
||||
/** Allowed file types, default 'image/*' */
|
||||
accept?: string;
|
||||
/** Max file size in bytes, default 5MB */
|
||||
maxSize?: number;
|
||||
/** Upload error callback, uses alert if not provided */
|
||||
onUploadError?: (error: unknown) => void;
|
||||
/** Upload function, returns image URL */
|
||||
upload: (
|
||||
file: File,
|
||||
onProgress?: (percent: number) => void,
|
||||
) => Promise<string>;
|
||||
}
|
||||
```
|
||||
|
||||
### VbenTiptapPreview Props
|
||||
|
||||
| Property | Description | Type | Default |
|
||||
| ----------- | ----------------------- | ------------------ | ------- |
|
||||
| `content` | HTML content to preview | `string` | `''` |
|
||||
| `minHeight` | Minimum height | `number \| string` | `160` |
|
||||
| `class` | Custom class name | `any` | - |
|
||||
|
||||
## Toolbar Features
|
||||
|
||||
The editor toolbar provides the following features:
|
||||
|
||||
### Formatting
|
||||
|
||||
- **Undo/Redo** - Undo or redo editing operations
|
||||
- **Clear Formatting** - Remove all formatting from selected text
|
||||
- **Bold** - Bold text
|
||||
- **Italic** - Italic text
|
||||
- **Underline** - Underline text
|
||||
- **Strikethrough** - Strikethrough text
|
||||
- **Inline Code** - Inline code mark
|
||||
|
||||
### Structure
|
||||
|
||||
- **Headings** - Paragraph, H1-H4 heading switching
|
||||
- **Ordered List** - Numbered list
|
||||
- **Bullet List** - Bulleted list
|
||||
- **Blockquote** - Quote block style
|
||||
- **Code Block** - Multi-line code block
|
||||
|
||||
### Links & Images
|
||||
|
||||
- **Insert Link** - Insert or edit hyperlinks
|
||||
- **Remove Link** - Remove link from selected text
|
||||
- **Insert Image** - Insert image via URL
|
||||
|
||||
### Style
|
||||
|
||||
- **Text Color** - Set text color (preset palette)
|
||||
- **Highlight Color** - Set text background highlight color
|
||||
|
||||
### Alignment
|
||||
|
||||
- **Align Left** - Left align text
|
||||
- **Align Center** - Center align text
|
||||
- **Align Right** - Right align text
|
||||
|
||||
### Other
|
||||
|
||||
- **Preview** - Preview content in a modal
|
||||
|
||||
## Image Upload
|
||||
|
||||
<DemoPreview dir="demos/vben-tiptap/image-upload" />
|
||||
|
||||
When `imageUpload` is configured, the toolbar image button becomes a dropdown menu with "Upload" and "URL" options.
|
||||
|
||||
### Upload Methods
|
||||
|
||||
Three image upload methods are supported:
|
||||
|
||||
1. **File Selection** - Click the upload button in toolbar
|
||||
2. **Drag & Drop** - Drag images directly into the editor
|
||||
3. **Paste** - Paste images into the editor
|
||||
|
||||
### Upload Progress Display
|
||||
|
||||
During upload:
|
||||
|
||||
- **Loading Indicator** - Spinner animation indicating upload in progress
|
||||
- **Progress Bar** - Shows progress bar when upload function provides `onProgress` callback
|
||||
|
||||
### File Validation
|
||||
|
||||
- `accept` - Specify allowed file types (MIME types)
|
||||
- `maxSize` - Maximum file size limit (bytes)
|
||||
- Validation failure triggers `onUploadError` callback or default alert
|
||||
|
||||
::: warning Important Notes
|
||||
|
||||
- Only single image upload is supported; multi-image drag/paste will show a prompt and process only the first image
|
||||
- Do not save editor content (`getHTML()`) during upload as image URLs are temporary blob URLs
|
||||
- When using custom `extensions`, the image upload feature will not be available (toolbar won't show upload option)
|
||||
|
||||
:::
|
||||
|
||||
## Custom Extensions
|
||||
|
||||
Pass custom Tiptap extension configurations via the `extensions` property:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { VbenTiptap } from '@vben/plugins/tiptap';
|
||||
import StarterKit from '@tiptap/starter-kit';
|
||||
import Underline from '@tiptap/extension-underline';
|
||||
|
||||
const extensions = [
|
||||
StarterKit,
|
||||
Underline,
|
||||
// Other extensions...
|
||||
];
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<VbenTiptap v-model="content" :extensions="extensions" />
|
||||
</template>
|
||||
```
|
||||
|
||||
::: warning Custom Extensions Note
|
||||
|
||||
When using custom `extensions`:
|
||||
|
||||
- Default extension configuration will not take effect
|
||||
- Image upload feature is not available (toolbar won't show upload option)
|
||||
- You need to configure all required editor features yourself
|
||||
|
||||
:::
|
||||
87
docs/src/en/components/common-ui/vben-vxe-table.md
Normal file
87
docs/src/en/components/common-ui/vben-vxe-table.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Vxe Table
|
||||
|
||||
`Vben Vxe Table` wraps `vxe-table` together with `Vben Form` so you can build searchable data grids with a shared API.
|
||||
|
||||
## Adapter Example
|
||||
|
||||
The current renderer adapter uses `renderTableDefault(...)` for table cell rendering:
|
||||
|
||||
```ts
|
||||
vxeUI.renderer.add('CellImage', {
|
||||
renderTableDefault(_renderOpts, params) {
|
||||
const { column, row } = params;
|
||||
return h(Image, { src: row[column.field] });
|
||||
},
|
||||
});
|
||||
|
||||
vxeUI.renderer.add('CellLink', {
|
||||
renderTableDefault(renderOpts) {
|
||||
const { props } = renderOpts;
|
||||
return h(
|
||||
Button,
|
||||
{ size: 'small', type: 'link' },
|
||||
{ default: () => props?.text },
|
||||
);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { useVbenVxeGrid } from '#/adapter/vxe-table';
|
||||
|
||||
const [Grid, gridApi] = useVbenVxeGrid({
|
||||
gridOptions: {},
|
||||
formOptions: {},
|
||||
gridEvents: {},
|
||||
});
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<Grid />
|
||||
</template>
|
||||
```
|
||||
|
||||
<DemoPreview dir="demos/vben-vxe-table/basic" />
|
||||
|
||||
## GridApi
|
||||
|
||||
| Method | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `setLoading` | update loading state | `(loading: boolean) => void` |
|
||||
| `setGridOptions` | merge new grid options | `(options: Partial<VxeGridProps['gridOptions']>) => void` |
|
||||
| `reload` | reload data and reset pagination | `(params?: Record<string, any>) => void` |
|
||||
| `query` | query data while keeping the current page | `(params?: Record<string, any>) => void` |
|
||||
| `grid` | `vxe-grid` instance | `VxeGridInstance` |
|
||||
| `formApi` | search form API | `FormApi` |
|
||||
| `toggleSearchForm` | toggle or force the search form visible state | `(show?: boolean) => boolean` |
|
||||
|
||||
## Props
|
||||
|
||||
| Prop | Description | Type |
|
||||
| --- | --- | --- |
|
||||
| `tableTitle` | table title | `string` |
|
||||
| `tableTitleHelp` | help text for the table title | `string` |
|
||||
| `class` | class for the outer container | `string` |
|
||||
| `gridClass` | class for the `vxe-grid` node | `string` |
|
||||
| `gridOptions` | `vxe-grid` options | `DeepPartial<VxeTableGridOptions>` |
|
||||
| `gridEvents` | `vxe-grid` event handlers | `DeepPartial<VxeGridListeners>` |
|
||||
| `formOptions` | search form options | `VbenFormProps` |
|
||||
| `showSearchForm` | whether the search form is visible | `boolean` |
|
||||
| `separator` | separator between the search form and table body | `boolean \| SeparatorOptions` |
|
||||
|
||||
## Slots
|
||||
|
||||
| Slot | Description |
|
||||
| ----------------- | ------------------------------------------------------- |
|
||||
| `toolbar-actions` | left side of the toolbar, near the title |
|
||||
| `toolbar-tools` | right side of the toolbar, before built-in tool buttons |
|
||||
| `table-title` | custom table title |
|
||||
|
||||
All named slots starting with `form-` are forwarded to the search form.
|
||||
15
docs/src/en/components/introduction.md
Normal file
15
docs/src/en/components/introduction.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Introduction
|
||||
|
||||
::: info README
|
||||
|
||||
This section documents the framework components, including their usage patterns, configuration points, and major APIs. If the built-in wrappers do not fit your needs, you can always use native components directly or build your own abstractions.
|
||||
|
||||
:::
|
||||
|
||||
## Layout Components
|
||||
|
||||
Layout components are usually used as top-level containers inside the page content area. They provide shared layout styles and some baseline behavior.
|
||||
|
||||
## Common Components
|
||||
|
||||
Common components include frequently used UI building blocks such as modals, drawers, forms, and API-backed selectors. Most of them are implemented on top of shared Tailwind CSS and shadcn-vue based primitives, while still allowing each app to adapt them to its own UI library.
|
||||
29
docs/src/en/components/layout-ui/page.md
Normal file
29
docs/src/en/components/layout-ui/page.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Page
|
||||
|
||||
`Page` is the standard top-level layout container for business pages. It provides a header area, a content area, and an optional footer area.
|
||||
|
||||
## Props
|
||||
|
||||
| Prop | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `title` | page title | `string \| slot` | - |
|
||||
| `description` | page description | `string \| slot` | - |
|
||||
| `contentClass` | class for the content area | `string` | - |
|
||||
| `headerClass` | class for the header area | `string` | - |
|
||||
| `footerClass` | class for the footer area | `string` | - |
|
||||
| `autoContentHeight` | auto-calculate the content area height from the visible layout height | `boolean` | `false` |
|
||||
| `heightOffset` | extra height offset subtracted from the content area when auto height is enabled | `number` | `0` |
|
||||
|
||||
## Slots
|
||||
|
||||
| Slot | Description |
|
||||
| ------------- | ------------------------- |
|
||||
| `default` | page content |
|
||||
| `title` | custom title |
|
||||
| `description` | custom description |
|
||||
| `extra` | right-side header content |
|
||||
| `footer` | footer content |
|
||||
242
docs/src/en/guide/in-depth/zod-v4-form-migration.md
Normal file
242
docs/src/en/guide/in-depth/zod-v4-form-migration.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Zod 4 and TanStack Form Migration
|
||||
|
||||
This migration upgrades form schemas from Zod 3 to Zod 4 and replaces vee-validate with TanStack Form internally. The Vben business API remains stable while implementation-specific form APIs are removed from the public boundary.
|
||||
|
||||
## Dependency Changes
|
||||
|
||||
| Area | Before | After |
|
||||
| --- | --- | --- |
|
||||
| Schema | `zod@^3.25.76` | `zod@^4.4.3` |
|
||||
| Defaults | `zod-defaults@0.1.3` | `zod-defaults@^0.2.3` |
|
||||
| Form engine | `vee-validate@^4.15.1` | `@tanstack/vue-form@^1.33.2` |
|
||||
| Zod adapter | `@vee-validate/zod@^4.15.1` | Removed; TanStack Form supports Standard Schema |
|
||||
|
||||
Source files, package manifests, and the lockfile must no longer depend on `vee-validate` or `@vee-validate/zod`.
|
||||
|
||||
## Compatibility Boundary
|
||||
|
||||
The following Vben APIs remain supported:
|
||||
|
||||
- `useVbenForm(options)` returning `[Form, formApi]`
|
||||
- existing `FormApi` methods for values, reset, validation, submission, schema updates, and component refs
|
||||
- existing `FormSchema` fields, dependencies, deprecated `valueFormat`, and array schema structure
|
||||
- application adapters and the re-exported `z` namespace
|
||||
- the existing `componentField` slot and binding shape
|
||||
|
||||
`formApi.form` is now the library-independent `FormContextApi`. It exposes values, errors, meta, set/reset/validate/submit methods, and array operations without leaking vee or raw TanStack generics.
|
||||
|
||||
New code uses `reset`, `submit`, `validateAndSubmit`, and `clearValidation`. The former `resetForm`, `submitForm`, `validateAndSubmitForm`, and `resetValidate` names remain deprecated forwarding aliases. They emit one warning per name in development and stay silent in production.
|
||||
|
||||
## Form UI API Changes in This Refactor
|
||||
|
||||
### Added APIs
|
||||
|
||||
| API | Type/Location | Description |
|
||||
| --- | --- | --- |
|
||||
| `dependencies.resolve(context)` | `FormItemDependenciesResolve` | Evaluates one complete dynamic patch from declared `triggerFields` and commits it atomically. Context contains readonly `values`, `actions`, `controller`, and row-aware `schema`. |
|
||||
| `useValues()` | `FormContextApi` | Subscribes to all form values. Use only when full-form reactivity is required. |
|
||||
| `useFieldValue(fieldName)` | `FormContextApi` | Subscribes to one field value without reacting to unrelated fields. |
|
||||
| `useFieldValues(fieldNames)` | `FormContextApi` | Subscribes to a declared group of field values. |
|
||||
| `useFieldError(fieldName)` | `FormContextApi` | Subscribes to one field error without consuming the full error object. |
|
||||
| `getRawValues()` | `FormApi` | Returns an independent form-value snapshot before codec or legacy formatting. |
|
||||
| `formatValues(rawValues)` | `FormApi` | Runs the unified formatting pipeline on a supplied raw snapshot. |
|
||||
| `getValueSnapshot()` | `FormApi` | Returns `{ rawValues, values }`, where `values` is `TSubmitValues`. |
|
||||
| `asyncDebounceMs` | `FormFieldOptions` | Configures TanStack Field async validation debounce. |
|
||||
| `changeEventFallback` | `FormCommonConfig` / adapter config | Enables fallback for legacy components that emit `change` without `update:*`; defaults to `false`. |
|
||||
|
||||
`dependencies.resolve` may return `if`, `show`, `disabled`, `required`, `rules`, `componentProps`, `help`, and `renderComponentContent`. Omitting `rules` keeps the static rule; returning `rules: null` disables it.
|
||||
|
||||
### Changed APIs
|
||||
|
||||
| API | Before | After |
|
||||
| --- | --- | --- |
|
||||
| Submit callback | `handleSubmit(values)` | `handleSubmit(values, rawValues)`; the first argument is formatted and the second is the matching readonly raw snapshot. Existing single-argument functions remain valid. |
|
||||
| Values change callback | `handleValuesChange(values, fieldsChanged)` | `handleValuesChange(rawValues, fieldsChanged, getFormattedValues)`; formatting is lazy and incurs no clone/transform cost unless requested. |
|
||||
| Field validation triggers | Four `validateOn*` booleans | `validateOn?: readonly ('blur' \| 'change')[]`; submit always validates. |
|
||||
| Change-event compatibility | `disabledOnChangeListener: false` enabled fallback | `changeEventFallback: true` enables fallback with positive semantics. |
|
||||
| Top-level render callbacks | `componentProps(values, actions, ctx)`, `help(values, actions, ctx)`, `renderComponentContent(values, actions, ctx)` | Receive only lightweight `FormSchemaContext`; value-dependent behavior moves to `dependencies.resolve`. |
|
||||
| `validateAndSubmit()` | Repeated low-level validation/scroll handling and could validate again during submit | Delegates to canonical `validate()` and shared submission logic; invalid forms do not submit. |
|
||||
| `getValues()` | Implicitly returned transformed values | Returns codec-encoded `TSubmitValues`; without a codec it preserves legacy formatting. |
|
||||
|
||||
### Removed APIs
|
||||
|
||||
| Removed API | Replacement |
|
||||
| --- | --- |
|
||||
| `FormValidationOptions` | `validate()` and `validateField(fieldName)` no longer accept options. |
|
||||
| `force` / `silent` / `validated-only` validation modes | Removed because these vee modes have no TanStack runtime semantics. |
|
||||
| `validateOnBlur` / `validateOnChange` / `validateOnInput` / `validateOnModelUpdate` | Use `formFieldProps.validateOn`; input and model updates are represented by `change`. |
|
||||
| `disabledOnChangeListener` | Use positive `changeEventFallback`. |
|
||||
| `disabledOnInputListener` | Input listeners are no longer bound automatically; provide `componentProps.onInput` explicitly when required. |
|
||||
| `values/actions` parameters from top-level schema render functions | Use `FormSchemaContext`; move value-dependent behavior to `dependencies.resolve`. |
|
||||
|
||||
### Deprecated but Supported
|
||||
|
||||
- `dependencies.if/show/disabled/required/rules/componentProps/trigger` remain compatible for this release, but every callback is marked `@deprecated` and emits one development warning. If both syntaxes bypass the type union, `resolve` wins.
|
||||
- `resetForm`, `submitForm`, `resetValidate`, and `validateAndSubmitForm` continue forwarding to canonical methods.
|
||||
- `FormActions` remains as a deprecated alias of `FormContextApi`.
|
||||
- `setupVbenForm({ defineRules })` remains supported; `rules` wins for duplicate names.
|
||||
- The re-exported `z`, `componentField` slots, and `emptyStateValue` remain unchanged.
|
||||
|
||||
### Internal Behavior Changes
|
||||
|
||||
- Field components use fine-grained value/error selectors; full error aggregation is no longer on the normal input path.
|
||||
- Async validators discard stale Promises through a Vben generation without reading private TanStack AbortController or meta fields.
|
||||
- New and legacy dependencies share one atomic executor, so stale async results cannot overwrite newer state.
|
||||
- New code uses one form-level codec to encode the complete object atomically; legacy array-to-string, range mapping, and schema `valueFormat` remain compatible but deprecated.
|
||||
|
||||
## Typed Values and Slots
|
||||
|
||||
Application adapters keep the UI component mapping fixed and expose the business value shape as the only generic:
|
||||
|
||||
```ts
|
||||
interface AccountFormValues {
|
||||
email: string;
|
||||
nickname: string;
|
||||
}
|
||||
|
||||
const [Form, formApi] = useVbenForm<AccountFormValues>({
|
||||
handleSubmit(values) {
|
||||
return addAccount(values);
|
||||
},
|
||||
schema: [
|
||||
{ component: 'Input', fieldName: 'email' },
|
||||
{ component: 'Input', fieldName: 'nickname' },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
`TValues` flows through `VbenFormProps`, `FormSchema`, `FormApi`, `FormContextApi`, value APIs, submit/change callbacks, selectors, and dynamic schema callbacks. The returned `Form` component also exposes typed slots: known field slots use the matching value type for `field.state.value` and `componentField.modelValue`, while all field/default/action slots receive the complete `values` and matching `formApi`. Legacy forms without `TValues` retain arbitrary slot names and broad props.
|
||||
|
||||
## New and Legacy Rule Registration
|
||||
|
||||
Use `rules` in new code:
|
||||
|
||||
```ts
|
||||
setupVbenForm({
|
||||
rules: {
|
||||
required(value, _params, context) {
|
||||
const isEmpty =
|
||||
value === undefined ||
|
||||
value === null ||
|
||||
value === '' ||
|
||||
(Array.isArray(value) && value.length === 0);
|
||||
return isEmpty ? `${context.label} is required` : true;
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
The legacy `defineRules` option forwards to the same registry:
|
||||
|
||||
```ts
|
||||
setupVbenForm({
|
||||
defineRules: {
|
||||
required: legacyRequiredRule,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Legacy runtime usage emits one warning per deprecation key in development and no warnings in production. If both options define the same rule, `rules` wins. The `FormActions` type remains as a deprecated alias of `FormContextApi`; editors report the type deprecation because type-only usage cannot emit runtime warnings.
|
||||
|
||||
## Running the Codemod
|
||||
|
||||
Run the pinned tool against each affected tsconfig from a clean Git worktree:
|
||||
|
||||
```bash
|
||||
npx --yes zod-v3-to-v4@1.21.3 path/to/tsconfig.json
|
||||
```
|
||||
|
||||
The tool edits `.ts`, `.tsx`, and `.vue` files in place and has no dry-run mode. Always review `git diff` afterward.
|
||||
|
||||
The codemod primarily recognizes direct `zod` imports. Schemas that obtain `z` through `@vben/common-ui` or an application adapter need manual review, especially constructor errors, string formats, and dynamic refinement messages.
|
||||
|
||||
## Zod 4 Changes
|
||||
|
||||
### Unified Error Parameters
|
||||
|
||||
Replace `required_error` and `invalid_type_error` with `error`:
|
||||
|
||||
```ts
|
||||
const count = z.number({
|
||||
error: (issue) =>
|
||||
issue.input === undefined ? 'Count is required' : 'Count must be a number',
|
||||
});
|
||||
```
|
||||
|
||||
Use an `error(issue)` callback for dynamic refinement messages instead of passing a function that returns params as the second argument to `.refine()`.
|
||||
|
||||
### String Formats and Errors
|
||||
|
||||
Prefer top-level format schemas:
|
||||
|
||||
```ts
|
||||
z.email('Invalid email');
|
||||
z.url('Invalid URL');
|
||||
z.uuid('Invalid UUID');
|
||||
```
|
||||
|
||||
Read validation details from `ZodError.issues`; the old `.errors` property is removed.
|
||||
|
||||
### Defaults and Optionality
|
||||
|
||||
Zod 4 defaults may return immediately when the input is `undefined`. Review `.default().optional()` using actual parse behavior instead of internal type names.
|
||||
|
||||
Vben initial values use this precedence:
|
||||
|
||||
1. explicit schema `defaultValue`
|
||||
2. Zod `.default()`
|
||||
3. Zod 4-compatible `zod-defaults`
|
||||
4. component empty-state conventions
|
||||
|
||||
Required markers are derived from whether the schema accepts `undefined`.
|
||||
|
||||
### Wrappers, Refine, Transform, and Coerce
|
||||
|
||||
Do not read `_def`, `_zod.def`, or `typeName`. Use public `.unwrap()` APIs and public pipe inputs. Delegate intersection defaults to the Zod 4-compatible `zod-defaults` package.
|
||||
|
||||
Standard Schema validation does not write transform/coerce output back into TanStack Form state. Use the form-level codec for submission payload conversion, or explicitly call `parseAsync` inside the codec `encode` boundary when transformed schema output is required.
|
||||
|
||||
Also review these changes:
|
||||
|
||||
- `z.record()` should specify key and value schemas
|
||||
- `z.enum()` replaces former `nativeEnum` use cases
|
||||
- number integer, Infinity, and finite behavior
|
||||
- object strictness, merge, and unknown keys
|
||||
- intersection merge conflicts
|
||||
- coerce input types defaulting to `unknown`
|
||||
- removal of Zod 3 types such as `ZodEffects`, `ZodTypeAny`, and `AnyZodObject`
|
||||
|
||||
## Form Engine Behavior
|
||||
|
||||
`formFieldProps.validateOn` accepts `blur` and `change`, with both enabled by default; submit always validates fields. `asyncDebounceMs` configures TanStack Field async debounce. The four vee-style `validateOn*` booleans and `force/silent/validated-only` modes have been removed.
|
||||
|
||||
The shadcn form primitives now use a Vben-owned field context. Labels, controls, descriptions, and messages continue to provide ids, `aria-invalid`, `aria-describedby`, touched, dirty, valid, and error states.
|
||||
|
||||
`clearValidation(fieldNames?)` advances Vben's validator generation and clears public error state without relying on a private TanStack AbortController. A Promise that finishes later is discarded as stale. Omitting `fieldNames` covers every registered field and every field with an existing error.
|
||||
|
||||
`dependencies.resolve(context)` is the recommended API: it evaluates once and atomically commits one dynamic-state patch, while stale async results are discarded as a unit. Legacy `if/show/disabled/required/rules/componentProps/trigger` callbacks remain supported through the same normalized executor, but are marked `@deprecated` and emit one development warning. Both APIs react only to declared `triggerFields`.
|
||||
|
||||
`handleValuesChange(rawValues, fieldsChanged, getFormattedValues)` receives readonly `TFormValues` and runs codec or legacy formatting only when its third argument is called. `getRawValues()` returns form values and `getValues()` returns `TSubmitValues`; use `getValueSnapshot()` when both are required. `handleSubmit(values, rawValues)` receives both forms at submission. Legacy array-to-string, range mapping, and schema `valueFormat` remain compatible but deprecated. Array fields keep using TanStack push/remove operations and stable row identity.
|
||||
|
||||
## Test and Acceptance Matrix
|
||||
|
||||
Required coverage includes:
|
||||
|
||||
- Zod defaults, optional, nullable, intersection, pipe, transform, coerce, and errors
|
||||
- runtime values, selectors, reset, manual errors, validation, and async validation
|
||||
- field binding, blur/change triggers, error messages, ARIA, dependencies, and arrays
|
||||
- new/legacy API equivalence, warning deduplication, production silence, and type aliases
|
||||
- complete `useVbenForm` lifecycle, submission, `handleValuesChange`, submit-on-change, and async race handling
|
||||
|
||||
Acceptance requires zero TypeScript errors, zero build errors, all tests passing, no unhandled browser errors, modified-file formatting and lint passing, and no source dependency on vee or Zod private structures.
|
||||
|
||||
## References
|
||||
|
||||
- [Zod 4 release notes](https://zod.dev/v4)
|
||||
- [Zod migration guide](https://zod.dev/v4/changelog)
|
||||
- [TanStack Form Vue overview](https://tanstack.com/form/latest/docs/framework/vue/overview)
|
||||
- [TanStack Form validation](https://tanstack.com/form/latest/docs/framework/vue/guides/validation)
|
||||
274
docs/src/guide/in-depth/zod-v4-form-migration.md
Normal file
274
docs/src/guide/in-depth/zod-v4-form-migration.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Zod 4 与 TanStack Form 迁移指南
|
||||
|
||||
本次迁移将表单校验 schema 从 Zod 3 升级到 Zod 4，并将内部表单引擎从 vee-validate 替换为 TanStack Form。迁移目标是保持 Vben 业务 API 稳定，同时移除业务代码对具体表单引擎的耦合。
|
||||
|
||||
## 依赖变化
|
||||
|
||||
| 类型 | 迁移前 | 迁移后 |
|
||||
| --- | --- | --- |
|
||||
| Schema | `zod@^3.25.76` | `zod@^4.4.3` |
|
||||
| 默认值 | `zod-defaults@0.1.3` | `zod-defaults@^0.2.3` |
|
||||
| 表单引擎 | `vee-validate@^4.15.1` | `@tanstack/vue-form@^1.33.2` |
|
||||
| Zod 适配器 | `@vee-validate/zod@^4.15.1` | 不再需要，TanStack Form 支持 Standard Schema |
|
||||
|
||||
迁移后，源码、package manifest 和锁文件中都不应再依赖 `vee-validate` 或 `@vee-validate/zod`。
|
||||
|
||||
## 上层兼容范围
|
||||
|
||||
以下 Vben API 保持兼容：
|
||||
|
||||
- `useVbenForm(options)` 仍返回 `[Form, formApi]`
|
||||
- `FormApi` 的值、校验、提交、重置、schema 更新和组件引用能力
|
||||
- `FormSchema` 的 `fieldName`、`component`、`componentProps`、`rules`、`dependencies`、`defaultValue`、已弃用的 `valueFormat` 和数组字段结构
|
||||
- `dependencies.triggerFields` 与回调参数
|
||||
- 组件适配器和 `z` 重导出路径
|
||||
- 自定义 slot 中原有的 `componentField` 绑定对象
|
||||
|
||||
`formApi.form` 现在是库无关的 `FormContextApi`。它提供 values、errors、meta、字段读写、验证、提交、重置和数组操作，但不再暴露 vee `FormContext` 或原始 TanStack 实例。
|
||||
|
||||
新代码使用 `reset`、`submit`、`validateAndSubmit` 和 `clearValidation`。旧的 `resetForm`、`submitForm`、`validateAndSubmitForm` 和 `resetValidate` 仍会委托给新实现，并通过 `@deprecated` 与开发环境一次性 warning 提示迁移；生产环境不输出 warning。
|
||||
|
||||
## 本轮 Form UI API 变更
|
||||
|
||||
### 新增 API
|
||||
|
||||
| API | 类型/位置 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `dependencies.resolve(context)` | `FormItemDependenciesResolve` | 根据声明的 `triggerFields` 一次计算完整动态 patch，并原子更新字段状态。context 包含只读 `values`、`actions`、`controller` 和数组行感知的 `schema`。 |
|
||||
| `useValues()` | `FormContextApi` | 订阅完整表单值。仅在确实需要整表响应式值时使用。 |
|
||||
| `useFieldValue(fieldName)` | `FormContextApi` | 订阅单字段值，避免无关字段变化触发组件更新。 |
|
||||
| `useFieldValues(fieldNames)` | `FormContextApi` | 订阅一组字段值，主要用于声明式依赖计算。 |
|
||||
| `useFieldError(fieldName)` | `FormContextApi` | 订阅单字段错误，不再依赖全量错误对象。 |
|
||||
| `getRawValues()` | `FormApi` | 返回未执行 codec 或旧格式化管道的独立表单值快照。 |
|
||||
| `formatValues(rawValues)` | `FormApi` | 对指定原始值执行统一格式化流水线。 |
|
||||
| `getValueSnapshot()` | `FormApi` | 同时返回 `{ rawValues, values }`，其中 `values` 为 `TSubmitValues`。 |
|
||||
| `asyncDebounceMs` | `FormFieldOptions` | 设置 TanStack Field 异步校验防抖时间。 |
|
||||
| `changeEventFallback` | `FormCommonConfig` / adapter config | 为只发送 `change`、不发送 `update:*` 的旧组件启用事件回退，默认 `false`。 |
|
||||
|
||||
`dependencies.resolve` 可以返回 `if`、`show`、`disabled`、`required`、`rules`、`componentProps`、`help` 和 `renderComponentContent`。未返回 `rules` 时继续使用静态规则；显式返回 `rules: null` 时关闭静态规则。
|
||||
|
||||
### 变更的 API
|
||||
|
||||
| API | 迁移前 | 迁移后 |
|
||||
| --- | --- | --- |
|
||||
| 提交回调 | `handleSubmit(values)` | `handleSubmit(values, rawValues)`；首参为格式化值，次参为同一次提交对应的只读原始快照。旧单参数函数仍可直接使用。 |
|
||||
| 值变化回调 | `handleValuesChange(values, fieldsChanged)` | `handleValuesChange(rawValues, fieldsChanged, getFormattedValues)`；第三个参数为惰性格式化函数，不调用时不产生深拷贝和转换开销。 |
|
||||
| 字段校验触发 | 四个 `validateOn*` 布尔项 | `validateOn?: readonly ('blur' \| 'change')[]`；submit 始终校验。 |
|
||||
| change 事件兼容 | `disabledOnChangeListener: false` 表示启用 | `changeEventFallback: true` 表示启用，改为正向语义。 |
|
||||
| 顶层动态渲染回调 | `componentProps(values, actions, ctx)`、`help(values, actions, ctx)`、`renderComponentContent(values, actions, ctx)` | 仅接收轻量 `FormSchemaContext`。依赖表单值的动态逻辑迁移到 `dependencies.resolve`。 |
|
||||
| `validateAndSubmit()` | 自行调用底层校验并重复实现错误滚动，提交阶段可能再次校验 | 委托统一 `validate()` 与共享提交逻辑，无效时不提交，错误滚动只有一个实现。 |
|
||||
| `getValues()` | 隐式完成所有字段转换 | 返回 codec 编码后的 `TSubmitValues`；无 codec 时保持旧格式化行为。 |
|
||||
|
||||
### 删除的 API
|
||||
|
||||
| 已删除 API | 替代方式 |
|
||||
| --- | --- |
|
||||
| `FormValidationOptions` | `validate()` 与 `validateField(fieldName)` 不再接收 options。 |
|
||||
| `force` / `silent` / `validated-only` validation mode | 这些 vee mode 在 TanStack runtime 中没有对应语义，直接删除。 |
|
||||
| `validateOnBlur` / `validateOnChange` / `validateOnInput` / `validateOnModelUpdate` | 使用 `formFieldProps.validateOn`；input 与 model update 统一归入 `change`。 |
|
||||
| `disabledOnChangeListener` | 使用正向语义的 `changeEventFallback`。 |
|
||||
| `disabledOnInputListener` | 不再自动绑定 input listener；确需自定义 input 处理时在 `componentProps.onInput` 中显式提供。 |
|
||||
| 顶层 schema 渲染函数中的 `values/actions` 参数 | 使用 `FormSchemaContext`；值相关联动使用 `dependencies.resolve`。 |
|
||||
|
||||
### 已弃用但保留兼容
|
||||
|
||||
- `dependencies.if/show/disabled/required/rules/componentProps/trigger` 本轮仍完整兼容，但均已标记 `@deprecated`。开发环境首次使用时警告一次；新旧语法绕过类型同时存在时以 `resolve` 为准。
|
||||
- `resetForm`、`submitForm`、`resetValidate` 和 `validateAndSubmitForm` 继续转发到新方法。
|
||||
- `FormActions` 继续作为 `FormContextApi` 的弃用类型别名。
|
||||
- `setupVbenForm({ defineRules })` 继续兼容；与 `rules` 同名时新 API 优先。
|
||||
- `z` 重导出、`componentField` slot 和 `emptyStateValue` 保持不变。
|
||||
|
||||
### 非 API 行为调整
|
||||
|
||||
- 字段组件改用细粒度 value/error selector；全量错误聚合退出普通输入热路径。
|
||||
- async validator 通过 Vben generation 丢弃过期 Promise，不读取 TanStack 私有 AbortController 或 meta 字段。
|
||||
- dependencies 新旧语法共用一个原子执行器，异步旧结果不会覆盖新状态。
|
||||
- 新代码使用表单级 codec 原子编码完整对象；旧 array-to-string、时间范围映射和 schema `valueFormat` 继续兼容但已弃用。
|
||||
|
||||
## 值类型与插槽类型
|
||||
|
||||
应用 adapter 保留 UI 组件类型，只把业务值类型作为泛型暴露：
|
||||
|
||||
```ts
|
||||
interface AccountFormValues {
|
||||
email: string;
|
||||
nickname: string;
|
||||
}
|
||||
|
||||
const [Form, formApi] = useVbenForm<AccountFormValues>({
|
||||
handleSubmit(values) {
|
||||
return addAccount(values);
|
||||
},
|
||||
schema: [
|
||||
{ component: 'Input', fieldName: 'email' },
|
||||
{ component: 'Input', fieldName: 'nickname' },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
`TValues` 会传递给 `VbenFormProps`、`FormSchema`、`FormApi`、`FormContextApi`、值读写 API、提交/变化回调、selector 和 schema 动态回调。返回的 `Form` 组件同时提供 typed slots：已知字段插槽的 `field.state.value` 与 `componentField.modelValue` 使用对应字段类型，并额外提供完整 `values` 与同型 `formApi`；默认和操作插槽也提供 `values/formApi`。未声明 `TValues` 的旧表单仍允许任意字段插槽并回退为宽泛类型。
|
||||
|
||||
## 新旧规则注册 API
|
||||
|
||||
新代码使用 `rules`：
|
||||
|
||||
```ts
|
||||
setupVbenForm({
|
||||
rules: {
|
||||
required(value, _params, context) {
|
||||
const isEmpty =
|
||||
value === undefined ||
|
||||
value === null ||
|
||||
value === '' ||
|
||||
(Array.isArray(value) && value.length === 0);
|
||||
return isEmpty ? `${context.label} is required` : true;
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
旧的 `defineRules` 仍会转发到同一个规则注册表：
|
||||
|
||||
```ts
|
||||
setupVbenForm({
|
||||
defineRules: {
|
||||
required: legacyRequiredRule,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
使用旧入口时，开发环境针对该弃用项只输出一次警告；生产环境不输出。若同时提供 `rules` 与 `defineRules` 的同名规则，`rules` 优先。`FormActions` 类型保留为 `FormContextApi` 的弃用别名，类型别名本身无法触发运行时警告，编辑器会通过 `@deprecated` 提示迁移。
|
||||
|
||||
## 使用迁移工具
|
||||
|
||||
建议在干净的 Git 工作树中按项目 tsconfig 执行固定版本工具：
|
||||
|
||||
```bash
|
||||
npx --yes zod-v3-to-v4@1.21.3 path/to/tsconfig.json
|
||||
```
|
||||
|
||||
工具会原地修改 `.ts`、`.tsx` 和 `.vue` 文件，没有 dry-run 模式。执行后必须检查 `git diff`。
|
||||
|
||||
工具只能可靠识别直接从 `zod` 导入的调用。通过 `@vben/common-ui` 或应用 adapter 间接取得 `z` 的 schema 需要人工审计，尤其是构造器错误参数、字符串格式和动态 refine 参数。
|
||||
|
||||
## Zod 4 代码变更
|
||||
|
||||
### 错误参数
|
||||
|
||||
构造器中的 `required_error` 和 `invalid_type_error` 合并为 `error`：
|
||||
|
||||
```ts
|
||||
const count = z.number({
|
||||
error: (issue) =>
|
||||
issue.input === undefined ? 'Count is required' : 'Count must be a number',
|
||||
});
|
||||
```
|
||||
|
||||
refinement 继续支持字符串或对象参数。需要根据输入动态生成消息时，使用 `error(issue)`，不再传入返回 params 的第二个函数。
|
||||
|
||||
### 字符串格式
|
||||
|
||||
优先使用顶层格式 API：
|
||||
|
||||
```ts
|
||||
z.email('Invalid email');
|
||||
z.url('Invalid URL');
|
||||
z.uuid('Invalid UUID');
|
||||
```
|
||||
|
||||
旧的 `z.string().email()` 等形式不应继续新增。
|
||||
|
||||
### 错误列表
|
||||
|
||||
ZodError 使用 `issues`：
|
||||
|
||||
```ts
|
||||
const result = schema.safeParse(value);
|
||||
if (!result.success) {
|
||||
console.log(result.error.issues);
|
||||
}
|
||||
```
|
||||
|
||||
不要读取已移除的 `.errors`。
|
||||
|
||||
### 默认值与 optional
|
||||
|
||||
Zod 4 的 default 在输入为 `undefined` 时可以直接返回默认值。`.default().optional()` 的结果必须按实际 parse 语义复核，而不是通过类型名称猜测。
|
||||
|
||||
Vben 表单按以下优先级生成初值：
|
||||
|
||||
1. schema 中显式 `defaultValue`
|
||||
2. Zod schema 中的 `.default()`
|
||||
3. `zod-defaults` 生成的对象、intersection 和基础空值
|
||||
4. Vben 组件约定的空字符串、空数组或空状态值
|
||||
|
||||
必填标记以 schema 是否接受 `undefined` 为准。
|
||||
|
||||
### 包装器、refine 与 transform
|
||||
|
||||
不要读取 `_def`、`_zod.def` 或 `typeName`。公共包装器使用 `.unwrap()`；Zod 4 的 transform/pipe 使用公开的输入 schema。intersection 的默认值交给支持 Zod 4 的 `zod-defaults` 处理。
|
||||
|
||||
TanStack Form 使用 Standard Schema 校验时不会自动把 transform/coerce 的输出写回当前表单 state。提交 payload 需要转换时，使用表单级 codec；如果必须提交 schema transform 后的结果，应在 codec 的 `encode` 边界显式调用 `parseAsync`。
|
||||
|
||||
### 其他需要复核的 API
|
||||
|
||||
- `z.record()` 需要明确 key schema 与 value schema
|
||||
- `z.enum()` 已覆盖原 `nativeEnum` 用法
|
||||
- number 的 `int`、Infinity 和 finite 约束需按 Zod 4 语义复核
|
||||
- object 的 strict、merge、unknown keys 行为需要通过测试确认
|
||||
- intersection 合并冲突现在可能直接抛出错误
|
||||
- coerce schema 的 input 类型默认为 `unknown`
|
||||
- `ZodEffects`、`ZodTypeAny`、`AnyZodObject` 等 Zod 3 类型不应继续使用
|
||||
|
||||
## 表单引擎行为
|
||||
|
||||
### 验证触发
|
||||
|
||||
`formFieldProps.validateOn` 接收 `blur`、`change` 数组，默认两者都启用；所有字段仍会在 submit 时验证。`asyncDebounceMs` 映射到 TanStack Field 的异步防抖配置。原 vee 风格的四个 `validateOn*` 布尔项和 `force/silent/validated-only` mode 已删除。
|
||||
|
||||
### 错误与可访问性
|
||||
|
||||
shadcn form primitive 使用 Vben 自有字段上下文，不再注入 vee 的 `FieldContextKey`。`FormLabel`、`FormControl`、`FormDescription` 和 `FormMessage` 继续维护：
|
||||
|
||||
- `for` 与 control id
|
||||
- `aria-invalid`
|
||||
- `aria-describedby`
|
||||
- touched、dirty、valid 和错误消息
|
||||
|
||||
`clearValidation(fieldNames?)` 会递增 Vben validator generation 并清空公开错误状态，不依赖 TanStack 私有 AbortController。异步 Promise 即使随后完成也会因代次过期而被丢弃；省略字段参数时会处理全部已注册或已有错误的字段。
|
||||
|
||||
### 依赖与数组
|
||||
|
||||
`dependencies.resolve(context)` 是推荐语法：一次求值并原子提交完整动态 patch，过期异步结果整体丢弃。旧的 `if/show/disabled/required/rules/componentProps/trigger` 语法仍兼容，但已标记为 `@deprecated` 并在开发环境首次使用时提示迁移；内部仍归一到同一个执行器。两种语法都只根据 `triggerFields` 重算，无关字段变化不会执行回调。
|
||||
|
||||
`handleValuesChange(rawValues, fieldsChanged, getFormattedValues)` 接收只读 `TFormValues`，第三个参数仅在调用时执行 codec 或旧格式化管道。`getRawValues()` 返回表单值，`getValues()` 返回 `TSubmitValues`；需要同时比较时使用 `getValueSnapshot()`。提交回调通过 `handleSubmit(values, rawValues)` 同时取得两种结构。旧 array-to-string、时间范围映射和 schema `valueFormat` 继续兼容但已弃用。数组字段继续使用 TanStack push/remove 操作和稳定行身份。
|
||||
|
||||
## 测试与验收
|
||||
|
||||
迁移至少需要覆盖以下层级：
|
||||
|
||||
- Zod 4 helper：default、optional、nullable、intersection、pipe、transform、coerce 与错误参数
|
||||
- runtime：值读写、selector、reset、字段错误、validate 和异步校验
|
||||
- 组件：输入绑定、blur/change 触发、错误消息、ARIA、dependencies 和数组增删
|
||||
- 兼容：`rules`/`defineRules` 结果一致、开发 warning 去重、生产静默、类型别名
|
||||
- 集成：`useVbenForm` 生命周期、提交、`handleValuesChange`、submit-on-change 和 async race
|
||||
|
||||
验收标准：
|
||||
|
||||
1. 受影响 package、应用、playground 和 docs 无 TypeScript 错误
|
||||
2. form-ui 与所有应用构建成功
|
||||
3. 单元、组件和集成测试全部通过
|
||||
4. 浏览器 smoke 流程无 `pageerror`、`console.error` 或未处理 Promise
|
||||
5. 修改文件通过 oxfmt 与 ESLint
|
||||
6. 静态搜索中不再出现 vee 依赖、Zod 私有结构或 Zod 3 错误参数
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Zod 4 release notes](https://zod.dev/v4)
|
||||
- [Zod migration guide](https://zod.dev/v4/changelog)
|
||||
- [TanStack Form Vue overview](https://tanstack.com/form/latest/docs/framework/vue/overview)
|
||||
- [TanStack Form validation](https://tanstack.com/form/latest/docs/framework/vue/guides/validation)
|
||||
Reference in New Issue
Block a user