chore: release 5.5.2

* feat: header menu align support

* fix: typo

.github/CODEOWNERS

@@ -1,14 +1,14 @@
 # default onwer
-* anncwb@126.com vince292007@gmail.com
+* anncwb@126.com vince292007@gmail.com netfan@foxmail.com
 
 # vben core onwer
-/.github/ anncwb@126.com vince292007@gmail.com
-/.vscode/ anncwb@126.com vince292007@gmail.com
-/packages/ anncwb@126.com vince292007@gmail.com
-/packages/@core/ anncwb@126.com vince292007@gmail.com
-/internal/ anncwb@126.com vince292007@gmail.com
-/scripts/ anncwb@126.com vince292007@gmail.com
+/.github/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com
+/.vscode/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com
+/packages/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com
+/packages/@core/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com
+/internal/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com
+/scripts/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com
 
 # vben team onwer
-apps/ anncwb@126.com vince292007@gmail.com @vbenjs/team-v5
-docs/ anncwb@126.com vince292007@gmail.com @vbenjs/team-v5
+apps/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com @vbenjs/team-v5
+docs/ anncwb@126.com vince292007@gmail.com netfan@foxmail.com @vbenjs/team-v5

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -62,7 +62,7 @@ body:
       description: Before submitting the issue, please make sure you do the following
       # description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com).
       options:
-        - label: Read the [docs](https://anncwb.github.io/vue-vben-admin-doc/)
+        - label: Read the [docs](https://doc.vben.pro/)
           required: true
         - label: Ensure the code is up to date. (Some issues have been fixed in the latest version)
           required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -62,7 +62,7 @@ body:
       label: Validations
       description: Before submitting the issue, please make sure you do the following
       options:
-        - label: Read the [docs](https://anncwb.github.io/vue-vben-admin-doc/)
+        - label: Read the [docs](https://doc.vben.pro/)
           required: true
         - label: Ensure the code is up to date. (Some issues have been fixed in the latest version)
           required: true

.vscode/launch.json

@@ -9,7 +9,7 @@
       "url": "http://localhost:5555",
       "env": { "NODE_ENV": "development" },
       "sourceMaps": true,
-      "webRoot": "${workspaceFolder}"
+      "webRoot": "${workspaceFolder}/playground"
     },
     {
       "type": "chrome",
@@ -18,7 +18,7 @@
       "url": "http://localhost:5666",
       "env": { "NODE_ENV": "development" },
       "sourceMaps": true,
-      "webRoot": "${workspaceFolder}"
+      "webRoot": "${workspaceFolder}/apps/web-antd"
     },
     {
       "type": "chrome",
@@ -27,7 +27,7 @@
       "url": "http://localhost:5777",
       "env": { "NODE_ENV": "development" },
       "sourceMaps": true,
-      "webRoot": "${workspaceFolder}"
+      "webRoot": "${workspaceFolder}/apps/web-ele"
     },
     {
       "type": "chrome",
@@ -36,7 +36,7 @@
       "url": "http://localhost:5888",
       "env": { "NODE_ENV": "development" },
       "sourceMaps": true,
-      "webRoot": "${workspaceFolder}"
+      "webRoot": "${workspaceFolder}/apps/web-naive"
     }
   ]
 }

.vscode/settings.json

@@ -160,6 +160,7 @@
   "stylelint.enable": true,
   "stylelint.packageManager": "pnpm",
   "stylelint.validate": ["css", "less", "postcss", "scss", "vue"],
+  "stylelint.customSyntax": "postcss-html",
   "stylelint.snippet": ["css", "less", "postcss", "scss", "vue"],
 
   "typescript.inlayHints.enumMemberValues.enabled": true,
@@ -221,5 +222,6 @@
   "commentTranslate.hover.enabled": false,
   "commentTranslate.multiLineMerge": true,
   "vue.server.hybridMode": true,
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "oxc.enable": false
 }

apps/backend-mock/api/table/list.ts

@@ -43,6 +43,31 @@ export default eventHandler(async (event) => {
 
   await sleep(600);
 
-  const { page, pageSize } = getQuery(event);
-  return usePageResponseSuccess(page as string, pageSize as string, mockData);
+  const { page, pageSize, sortBy, sortOrder } = getQuery(event);
+  const listData = structuredClone(mockData);
+  if (sortBy && Reflect.has(listData[0], sortBy as string)) {
+    listData.sort((a, b) => {
+      if (sortOrder === 'asc') {
+        if (sortBy === 'price') {
+          return (
+            Number.parseFloat(a[sortBy as string]) -
+            Number.parseFloat(b[sortBy as string])
+          );
+        } else {
+          return a[sortBy as string] > b[sortBy as string] ? 1 : -1;
+        }
+      } else {
+        if (sortBy === 'price') {
+          return (
+            Number.parseFloat(b[sortBy as string]) -
+            Number.parseFloat(a[sortBy as string])
+          );
+        } else {
+          return a[sortBy as string] < b[sortBy as string] ? 1 : -1;
+        }
+      }
+    });
+  }
+
+  return usePageResponseSuccess(page as string, pageSize as string, listData);
 });

apps/backend-mock/utils/mock-data.ts

@@ -4,6 +4,7 @@ export interface UserInfo {
   realName: string;
   roles: string[];
   username: string;
+  homePath?: string;
 }
 
 export const MOCK_USERS: UserInfo[] = [
@@ -20,6 +21,7 @@ export const MOCK_USERS: UserInfo[] = [
     realName: 'Admin',
     roles: ['admin'],
     username: 'admin',
+    homePath: '/workspace',
   },
   {
     id: 2,
@@ -27,6 +29,7 @@ export const MOCK_USERS: UserInfo[] = [
     realName: 'Jack',
     roles: ['user'],
     username: 'jack',
+    homePath: '/analytics',
   },
 ];
 

apps/web-antd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/web-antd",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "homepage": "https://vben.pro",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",
   "repository": {

apps/web-antd/src/adapter/component/index.ts

@@ -8,7 +8,7 @@ import type { BaseFormComponentType } from '@vben/common-ui';
 import type { Component, SetupContext } from 'vue';
 import { h } from 'vue';
 
-import { globalShareState } from '@vben/common-ui';
+import { ApiComponent, globalShareState, IconPicker } from '@vben/common-ui';
 import { $t } from '@vben/locales';
 
 import {
@@ -48,12 +48,15 @@ const withDefaultPlaceholder = <T extends Component>(
 
 // 这里需要自行根据业务组件库进行适配，需要用到的组件都需要在这里类型说明
 export type ComponentType =
+  | 'ApiSelect'
+  | 'ApiTreeSelect'
   | 'AutoComplete'
   | 'Checkbox'
   | 'CheckboxGroup'
   | 'DatePicker'
   | 'DefaultButton'
   | 'Divider'
+  | 'IconPicker'
   | 'Input'
   | 'InputNumber'
   | 'InputPassword'
@@ -77,7 +80,38 @@ async function initComponentAdapter() {
     // 如果你的组件体积比较大，可以使用异步加载
     // Button: () =>
     // import('xxx').then((res) => res.Button),
-
+    ApiSelect: (props, { attrs, slots }) => {
+      return h(
+        ApiComponent,
+        {
+          placeholder: $t('ui.placeholder.select'),
+          ...props,
+          ...attrs,
+          component: Select,
+          loadingSlot: 'suffixIcon',
+          visibleEvent: 'onDropdownVisibleChange',
+          modelPropName: 'value',
+        },
+        slots,
+      );
+    },
+    ApiTreeSelect: (props, { attrs, slots }) => {
+      return h(
+        ApiComponent,
+        {
+          placeholder: $t('ui.placeholder.select'),
+          ...props,
+          ...attrs,
+          component: TreeSelect,
+          fieldNames: { label: 'label', value: 'value', children: 'children' },
+          loadingSlot: 'suffixIcon',
+          modelPropName: 'value',
+          optionsPropName: 'treeData',
+          visibleEvent: 'onVisibleChange',
+        },
+        slots,
+      );
+    },
     AutoComplete,
     Checkbox,
     CheckboxGroup,
@@ -87,6 +121,13 @@ async function initComponentAdapter() {
       return h(Button, { ...props, attrs, type: 'default' }, slots);
     },
     Divider,
+    IconPicker: (props, { attrs, slots }) => {
+      return h(
+        IconPicker,
+        { iconSlot: 'addonAfter', inputComponent: Input, ...props, ...attrs },
+        slots,
+      );
+    },
     Input: withDefaultPlaceholder(Input, 'input'),
     InputNumber: withDefaultPlaceholder(InputNumber, 'input'),
     InputPassword: withDefaultPlaceholder(InputPassword, 'input'),

apps/web-antd/src/preferences.ts

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

apps/web-antd/src/router/guard.ts

@@ -54,7 +54,9 @@ function setupAccessGuard(router: Router) {
     if (coreRouteNames.includes(to.name as string)) {
       if (to.path === LOGIN_PATH && accessStore.accessToken) {
         return decodeURIComponent(
-          (to.query?.redirect as string) || DEFAULT_HOME_PATH,
+          (to.query?.redirect as string) ||
+            userStore.userInfo?.homePath ||
+            DEFAULT_HOME_PATH,
         );
       }
       return true;
@@ -72,7 +74,10 @@ function setupAccessGuard(router: Router) {
         return {
           path: LOGIN_PATH,
           // 如不需要，直接删除 query
-          query: { redirect: encodeURIComponent(to.fullPath) },
+          query:
+            to.fullPath === DEFAULT_HOME_PATH
+              ? {}
+              : { redirect: encodeURIComponent(to.fullPath) },
           // 携带当前跳转的页面，登录后重新跳转该页面
           replace: true,
         };
@@ -102,7 +107,10 @@ function setupAccessGuard(router: Router) {
     accessStore.setAccessMenus(accessibleMenus);
     accessStore.setAccessRoutes(accessibleRoutes);
     accessStore.setIsAccessChecked(true);
-    const redirectPath = (from.query.redirect ?? to.fullPath) as string;
+    const redirectPath = (from.query.redirect ??
+      (to.path === DEFAULT_HOME_PATH
+        ? userInfo.homePath || DEFAULT_HOME_PATH
+        : to.fullPath)) as string;
 
     return {
       ...router.resolve(decodeURIComponent(redirectPath)),

apps/web-antd/src/router/routes/index.ts

@@ -17,12 +17,12 @@ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles);
 
 /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */
 // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles);
-/** 不需要权限的菜单列表（会显示在菜单中） */
 // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles);
 const staticRoutes: RouteRecordRaw[] = [];
 const externalRoutes: RouteRecordRaw[] = [];
 
-/** 路由列表，由基本路由+静态路由组成 */
+/** 路由列表，由基本路由、外部路由和404兜底路由组成
+ *  无需走权限验证（会一直显示在菜单中） */
 const routes: RouteRecordRaw[] = [
   ...coreRoutes,
   ...externalRoutes,
@@ -32,5 +32,6 @@ const routes: RouteRecordRaw[] = [
 /** 基本路由列表，这些路由不需要进入权限拦截 */
 const coreRouteNames = traverseTreeValues(coreRoutes, (route) => route.name);
 
+/** 有权限校验的路由列表，包含动态路由和静态路由 */
 const accessRoutes = [...dynamicRoutes, ...staticRoutes];
 export { accessRoutes, coreRouteNames, routes };

apps/web-antd/src/views/_core/authentication/code-login.vue

@@ -10,6 +10,7 @@ import { $t } from '@vben/locales';
 defineOptions({ name: 'CodeLogin' });
 
 const loading = ref(false);
+const CODE_LENGTH = 6;
 
 const formSchema = computed((): VbenFormSchema[] => {
   return [
@@ -30,6 +31,7 @@ const formSchema = computed((): VbenFormSchema[] => {
     {
       component: 'VbenPinInput',
       componentProps: {
+        codeLength: CODE_LENGTH,
         createText: (countdown: number) => {
           const text =
             countdown > 0
@@ -41,7 +43,9 @@ const formSchema = computed((): VbenFormSchema[] => {
       },
       fieldName: 'code',
       label: $t('authentication.code'),
-      rules: z.string().min(1, { message: $t('authentication.codeTip') }),
+      rules: z.string().length(CODE_LENGTH, {
+        message: $t('authentication.codeTip', [CODE_LENGTH]),
+      }),
     },
   ];
 });

apps/web-antd/src/views/dashboard/workspace/index.vue

@@ -7,6 +7,7 @@ import type {
 } from '@vben/common-ui';
 
 import { ref } from 'vue';
+import { useRouter } from 'vue-router';
 
 import {
   AnalysisChartCard,
@@ -18,11 +19,15 @@ import {
 } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { useUserStore } from '@vben/stores';
+import { openWindow } from '@vben/utils';
 
 import AnalyticsVisitsSource from '../analytics/analytics-visits-source.vue';
 
 const userStore = useUserStore();
 
+// 这是一个示例数据，实际项目中需要根据实际情况进行调整
+// url 也可以是内部路由，在 navTo 方法中识别处理，进行内部跳转
+// 例如：url: /dashboard/workspace
 const projectItems: WorkbenchProjectItem[] = [
   {
     color: '',
@@ -31,6 +36,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '开源组',
     icon: 'carbon:logo-github',
     title: 'Github',
+    url: 'https://github.com',
   },
   {
     color: '#3fb27f',
@@ -39,6 +45,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '算法组',
     icon: 'ion:logo-vue',
     title: 'Vue',
+    url: 'https://vuejs.org',
   },
   {
     color: '#e18525',
@@ -47,6 +54,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '上班摸鱼',
     icon: 'ion:logo-html5',
     title: 'Html5',
+    url: 'https://developer.mozilla.org/zh-CN/docs/Web/HTML',
   },
   {
     color: '#bf0c2c',
@@ -55,6 +63,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: 'UI',
     icon: 'ion:logo-angular',
     title: 'Angular',
+    url: 'https://angular.io',
   },
   {
     color: '#00d8ff',
@@ -63,6 +72,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '技术牛',
     icon: 'bx:bxl-react',
     title: 'React',
+    url: 'https://reactjs.org',
   },
   {
     color: '#EBD94E',
@@ -71,39 +81,47 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '架构组',
     icon: 'ion:logo-javascript',
     title: 'Js',
+    url: 'https://developer.mozilla.org/zh-CN/docs/Web/JavaScript',
   },
 ];
 
+// 同样，这里的 url 也可以使用以 http 开头的外部链接
 const quickNavItems: WorkbenchQuickNavItem[] = [
   {
     color: '#1fdaca',
     icon: 'ion:home-outline',
     title: '首页',
+    url: '/',
   },
   {
     color: '#bf0c2c',
     icon: 'ion:grid-outline',
     title: '仪表盘',
+    url: '/dashboard',
   },
   {
     color: '#e18525',
     icon: 'ion:layers-outline',
     title: '组件',
+    url: '/demos/features/icons',
   },
   {
     color: '#3fb27f',
     icon: 'ion:settings-outline',
     title: '系统管理',
+    url: '/demos/features/login-expired', // 这里的 URL 是示例，实际项目中需要根据实际情况进行调整
   },
   {
     color: '#4daf1bc9',
     icon: 'ion:key-outline',
     title: '权限管理',
+    url: '/demos/access/page-control',
   },
   {
     color: '#00d8ff',
     icon: 'ion:bar-chart-outline',
     title: '图表',
+    url: '/analytics',
   },
 ];
 
@@ -195,6 +213,24 @@ const trendItems: WorkbenchTrendItem[] = [
     title: 'Vben',
   },
 ];
+
+const router = useRouter();
+
+// 这是一个示例方法，实际项目中需要根据实际情况进行调整
+// This is a sample method, adjust according to the actual project requirements
+function navTo(nav: WorkbenchProjectItem | WorkbenchQuickNavItem) {
+  if (nav.url?.startsWith('http')) {
+    openWindow(nav.url);
+    return;
+  }
+  if (nav.url?.startsWith('/')) {
+    router.push(nav.url).catch((error) => {
+      console.error('Navigation failed:', error);
+    });
+  } else {
+    console.warn(`Unknown URL for navigation item: ${nav.title} -> ${nav.url}`);
+  }
+}
 </script>
 
 <template>
@@ -210,7 +246,7 @@ const trendItems: WorkbenchTrendItem[] = [
 
     <div class="mt-5 flex flex-col lg:flex-row">
       <div class="mr-4 w-full lg:w-3/5">
-        <WorkbenchProject :items="projectItems" title="项目" />
+        <WorkbenchProject :items="projectItems" title="项目" @click="navTo" />
         <WorkbenchTrends :items="trendItems" class="mt-5" title="最新动态" />
       </div>
       <div class="w-full lg:w-2/5">
@@ -218,6 +254,7 @@ const trendItems: WorkbenchTrendItem[] = [
           :items="quickNavItems"
           class="mt-5 lg:mt-0"
           title="快捷导航"
+          @click="navTo"
         />
         <WorkbenchTodo :items="todoItems" class="mt-5" title="待办事项" />
         <AnalysisChartCard class="mt-5" title="访问来源">

apps/web-ele/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/web-ele",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "homepage": "https://vben.pro",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",
   "repository": {

apps/web-ele/src/adapter/component/index.ts

@@ -4,23 +4,28 @@
  */
 
 import type { BaseFormComponentType } from '@vben/common-ui';
+import type { Recordable } from '@vben/types';
 
 import type { Component, SetupContext } from 'vue';
 import { h } from 'vue';
 
-import { globalShareState } from '@vben/common-ui';
+import { ApiComponent, globalShareState, IconPicker } from '@vben/common-ui';
 import { $t } from '@vben/locales';
 
 import {
   ElButton,
   ElCheckbox,
+  ElCheckboxButton,
   ElCheckboxGroup,
+  ElDatePicker,
   ElDivider,
   ElInput,
   ElInputNumber,
   ElNotification,
+  ElRadio,
+  ElRadioButton,
   ElRadioGroup,
-  ElSelect,
+  ElSelectV2,
   ElSpace,
   ElSwitch,
   ElTimePicker,
@@ -40,10 +45,13 @@ const withDefaultPlaceholder = <T extends Component>(
 
 // 这里需要自行根据业务组件库进行适配，需要用到的组件都需要在这里类型说明
 export type ComponentType =
+  | 'ApiSelect'
+  | 'ApiTreeSelect'
   | 'Checkbox'
   | 'CheckboxGroup'
   | 'DatePicker'
   | 'Divider'
+  | 'IconPicker'
   | 'Input'
   | 'InputNumber'
   | 'RadioGroup'
@@ -60,11 +68,59 @@ async function initComponentAdapter() {
     // 如果你的组件体积比较大，可以使用异步加载
     // Button: () =>
     // import('xxx').then((res) => res.Button),
-
+    ApiSelect: (props, { attrs, slots }) => {
+      return h(
+        ApiComponent,
+        {
+          placeholder: $t('ui.placeholder.select'),
+          ...props,
+          ...attrs,
+          component: ElSelectV2,
+          loadingSlot: 'loading',
+          visibleEvent: 'onVisibleChange',
+        },
+        slots,
+      );
+    },
+    ApiTreeSelect: (props, { attrs, slots }) => {
+      return h(
+        ApiComponent,
+        {
+          placeholder: $t('ui.placeholder.select'),
+          ...props,
+          ...attrs,
+          component: ElTreeSelect,
+          props: { label: 'label', children: 'children' },
+          nodeKey: 'value',
+          loadingSlot: 'loading',
+          optionsPropName: 'data',
+          visibleEvent: 'onVisibleChange',
+        },
+        slots,
+      );
+    },
     Checkbox: ElCheckbox,
-    CheckboxGroup: ElCheckboxGroup,
+    CheckboxGroup: (props, { attrs, slots }) => {
+      let defaultSlot;
+      if (Reflect.has(slots, 'default')) {
+        defaultSlot = slots.default;
+      } else {
+        const { options, isButton } = attrs;
+        if (Array.isArray(options)) {
+          defaultSlot = () =>
+            options.map((option) =>
+              h(isButton ? ElCheckboxButton : ElCheckbox, option),
+            );
+        }
+      }
+      return h(
+        ElCheckboxGroup,
+        { ...props, ...attrs },
+        { ...slots, default: defaultSlot },
+      );
+    },
     // 自定义默认按钮
-    DefaulButton: (props, { attrs, slots }) => {
+    DefaultButton: (props, { attrs, slots }) => {
       return h(ElButton, { ...props, attrs, type: 'info' }, slots);
     },
     // 自定义主要按钮
@@ -72,13 +128,87 @@ async function initComponentAdapter() {
       return h(ElButton, { ...props, attrs, type: 'primary' }, slots);
     },
     Divider: ElDivider,
+    IconPicker: (props, { attrs, slots }) => {
+      return h(
+        IconPicker,
+        {
+          iconSlot: 'append',
+          modelValueProp: 'model-value',
+          inputComponent: ElInput,
+          ...props,
+          ...attrs,
+        },
+        slots,
+      );
+    },
     Input: withDefaultPlaceholder(ElInput, 'input'),
     InputNumber: withDefaultPlaceholder(ElInputNumber, 'input'),
-    RadioGroup: ElRadioGroup,
-    Select: withDefaultPlaceholder(ElSelect, 'select'),
+    RadioGroup: (props, { attrs, slots }) => {
+      let defaultSlot;
+      if (Reflect.has(slots, 'default')) {
+        defaultSlot = slots.default;
+      } else {
+        const { options } = attrs;
+        if (Array.isArray(options)) {
+          defaultSlot = () =>
+            options.map((option) =>
+              h(attrs.isButton ? ElRadioButton : ElRadio, option),
+            );
+        }
+      }
+      return h(
+        ElRadioGroup,
+        { ...props, ...attrs },
+        { ...slots, default: defaultSlot },
+      );
+    },
+    Select: (props, { attrs, slots }) => {
+      return h(ElSelectV2, { ...props, attrs }, slots);
+    },
     Space: ElSpace,
     Switch: ElSwitch,
-    TimePicker: ElTimePicker,
+    TimePicker: (props, { attrs, slots }) => {
+      const { name, id, isRange } = props;
+      const extraProps: Recordable<any> = {};
+      if (isRange) {
+        if (name && !Array.isArray(name)) {
+          extraProps.name = [name, `${name}_end`];
+        }
+        if (id && !Array.isArray(id)) {
+          extraProps.id = [id, `${id}_end`];
+        }
+      }
+      return h(
+        ElTimePicker,
+        {
+          ...props,
+          ...attrs,
+          ...extraProps,
+        },
+        slots,
+      );
+    },
+    DatePicker: (props, { attrs, slots }) => {
+      const { name, id, type } = props;
+      const extraProps: Recordable<any> = {};
+      if (type && type.includes('range')) {
+        if (name && !Array.isArray(name)) {
+          extraProps.name = [name, `${name}_end`];
+        }
+        if (id && !Array.isArray(id)) {
+          extraProps.id = [id, `${id}_end`];
+        }
+      }
+      return h(
+        ElDatePicker,
+        {
+          ...props,
+          ...attrs,
+          ...extraProps,
+        },
+        slots,
+      );
+    },
     TreeSelect: withDefaultPlaceholder(ElTreeSelect, 'select'),
     Upload: ElUpload,
   };

apps/web-ele/src/adapter/form.ts

@@ -12,6 +12,7 @@ setupVbenForm<ComponentType>({
   config: {
     modelPropNameMap: {
       Upload: 'fileList',
+      CheckboxGroup: 'model-value',
     },
   },
   defineRules: {

apps/web-ele/src/bootstrap.ts

@@ -7,6 +7,7 @@ import '@vben/styles';
 import '@vben/styles/ele';
 
 import { useTitle } from '@vueuse/core';
+import { ElLoading } from 'element-plus';
 
 import { $t, setupI18n } from '#/locales';
 
@@ -19,6 +20,9 @@ async function bootstrap(namespace: string) {
   await initComponentAdapter();
   const app = createApp(App);
 
+  // 注册Element Plus提供的v-loading指令
+  app.directive('loading', ElLoading.directive);
+
   // 国际化 i18n 配置
   await setupI18n(app);
 

apps/web-ele/src/locales/langs/en-US/demos.json

@@ -1,6 +1,7 @@
 {
   "title": "Demos",
   "elementPlus": "Element Plus",
+  "form": "Form",
   "vben": {
     "title": "Project",
     "about": "About",

apps/web-ele/src/locales/langs/zh-CN/demos.json

@@ -1,6 +1,7 @@
 {
   "title": "演示",
   "elementPlus": "Element Plus",
+  "form": "表单演示",
   "vben": {
     "title": "项目",
     "about": "关于",

apps/web-ele/src/preferences.ts

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

apps/web-ele/src/router/guard.ts

@@ -54,7 +54,9 @@ function setupAccessGuard(router: Router) {
     if (coreRouteNames.includes(to.name as string)) {
       if (to.path === LOGIN_PATH && accessStore.accessToken) {
         return decodeURIComponent(
-          (to.query?.redirect as string) || DEFAULT_HOME_PATH,
+          (to.query?.redirect as string) ||
+            userStore.userInfo?.homePath ||
+            DEFAULT_HOME_PATH,
         );
       }
       return true;
@@ -72,7 +74,10 @@ function setupAccessGuard(router: Router) {
         return {
           path: LOGIN_PATH,
           // 如不需要，直接删除 query
-          query: { redirect: encodeURIComponent(to.fullPath) },
+          query:
+            to.fullPath === DEFAULT_HOME_PATH
+              ? {}
+              : { redirect: encodeURIComponent(to.fullPath) },
           // 携带当前跳转的页面，登录后重新跳转该页面
           replace: true,
         };
@@ -102,7 +107,10 @@ function setupAccessGuard(router: Router) {
     accessStore.setAccessMenus(accessibleMenus);
     accessStore.setAccessRoutes(accessibleRoutes);
     accessStore.setIsAccessChecked(true);
-    const redirectPath = (from.query.redirect ?? to.fullPath) as string;
+    const redirectPath = (from.query.redirect ??
+      (to.path === DEFAULT_HOME_PATH
+        ? userInfo.homePath || DEFAULT_HOME_PATH
+        : to.fullPath)) as string;
 
     return {
       ...router.resolve(decodeURIComponent(redirectPath)),

apps/web-ele/src/router/routes/index.ts

@@ -17,12 +17,12 @@ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles);
 
 /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */
 // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles);
-/** 不需要权限的菜单列表（会显示在菜单中） */
 // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles);
 const staticRoutes: RouteRecordRaw[] = [];
 const externalRoutes: RouteRecordRaw[] = [];
 
-/** 路由列表，由基本路由+静态路由组成 */
+/** 路由列表，由基本路由、外部路由和404兜底路由组成
+ *  无需走权限验证（会一直显示在菜单中） */
 const routes: RouteRecordRaw[] = [
   ...coreRoutes,
   ...externalRoutes,
@@ -32,5 +32,6 @@ const routes: RouteRecordRaw[] = [
 /** 基本路由列表，这些路由不需要进入权限拦截 */
 const coreRouteNames = traverseTreeValues(coreRoutes, (route) => route.name);
 
+/** 有权限校验的路由列表，包含动态路由和静态路由 */
 const accessRoutes = [...dynamicRoutes, ...staticRoutes];
 export { accessRoutes, coreRouteNames, routes };

apps/web-ele/src/router/routes/modules/demos.ts

@@ -23,6 +23,14 @@ const routes: RouteRecordRaw[] = [
         path: '/demos/element',
         component: () => import('#/views/demos/element/index.vue'),
       },
+      {
+        meta: {
+          title: $t('demos.form'),
+        },
+        name: 'BasicForm',
+        path: '/demos/form',
+        component: () => import('#/views/demos/form/basic.vue'),
+      },
     ],
   },
 ];

apps/web-ele/src/views/_core/authentication/code-login.vue

@@ -10,6 +10,7 @@ import { $t } from '@vben/locales';
 defineOptions({ name: 'CodeLogin' });
 
 const loading = ref(false);
+const CODE_LENGTH = 6;
 
 const formSchema = computed((): VbenFormSchema[] => {
   return [
@@ -30,6 +31,7 @@ const formSchema = computed((): VbenFormSchema[] => {
     {
       component: 'VbenPinInput',
       componentProps: {
+        codeLength: CODE_LENGTH,
         createText: (countdown: number) => {
           const text =
             countdown > 0
@@ -41,7 +43,9 @@ const formSchema = computed((): VbenFormSchema[] => {
       },
       fieldName: 'code',
       label: $t('authentication.code'),
-      rules: z.string().min(1, { message: $t('authentication.codeTip') }),
+      rules: z.string().length(CODE_LENGTH, {
+        message: $t('authentication.codeTip', [CODE_LENGTH]),
+      }),
     },
   ];
 });

apps/web-ele/src/views/dashboard/workspace/index.vue

@@ -7,6 +7,7 @@ import type {
 } from '@vben/common-ui';
 
 import { ref } from 'vue';
+import { useRouter } from 'vue-router';
 
 import {
   AnalysisChartCard,
@@ -18,11 +19,15 @@ import {
 } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { useUserStore } from '@vben/stores';
+import { openWindow } from '@vben/utils';
 
 import AnalyticsVisitsSource from '../analytics/analytics-visits-source.vue';
 
 const userStore = useUserStore();
 
+// 这是一个示例数据，实际项目中需要根据实际情况进行调整
+// url 也可以是内部路由，在 navTo 方法中识别处理，进行内部跳转
+// 例如：url: /dashboard/workspace
 const projectItems: WorkbenchProjectItem[] = [
   {
     color: '',
@@ -31,6 +36,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '开源组',
     icon: 'carbon:logo-github',
     title: 'Github',
+    url: 'https://github.com',
   },
   {
     color: '#3fb27f',
@@ -39,6 +45,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '算法组',
     icon: 'ion:logo-vue',
     title: 'Vue',
+    url: 'https://vuejs.org',
   },
   {
     color: '#e18525',
@@ -47,6 +54,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '上班摸鱼',
     icon: 'ion:logo-html5',
     title: 'Html5',
+    url: 'https://developer.mozilla.org/zh-CN/docs/Web/HTML',
   },
   {
     color: '#bf0c2c',
@@ -55,6 +63,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: 'UI',
     icon: 'ion:logo-angular',
     title: 'Angular',
+    url: 'https://angular.io',
   },
   {
     color: '#00d8ff',
@@ -63,6 +72,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '技术牛',
     icon: 'bx:bxl-react',
     title: 'React',
+    url: 'https://reactjs.org',
   },
   {
     color: '#EBD94E',
@@ -71,39 +81,47 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '架构组',
     icon: 'ion:logo-javascript',
     title: 'Js',
+    url: 'https://developer.mozilla.org/zh-CN/docs/Web/JavaScript',
   },
 ];
 
+// 同样，这里的 url 也可以使用以 http 开头的外部链接
 const quickNavItems: WorkbenchQuickNavItem[] = [
   {
     color: '#1fdaca',
     icon: 'ion:home-outline',
     title: '首页',
+    url: '/',
   },
   {
     color: '#bf0c2c',
     icon: 'ion:grid-outline',
     title: '仪表盘',
+    url: '/dashboard',
   },
   {
     color: '#e18525',
     icon: 'ion:layers-outline',
     title: '组件',
+    url: '/demos/features/icons',
   },
   {
     color: '#3fb27f',
     icon: 'ion:settings-outline',
     title: '系统管理',
+    url: '/demos/features/login-expired', // 这里的 URL 是示例，实际项目中需要根据实际情况进行调整
   },
   {
     color: '#4daf1bc9',
     icon: 'ion:key-outline',
     title: '权限管理',
+    url: '/demos/access/page-control',
   },
   {
     color: '#00d8ff',
     icon: 'ion:bar-chart-outline',
     title: '图表',
+    url: '/analytics',
   },
 ];
 
@@ -195,6 +213,24 @@ const trendItems: WorkbenchTrendItem[] = [
     title: 'Vben',
   },
 ];
+
+const router = useRouter();
+
+// 这是一个示例方法，实际项目中需要根据实际情况进行调整
+// This is a sample method, adjust according to the actual project requirements
+function navTo(nav: WorkbenchProjectItem | WorkbenchQuickNavItem) {
+  if (nav.url?.startsWith('http')) {
+    openWindow(nav.url);
+    return;
+  }
+  if (nav.url?.startsWith('/')) {
+    router.push(nav.url).catch((error) => {
+      console.error('Navigation failed:', error);
+    });
+  } else {
+    console.warn(`Unknown URL for navigation item: ${nav.title} -> ${nav.url}`);
+  }
+}
 </script>
 
 <template>
@@ -210,7 +246,7 @@ const trendItems: WorkbenchTrendItem[] = [
 
     <div class="mt-5 flex flex-col lg:flex-row">
       <div class="mr-4 w-full lg:w-3/5">
-        <WorkbenchProject :items="projectItems" title="项目" />
+        <WorkbenchProject :items="projectItems" title="项目" @click="navTo" />
         <WorkbenchTrends :items="trendItems" class="mt-5" title="最新动态" />
       </div>
       <div class="w-full lg:w-2/5">
@@ -218,6 +254,7 @@ const trendItems: WorkbenchTrendItem[] = [
           :items="quickNavItems"
           class="mt-5 lg:mt-0"
           title="快捷导航"
+          @click="navTo"
         />
         <WorkbenchTodo :items="todoItems" class="mt-5" title="待办事项" />
         <AnalysisChartCard class="mt-5" title="访问来源">

apps/web-ele/src/views/demos/element/index.vue

@@ -1,4 +1,6 @@
 <script lang="ts" setup>
+import { ref } from 'vue';
+
 import { Page } from '@vben/common-ui';
 
 import {
@@ -6,6 +8,7 @@ import {
   ElCard,
   ElMessage,
   ElNotification,
+  ElSegmented,
   ElSpace,
   ElTable,
 } from 'element-plus';
@@ -47,6 +50,10 @@ const tableData = [
   { prop1: '5', prop2: 'E' },
   { prop1: '6', prop2: 'F' },
 ];
+
+const segmentedValue = ref('Mon');
+
+const segmentedOptions = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
 </script>
 
 <template>
@@ -54,41 +61,57 @@ const tableData = [
     description="支持多语言，主题功能集成切换等"
     title="Element Plus组件使用演示"
   >
-    <ElCard class="mb-5">
-      <template #header> 按钮 </template>
-      <ElSpace>
-        <ElButton text>Text</ElButton>
-        <ElButton>Default</ElButton>
-        <ElButton type="primary"> Primary </ElButton>
-        <ElButton type="info"> Info </ElButton>
-        <ElButton type="success"> Success </ElButton>
-        <ElButton type="warning"> Warning </ElButton>
-        <ElButton type="danger"> Error </ElButton>
-      </ElSpace>
-    </ElCard>
-    <ElCard class="mb-5">
-      <template #header> Message </template>
-      <ElSpace>
-        <ElButton type="info" @click="info"> 信息 </ElButton>
-        <ElButton type="danger" @click="error"> 错误 </ElButton>
-        <ElButton type="warning" @click="warning"> 警告 </ElButton>
-        <ElButton type="success" @click="success"> 成功 </ElButton>
-      </ElSpace>
-    </ElCard>
-    <ElCard class="mb-5">
-      <template #header> Notification </template>
-      <ElSpace>
-        <ElButton type="info" @click="notify('info')"> 信息 </ElButton>
-        <ElButton type="danger" @click="notify('error')"> 错误 </ElButton>
-        <ElButton type="warning" @click="notify('warning')"> 警告 </ElButton>
-        <ElButton type="success" @click="notify('success')"> 成功 </ElButton>
-      </ElSpace>
-    </ElCard>
-    <ElCard class="mb-5">
-      <ElTable :data="tableData" stripe>
-        <ElTable.TableColumn label="测试列1" prop="prop1" />
-        <ElTable.TableColumn label="测试列2" prop="prop2" />
-      </ElTable>
-    </ElCard>
+    <div class="flex flex-wrap gap-5">
+      <ElCard class="mb-5 w-auto">
+        <template #header> 按钮 </template>
+        <ElSpace>
+          <ElButton text>Text</ElButton>
+          <ElButton>Default</ElButton>
+          <ElButton type="primary"> Primary </ElButton>
+          <ElButton type="info"> Info </ElButton>
+          <ElButton type="success"> Success </ElButton>
+          <ElButton type="warning"> Warning </ElButton>
+          <ElButton type="danger"> Error </ElButton>
+        </ElSpace>
+      </ElCard>
+      <ElCard class="mb-5 w-80">
+        <template #header> Message </template>
+        <ElSpace>
+          <ElButton type="info" @click="info"> 信息 </ElButton>
+          <ElButton type="danger" @click="error"> 错误 </ElButton>
+          <ElButton type="warning" @click="warning"> 警告 </ElButton>
+          <ElButton type="success" @click="success"> 成功 </ElButton>
+        </ElSpace>
+      </ElCard>
+      <ElCard class="mb-5 w-80">
+        <template #header> Notification </template>
+        <ElSpace>
+          <ElButton type="info" @click="notify('info')"> 信息 </ElButton>
+          <ElButton type="danger" @click="notify('error')"> 错误 </ElButton>
+          <ElButton type="warning" @click="notify('warning')"> 警告 </ElButton>
+          <ElButton type="success" @click="notify('success')"> 成功 </ElButton>
+        </ElSpace>
+      </ElCard>
+      <ElCard class="mb-5 w-auto">
+        <template #header> Segmented </template>
+        <ElSegmented
+          v-model="segmentedValue"
+          :options="segmentedOptions"
+          size="large"
+        />
+      </ElCard>
+      <ElCard class="mb-5 w-80">
+        <template #header> V-Loading </template>
+        <div class="flex size-72 items-center justify-center" v-loading="true">
+          一些演示的内容
+        </div>
+      </ElCard>
+      <ElCard class="mb-5 w-80">
+        <ElTable :data="tableData" stripe>
+          <ElTable.TableColumn label="测试列1" prop="prop1" />
+          <ElTable.TableColumn label="测试列2" prop="prop2" />
+        </ElTable>
+      </ElCard>
+    </div>
   </Page>
 </template>

apps/web-ele/src/views/demos/form/basic.vue

@@ -0,0 +1,181 @@
+<script lang="ts" setup>
+import { h } from 'vue';
+
+import { Page } from '@vben/common-ui';
+
+import { ElButton, ElCard, ElCheckbox, ElMessage } from 'element-plus';
+
+import { useVbenForm } from '#/adapter/form';
+import { getAllMenusApi } from '#/api';
+
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    // 所有表单项
+    componentProps: {
+      class: 'w-full',
+    },
+  },
+  layout: 'horizontal',
+  // 大屏一行显示3个，中屏一行显示2个，小屏一行显示1个
+  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+  handleSubmit: (values) => {
+    ElMessage.success(`表单数据：${JSON.stringify(values)}`);
+  },
+  schema: [
+    {
+      // 组件需要在 #/adapter.ts内注册，并加上类型
+      component: 'ApiSelect',
+      // 对应组件的参数
+      componentProps: {
+        // 菜单接口转options格式
+        afterFetch: (data: { name: string; path: string }[]) => {
+          return data.map((item: any) => ({
+            label: item.name,
+            value: item.path,
+          }));
+        },
+        // 菜单接口
+        api: getAllMenusApi,
+      },
+      // 字段名
+      fieldName: 'api',
+      // 界面显示的label
+      label: 'ApiSelect',
+    },
+    {
+      component: 'ApiTreeSelect',
+      // 对应组件的参数
+      componentProps: {
+        // 菜单接口
+        api: getAllMenusApi,
+        childrenField: 'children',
+        // 菜单接口转options格式
+        labelField: 'name',
+        valueField: 'path',
+      },
+      // 字段名
+      fieldName: 'apiTree',
+      // 界面显示的label
+      label: 'ApiTreeSelect',
+    },
+    {
+      component: 'Input',
+      fieldName: 'string',
+      label: 'String',
+    },
+    {
+      component: 'InputNumber',
+      fieldName: 'number',
+      label: 'Number',
+    },
+    {
+      component: 'RadioGroup',
+      fieldName: 'radio',
+      label: 'Radio',
+      componentProps: {
+        options: [
+          { value: 'A', label: 'A' },
+          { value: 'B', label: 'B' },
+          { value: 'C', label: 'C' },
+          { value: 'D', label: 'D' },
+          { value: 'E', label: 'E' },
+        ],
+      },
+    },
+    {
+      component: 'RadioGroup',
+      fieldName: 'radioButton',
+      label: 'RadioButton',
+      componentProps: {
+        isButton: true,
+        options: ['A', 'B', 'C', 'D', 'E', 'F'].map((v) => ({
+          value: v,
+          label: `选项${v}`,
+        })),
+      },
+    },
+    {
+      component: 'CheckboxGroup',
+      fieldName: 'checkbox',
+      label: 'Checkbox',
+      componentProps: {
+        options: ['A', 'B', 'C'].map((v) => ({ value: v, label: `选项${v}` })),
+      },
+    },
+    {
+      component: 'CheckboxGroup',
+      fieldName: 'checkbox1',
+      label: 'Checkbox1',
+      renderComponentContent: () => {
+        return {
+          default: () => {
+            return ['A', 'B', 'C', 'D'].map((v) =>
+              h(ElCheckbox, { label: v, value: v }),
+            );
+          },
+        };
+      },
+    },
+    {
+      component: 'CheckboxGroup',
+      fieldName: 'checkbotton',
+      label: 'CheckBotton',
+      componentProps: {
+        isButton: true,
+        options: [
+          { value: 'A', label: '选项A' },
+          { value: 'B', label: '选项B' },
+          { value: 'C', label: '选项C' },
+        ],
+      },
+    },
+    {
+      component: 'DatePicker',
+      fieldName: 'date',
+      label: 'Date',
+    },
+    {
+      component: 'Select',
+      fieldName: 'select',
+      label: 'Select',
+      componentProps: {
+        filterable: true,
+        options: [
+          { value: 'A', label: '选项A' },
+          { value: 'B', label: '选项B' },
+          { value: 'C', label: '选项C' },
+        ],
+      },
+    },
+  ],
+});
+function setFormValues() {
+  formApi.setValues({
+    string: 'string',
+    number: 123,
+    radio: 'B',
+    radioButton: 'C',
+    checkbox: ['A', 'C'],
+    checkbotton: ['B', 'C'],
+    checkbox1: ['A', 'B'],
+    date: new Date(),
+    select: 'B',
+  });
+}
+</script>
+<template>
+  <Page
+    description="我们重新包装了CheckboxGroup、RadioGroup、Select，可以通过options属性传入选项属性数组以自动生成选项"
+    title="表单演示"
+  >
+    <ElCard>
+      <template #header>
+        <div class="flex items-center">
+          <span class="flex-auto">基础表单演示</span>
+          <ElButton type="primary" @click="setFormValues">设置表单值</ElButton>
+        </div>
+      </template>
+      <Form />
+    </ElCard>
+  </Page>
+</template>

apps/web-naive/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/web-naive",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "homepage": "https://vben.pro",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",
   "repository": {

apps/web-naive/src/adapter/component/index.ts

@@ -8,7 +8,7 @@ import type { BaseFormComponentType } from '@vben/common-ui';
 import type { Component, SetupContext } from 'vue';
 import { h } from 'vue';
 
-import { globalShareState } from '@vben/common-ui';
+import { ApiComponent, globalShareState, IconPicker } from '@vben/common-ui';
 import { $t } from '@vben/locales';
 
 import {
@@ -19,6 +19,8 @@ import {
   NDivider,
   NInput,
   NInputNumber,
+  NRadio,
+  NRadioButton,
   NRadioGroup,
   NSelect,
   NSpace,
@@ -42,10 +44,13 @@ const withDefaultPlaceholder = <T extends Component>(
 
 // 这里需要自行根据业务组件库进行适配，需要用到的组件都需要在这里类型说明
 export type ComponentType =
+  | 'ApiSelect'
+  | 'ApiTreeSelect'
   | 'Checkbox'
   | 'CheckboxGroup'
   | 'DatePicker'
   | 'Divider'
+  | 'IconPicker'
   | 'Input'
   | 'InputNumber'
   | 'RadioGroup'
@@ -63,8 +68,54 @@ async function initComponentAdapter() {
     // Button: () =>
     // import('xxx').then((res) => res.Button),
 
+    ApiSelect: (props, { attrs, slots }) => {
+      return h(
+        ApiComponent,
+        {
+          placeholder: $t('ui.placeholder.select'),
+          ...props,
+          ...attrs,
+          component: NSelect,
+          modelPropName: 'value',
+        },
+        slots,
+      );
+    },
+    ApiTreeSelect: (props, { attrs, slots }) => {
+      return h(
+        ApiComponent,
+        {
+          placeholder: $t('ui.placeholder.select'),
+          ...props,
+          ...attrs,
+          component: NTreeSelect,
+          nodeKey: 'value',
+          loadingSlot: 'arrow',
+          keyField: 'value',
+          modelPropName: 'value',
+          optionsPropName: 'options',
+          visibleEvent: 'onVisibleChange',
+        },
+        slots,
+      );
+    },
     Checkbox: NCheckbox,
-    CheckboxGroup: NCheckboxGroup,
+    CheckboxGroup: (props, { attrs, slots }) => {
+      let defaultSlot;
+      if (Reflect.has(slots, 'default')) {
+        defaultSlot = slots.default;
+      } else {
+        const { options } = attrs;
+        if (Array.isArray(options)) {
+          defaultSlot = () => options.map((option) => h(NCheckbox, option));
+        }
+      }
+      return h(
+        NCheckboxGroup,
+        { ...props, ...attrs },
+        { default: defaultSlot },
+      );
+    },
     DatePicker: NDatePicker,
     // 自定义默认按钮
     DefaultButton: (props, { attrs, slots }) => {
@@ -75,9 +126,37 @@ async function initComponentAdapter() {
       return h(NButton, { ...props, attrs, type: 'primary' }, slots);
     },
     Divider: NDivider,
+    IconPicker: (props, { attrs, slots }) => {
+      return h(
+        IconPicker,
+        { iconSlot: 'suffix', inputComponent: NInput, ...props, ...attrs },
+        slots,
+      );
+    },
     Input: withDefaultPlaceholder(NInput, 'input'),
     InputNumber: withDefaultPlaceholder(NInputNumber, 'input'),
-    RadioGroup: NRadioGroup,
+    RadioGroup: (props, { attrs, slots }) => {
+      let defaultSlot;
+      if (Reflect.has(slots, 'default')) {
+        defaultSlot = slots.default;
+      } else {
+        const { options } = attrs;
+        if (Array.isArray(options)) {
+          defaultSlot = () =>
+            options.map((option) =>
+              h(attrs.isButton ? NRadioButton : NRadio, option),
+            );
+        }
+      }
+      const groupRender = h(
+        NRadioGroup,
+        { ...props, ...attrs },
+        { default: defaultSlot },
+      );
+      return attrs.isButton
+        ? h(NSpace, { vertical: true }, () => groupRender)
+        : groupRender;
+    },
     Select: withDefaultPlaceholder(NSelect, 'select'),
     Space: NSpace,
     Switch: NSwitch,

apps/web-naive/src/adapter/form.ts

@@ -10,8 +10,6 @@ import { $t } from '@vben/locales';
 
 setupVbenForm<ComponentType>({
   config: {
-    // naive-ui组件不接受onChang事件，所以需要禁用
-    disabledOnChangeListener: true,
     // naive-ui组件的空值为null,不能是undefined，否则重置表单时不生效
     emptyStateValue: null,
     baseModelPropName: 'value',

apps/web-naive/src/locales/langs/en-US/demos.json

@@ -2,6 +2,7 @@
   "title": "Demos",
   "naive": "Naive UI",
   "table": "Table",
+  "form": "Form",
   "vben": {
     "title": "Project",
     "about": "About",

apps/web-naive/src/locales/langs/zh-CN/demos.json

@@ -2,6 +2,7 @@
   "title": "演示",
   "naive": "Naive UI",
   "table": "Table",
+  "form": "表单",
   "vben": {
     "title": "项目",
     "about": "关于",

apps/web-naive/src/preferences.ts

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

apps/web-naive/src/router/guard.ts

@@ -54,7 +54,9 @@ function setupAccessGuard(router: Router) {
     if (coreRouteNames.includes(to.name as string)) {
       if (to.path === LOGIN_PATH && accessStore.accessToken) {
         return decodeURIComponent(
-          (to.query?.redirect as string) || DEFAULT_HOME_PATH,
+          (to.query?.redirect as string) ||
+            userStore.userInfo?.homePath ||
+            DEFAULT_HOME_PATH,
         );
       }
       return true;
@@ -72,7 +74,10 @@ function setupAccessGuard(router: Router) {
         return {
           path: LOGIN_PATH,
           // 如不需要，直接删除 query
-          query: { redirect: encodeURIComponent(to.fullPath) },
+          query:
+            to.fullPath === DEFAULT_HOME_PATH
+              ? {}
+              : { redirect: encodeURIComponent(to.fullPath) },
           // 携带当前跳转的页面，登录后重新跳转该页面
           replace: true,
         };
@@ -101,7 +106,10 @@ function setupAccessGuard(router: Router) {
     accessStore.setAccessMenus(accessibleMenus);
     accessStore.setAccessRoutes(accessibleRoutes);
     accessStore.setIsAccessChecked(true);
-    const redirectPath = (from.query.redirect ?? to.fullPath) as string;
+    const redirectPath = (from.query.redirect ??
+      (to.path === DEFAULT_HOME_PATH
+        ? userInfo.homePath || DEFAULT_HOME_PATH
+        : to.fullPath)) as string;
 
     return {
       ...router.resolve(decodeURIComponent(redirectPath)),

apps/web-naive/src/router/routes/index.ts

@@ -17,12 +17,12 @@ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles);
 
 /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */
 // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles);
-/** 不需要权限的菜单列表（会显示在菜单中） */
 // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles);
 const staticRoutes: RouteRecordRaw[] = [];
 const externalRoutes: RouteRecordRaw[] = [];
 
-/** 路由列表，由基本路由+静态路由组成 */
+/** 路由列表，由基本路由、外部路由和404兜底路由组成
+ *  无需走权限验证（会一直显示在菜单中） */
 const routes: RouteRecordRaw[] = [
   ...coreRoutes,
   ...externalRoutes,
@@ -32,5 +32,6 @@ const routes: RouteRecordRaw[] = [
 /** 基本路由列表，这些路由不需要进入权限拦截 */
 const coreRouteNames = traverseTreeValues(coreRoutes, (route) => route.name);
 
+/** 有权限校验的路由列表，包含动态路由和静态路由 */
 const accessRoutes = [...dynamicRoutes, ...staticRoutes];
 export { accessRoutes, coreRouteNames, routes };

apps/web-naive/src/router/routes/modules/demos.ts

@@ -31,6 +31,14 @@ const routes: RouteRecordRaw[] = [
         path: '/demos/table',
         component: () => import('#/views/demos/table/index.vue'),
       },
+      {
+        meta: {
+          title: $t('demos.form'),
+        },
+        name: 'Form',
+        path: '/demos/form',
+        component: () => import('#/views/demos/form/basic.vue'),
+      },
     ],
   },
 ];

apps/web-naive/src/views/_core/authentication/code-login.vue

@@ -10,6 +10,7 @@ import { $t } from '@vben/locales';
 defineOptions({ name: 'CodeLogin' });
 
 const loading = ref(false);
+const CODE_LENGTH = 6;
 
 const formSchema = computed((): VbenFormSchema[] => {
   return [
@@ -30,6 +31,7 @@ const formSchema = computed((): VbenFormSchema[] => {
     {
       component: 'VbenPinInput',
       componentProps: {
+        codeLength: CODE_LENGTH,
         createText: (countdown: number) => {
           const text =
             countdown > 0
@@ -41,7 +43,9 @@ const formSchema = computed((): VbenFormSchema[] => {
       },
       fieldName: 'code',
       label: $t('authentication.code'),
-      rules: z.string().min(1, { message: $t('authentication.codeTip') }),
+      rules: z.string().length(CODE_LENGTH, {
+        message: $t('authentication.codeTip', [CODE_LENGTH]),
+      }),
     },
   ];
 });

apps/web-naive/src/views/dashboard/workspace/index.vue

@@ -7,6 +7,7 @@ import type {
 } from '@vben/common-ui';
 
 import { ref } from 'vue';
+import { useRouter } from 'vue-router';
 
 import {
   AnalysisChartCard,
@@ -18,11 +19,15 @@ import {
 } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { useUserStore } from '@vben/stores';
+import { openWindow } from '@vben/utils';
 
 import AnalyticsVisitsSource from '../analytics/analytics-visits-source.vue';
 
 const userStore = useUserStore();
 
+// 这是一个示例数据，实际项目中需要根据实际情况进行调整
+// url 也可以是内部路由，在 navTo 方法中识别处理，进行内部跳转
+// 例如：url: /dashboard/workspace
 const projectItems: WorkbenchProjectItem[] = [
   {
     color: '',
@@ -31,6 +36,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '开源组',
     icon: 'carbon:logo-github',
     title: 'Github',
+    url: 'https://github.com',
   },
   {
     color: '#3fb27f',
@@ -39,6 +45,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '算法组',
     icon: 'ion:logo-vue',
     title: 'Vue',
+    url: 'https://vuejs.org',
   },
   {
     color: '#e18525',
@@ -47,6 +54,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '上班摸鱼',
     icon: 'ion:logo-html5',
     title: 'Html5',
+    url: 'https://developer.mozilla.org/zh-CN/docs/Web/HTML',
   },
   {
     color: '#bf0c2c',
@@ -55,6 +63,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: 'UI',
     icon: 'ion:logo-angular',
     title: 'Angular',
+    url: 'https://angular.io',
   },
   {
     color: '#00d8ff',
@@ -63,6 +72,7 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '技术牛',
     icon: 'bx:bxl-react',
     title: 'React',
+    url: 'https://reactjs.org',
   },
   {
     color: '#EBD94E',
@@ -71,39 +81,47 @@ const projectItems: WorkbenchProjectItem[] = [
     group: '架构组',
     icon: 'ion:logo-javascript',
     title: 'Js',
+    url: 'https://developer.mozilla.org/zh-CN/docs/Web/JavaScript',
   },
 ];
 
+// 同样，这里的 url 也可以使用以 http 开头的外部链接
 const quickNavItems: WorkbenchQuickNavItem[] = [
   {
     color: '#1fdaca',
     icon: 'ion:home-outline',
     title: '首页',
+    url: '/',
   },
   {
     color: '#bf0c2c',
     icon: 'ion:grid-outline',
     title: '仪表盘',
+    url: '/dashboard',
   },
   {
     color: '#e18525',
     icon: 'ion:layers-outline',
     title: '组件',
+    url: '/demos/features/icons',
   },
   {
     color: '#3fb27f',
     icon: 'ion:settings-outline',
     title: '系统管理',
+    url: '/demos/features/login-expired', // 这里的 URL 是示例，实际项目中需要根据实际情况进行调整
   },
   {
     color: '#4daf1bc9',
     icon: 'ion:key-outline',
     title: '权限管理',
+    url: '/demos/access/page-control',
   },
   {
     color: '#00d8ff',
     icon: 'ion:bar-chart-outline',
     title: '图表',
+    url: '/analytics',
   },
 ];
 
@@ -195,6 +213,24 @@ const trendItems: WorkbenchTrendItem[] = [
     title: 'Vben',
   },
 ];
+
+const router = useRouter();
+
+// 这是一个示例方法，实际项目中需要根据实际情况进行调整
+// This is a sample method, adjust according to the actual project requirements
+function navTo(nav: WorkbenchProjectItem | WorkbenchQuickNavItem) {
+  if (nav.url?.startsWith('http')) {
+    openWindow(nav.url);
+    return;
+  }
+  if (nav.url?.startsWith('/')) {
+    router.push(nav.url).catch((error) => {
+      console.error('Navigation failed:', error);
+    });
+  } else {
+    console.warn(`Unknown URL for navigation item: ${nav.title} -> ${nav.url}`);
+  }
+}
 </script>
 
 <template>
@@ -210,7 +246,7 @@ const trendItems: WorkbenchTrendItem[] = [
 
     <div class="mt-5 flex flex-col lg:flex-row">
       <div class="mr-4 w-full lg:w-3/5">
-        <WorkbenchProject :items="projectItems" title="项目" />
+        <WorkbenchProject :items="projectItems" title="项目" @click="navTo" />
         <WorkbenchTrends :items="trendItems" class="mt-5" title="最新动态" />
       </div>
       <div class="w-full lg:w-2/5">
@@ -218,6 +254,7 @@ const trendItems: WorkbenchTrendItem[] = [
           :items="quickNavItems"
           class="mt-5 lg:mt-0"
           title="快捷导航"
+          @click="navTo"
         />
         <WorkbenchTodo :items="todoItems" class="mt-5" title="待办事项" />
         <AnalysisChartCard class="mt-5" title="访问来源">

apps/web-naive/src/views/demos/form/basic.vue

@@ -0,0 +1,143 @@
+<script lang="ts" setup>
+import { Page } from '@vben/common-ui';
+
+import { NButton, NCard, useMessage } from 'naive-ui';
+
+import { useVbenForm } from '#/adapter/form';
+import { getAllMenusApi } from '#/api';
+
+const message = useMessage();
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    // 所有表单项
+    componentProps: {
+      class: 'w-full',
+    },
+  },
+  layout: 'horizontal',
+  // 大屏一行显示3个，中屏一行显示2个，小屏一行显示1个
+  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+  handleSubmit: (values) => {
+    message.success(`表单数据：${JSON.stringify(values)}`);
+  },
+  schema: [
+    {
+      // 组件需要在 #/adapter.ts内注册，并加上类型
+      component: 'ApiSelect',
+      // 对应组件的参数
+      componentProps: {
+        // 菜单接口转options格式
+        afterFetch: (data: { name: string; path: string }[]) => {
+          return data.map((item: any) => ({
+            label: item.name,
+            value: item.path,
+          }));
+        },
+        // 菜单接口
+        api: getAllMenusApi,
+      },
+      // 字段名
+      fieldName: 'api',
+      // 界面显示的label
+      label: 'ApiSelect',
+    },
+    {
+      component: 'ApiTreeSelect',
+      // 对应组件的参数
+      componentProps: {
+        // 菜单接口
+        api: getAllMenusApi,
+        childrenField: 'children',
+        // 菜单接口转options格式
+        labelField: 'name',
+        valueField: 'path',
+      },
+      // 字段名
+      fieldName: 'apiTree',
+      // 界面显示的label
+      label: 'ApiTreeSelect',
+    },
+    {
+      component: 'Input',
+      fieldName: 'string',
+      label: 'String',
+    },
+    {
+      component: 'InputNumber',
+      fieldName: 'number',
+      label: 'Number',
+    },
+    {
+      component: 'RadioGroup',
+      fieldName: 'radio',
+      label: 'Radio',
+      componentProps: {
+        options: [
+          { value: 'A', label: 'A' },
+          { value: 'B', label: 'B' },
+          { value: 'C', label: 'C' },
+          { value: 'D', label: 'D' },
+          { value: 'E', label: 'E' },
+        ],
+      },
+    },
+    {
+      component: 'RadioGroup',
+      fieldName: 'radioButton',
+      label: 'RadioButton',
+      componentProps: {
+        isButton: true,
+        class: 'flex flex-wrap', // 如果选项过多，可以添加class来自动折叠
+        options: [
+          { value: 'A', label: '选项A' },
+          { value: 'B', label: '选项B' },
+          { value: 'C', label: '选项C' },
+          { value: 'D', label: '选项D' },
+          { value: 'E', label: '选项E' },
+          { value: 'F', label: '选项F' },
+        ],
+      },
+    },
+    {
+      component: 'CheckboxGroup',
+      fieldName: 'checkbox',
+      label: 'Checkbox',
+      componentProps: {
+        options: [
+          { value: 'A', label: '选项A' },
+          { value: 'B', label: '选项B' },
+          { value: 'C', label: '选项C' },
+        ],
+      },
+    },
+    {
+      component: 'DatePicker',
+      fieldName: 'date',
+      label: 'Date',
+    },
+  ],
+});
+function setFormValues() {
+  formApi.setValues({
+    string: 'string',
+    number: 123,
+    radio: 'B',
+    radioButton: 'C',
+    checkbox: ['A', 'C'],
+    date: Date.now(),
+  });
+}
+</script>
+<template>
+  <Page
+    description="表单适配器重新包装了CheckboxGroup和RadioGroup，可以通过options属性传递选项数据（选项数据将作为子组件的属性）"
+    title="表单演示"
+  >
+    <NCard title="基础表单">
+      <template #header-extra>
+        <NButton type="primary" @click="setFormValues">设置表单值</NButton>
+      </template>
+      <Form />
+    </NCard>
+  </Page>
+</template>

cspell.json

@@ -4,53 +4,55 @@
   "language": "en,en-US",
   "allowCompoundWords": true,
   "words": [
-    "clsx",
-    "esno",
-    "demi",
-    "unref",
-    "taze",
     "acmr",
     "antd",
-    "lucide",
+    "antdv",
+    "astro",
     "brotli",
+    "clsx",
     "defu",
+    "demi",
+    "echarts",
+    "ependencies",
+    "esno",
+    "etag",
     "execa",
     "iconify",
+    "iconoir",
     "intlify",
+    "lockb",
+    "lucide",
+    "minh",
+    "minw",
     "mkdist",
     "mockjs",
-    "vitejs",
+    "naiveui",
+    "nocheck",
     "noopener",
     "noreferrer",
     "nprogress",
+    "nuxt",
     "pinia",
+    "prefixs",
     "publint",
     "qrcode",
     "shadcn",
     "sonner",
+    "sortablejs",
+    "styl",
+    "taze",
+    "ui-kit",
+    "uicons",
     "unplugin",
+    "unref",
     "vben",
     "vbenjs",
-    "vueuse",
-    "yxxx",
-    "nuxt",
-    "lockb",
-    "astro",
-    "ui-kit",
-    "styl",
-    "vnode",
-    "nocheck",
-    "prefixs",
-    "vitepress",
-    "antdv",
-    "ependencies",
     "vite",
-    "echarts",
-    "sortablejs",
-    "etag",
-    "naiveui",
-    "uicons",
-    "iconoir"
+    "vitejs",
+    "vitepress",
+    "vnode",
+    "vueuse",
+    "yxxx"
   ],
   "ignorePaths": [
     "**/node_modules/**",

docs/.vitepress/config/en.mts

@@ -221,9 +221,9 @@ function nav(): DefaultTheme.NavItem[] {
       link: '/commercial/community',
       text: '👨‍👦‍👦 Community',
     },
-    {
-      link: '/friend-links/',
-      text: '🤝 Friend Links',
-    },
+    // {
+    //   link: '/friend-links/',
+    //   text: '🤝 Friend Links',
+    // },
   ];
 }

docs/.vitepress/config/shared.mts

@@ -3,7 +3,10 @@ import type { HeadConfig } from 'vitepress';
 
 import { resolve } from 'node:path';
 
-import { viteArchiverPlugin } from '@vben/vite-config';
+import {
+  viteArchiverPlugin,
+  viteVxeTableImportsPlugin,
+} from '@vben/vite-config';
 
 import {
   GitChangelog,
@@ -59,6 +62,11 @@ export const shared = defineConfig({
           postcssIsolateStyles({ includeFiles: [/vp-doc\.css/] }),
         ],
       },
+      preprocessorOptions: {
+        scss: {
+          api: 'modern',
+        },
+      },
     },
     json: {
       stringify: true,
@@ -85,6 +93,7 @@ export const shared = defineConfig({
       GitChangelogMarkdownSection(),
       viteArchiverPlugin({ outputDir: '.vitepress' }),
       groupIconVitePlugin(),
+      await viteVxeTableImportsPlugin(),
     ],
     server: {
       fs: {
@@ -93,6 +102,7 @@ export const shared = defineConfig({
       host: true,
       port: 6173,
     },
+
     ssr: {
       external: ['@vue/repl'],
     },
@@ -156,6 +166,7 @@ function pwa(): PwaOptions {
     registerType: 'autoUpdate',
     workbox: {
       globPatterns: ['**/*.{css,js,html,svg,png,ico,txt,woff2}'],
+      maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
     },
   };
 }

docs/.vitepress/config/zh.mts

@@ -124,7 +124,7 @@ function sidebarCommercial(): DefaultTheme.SidebarItem[] {
   return [
     {
       link: 'community',
-      text: '社区',
+      text: '交流群',
     },
     {
       link: 'technical-support',
@@ -148,10 +148,24 @@ function sidebarComponents(): DefaultTheme.SidebarItem[] {
         },
       ],
     },
+    {
+      collapsed: false,
+      text: '布局组件',
+      items: [
+        {
+          link: 'layout-ui/page',
+          text: 'Page 页面',
+        },
+      ],
+    },
     {
       collapsed: false,
       text: '通用组件',
       items: [
+        {
+          link: 'common-ui/vben-api-component',
+          text: 'ApiComponent Api组件包装器',
+        },
         {
           link: 'common-ui/vben-modal',
           text: 'Modal 模态框',
@@ -172,6 +186,10 @@ function sidebarComponents(): DefaultTheme.SidebarItem[] {
           link: 'common-ui/vben-count-to-animator',
           text: 'CountToAnimator 数字动画',
         },
+        {
+          link: 'common-ui/vben-ellipsis-text',
+          text: 'EllipsisText 省略文本',
+        },
       ],
     },
   ];
@@ -266,7 +284,7 @@ function nav(): DefaultTheme.NavItem[] {
     },
     {
       link: '/commercial/community',
-      text: '👨‍👦‍👦 社区',
+      text: '👨‍👦‍👦 交流群',
       // items: [
       //   {
       //     link: 'https://qun.qq.com/qqweb/qunpro/share?_wv=3&_wwv=128&appChannel=share&inviteCode=22ySzj7pKiw&businessType=9&from=246610&biz=ka&mainSourceId=share&subSourceId=others&jumpsource=shorturl#/pc',
@@ -282,10 +300,10 @@ function nav(): DefaultTheme.NavItem[] {
       //   },
       // ],
     },
-    {
-      link: '/friend-links/',
-      text: '🤝 友情链接',
-    },
+    // {
+    //   link: '/friend-links/',
+    //   text: '🤝 友情链接',
+    // },
   ];
 }
 

docs/.vitepress/theme/index.ts

@@ -15,11 +15,12 @@ import 'virtual:group-icons.css';
 import '@nolebase/vitepress-plugin-git-changelog/client/style.css';
 
 export default {
-  enhanceApp(ctx: EnhanceAppContext) {
+  async enhanceApp(ctx: EnhanceAppContext) {
     const { app } = ctx;
     app.component('VbenContributors', VbenContributors);
     app.component('DemoPreview', DemoPreview);
     app.use(NolebaseGitChangelogPlugin);
+
     // 百度统计
     initHmPlugin();
   },

docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/docs",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "scripts": {
     "build": "vitepress build",
@@ -8,12 +8,16 @@
     "docs:preview": "vitepress preview"
   },
   "imports": {
-    "#/*": "./src/_env/*"
+    "#/*": {
+      "node": "./src/_env/node/*",
+      "default": "./src/_env/*"
+    }
   },
   "dependencies": {
     "@vben-core/shadcn-ui": "workspace:*",
     "@vben/common-ui": "workspace:*",
     "@vben/locales": "workspace:*",
+    "@vben/plugins": "workspace:*",
     "@vben/styles": "workspace:*",
     "ant-design-vue": "catalog:",
     "lucide-vue-next": "catalog:",

docs/src/_env/adapter/form.ts

@@ -14,8 +14,6 @@ initComponentAdapter();
 setupVbenForm<ComponentType>({
   config: {
     baseModelPropName: 'value',
-    // naive-ui组件不接受onChang事件，所以需要禁用
-    disabledOnChangeListener: true,
     // naive-ui组件的空值为null,不能是undefined，否则重置表单时不生效
     emptyStateValue: null,
     modelPropNameMap: {

docs/src/_env/adapter/index.ts

@@ -1 +0,0 @@
-export * from './form';

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

@@ -0,0 +1,70 @@
+import { h } from 'vue';
+
+import { setupVbenVxeTable, useVbenVxeGrid } from '@vben/plugins/vxe-table';
+
+import { Button, Image } from 'ant-design-vue';
+
+import { useVbenForm } from './form';
+
+if (!import.meta.env.SSR) {
+  setupVbenVxeTable({
+    configVxeTable: (vxeUI) => {
+      vxeUI.setConfig({
+        grid: {
+          align: 'center',
+          border: false,
+          columnConfig: {
+            resizable: true,
+          },
+
+          formConfig: {
+            // 全局禁用vxe-table的表单配置，使用formOptions
+            enabled: false,
+          },
+          minHeight: 180,
+          proxyConfig: {
+            autoLoad: true,
+            response: {
+              result: 'items',
+              total: 'total',
+              list: 'items',
+            },
+            showActiveMsg: true,
+            showResponseMsg: false,
+          },
+          round: true,
+          showOverflow: true,
+          size: 'small',
+        },
+      });
+
+      // 表格配置项可以用 cellRender: { name: 'CellImage' },
+      vxeUI.renderer.add('CellImage', {
+        renderTableDefault(_renderOpts, params) {
+          const { column, row } = params;
+          return h(Image, { src: row[column.field] });
+        },
+      });
+
+      // 表格配置项可以用 cellRender: { name: 'CellLink' },
+      vxeUI.renderer.add('CellLink', {
+        renderTableDefault(renderOpts) {
+          const { props } = renderOpts;
+          return h(
+            Button,
+            { size: 'small', type: 'link' },
+            { default: () => props?.text },
+          );
+        },
+      });
+
+      // 这里可以自行扩展 vxe-table 的全局配置，比如自定义格式化
+      // vxeUI.formats.add
+    },
+    useVbenForm,
+  });
+}
+
+export { useVbenVxeGrid };
+
+export type * from '@vben/plugins/vxe-table';

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

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

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

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

docs/src/commercial/community.md

@@ -20,7 +20,10 @@
 
 ::: tip
 
-因为微信群人数有限制，加微信群前，你可以通过[赞助](../sponsor/personal.md)任意金额，主动发送截图给作者，备注`加入微信群`即可。
+因为微信群人数有限制，加微信群要求：
+
+- 通过[赞助](../sponsor/personal.md)任意金额。
+- 发送赞助`截图`，备注`加入微信群`即可。
 
 :::
 

docs/src/components/common-ui/vben-api-component.md

@@ -0,0 +1,152 @@
+---
+outline: deep
+---
+
+# Vben ApiComponent Api组件包装器
+
+框架提供的API“包装器”，它一般不独立使用，主要用于包装其它组件，为目标组件提供自动获取远程数据的能力，但仍然保持了目标组件的原始用法。
+
+::: info 写在前面
+
+我们在各个应用的组件适配器中，使用ApiComponent包装了Select、TreeSelect组件，使得这些组件可以自动获取远程数据并生成选项。其它类似的组件（比如Cascader）如有需要也可以参考示例代码自行进行包装。
+
+:::
+
+## 基础用法
+
+通过 `component` 传入其它组件的定义，并配置相关的其它属性（主要是一些名称映射）。包装组件将通过`api`获取数据（`beforerFetch`、`afterFetch`将分别在`api`运行前、运行后被调用），使用`resultField`从中提取数组，使用`valueField`、`labelField`等来从数据中提取value和label（如果提供了`childrenField`，会将其作为树形结构递归处理每一级数据），之后将处理好的数据通过`optionsPropName`指定的属性传递给目标组件。
+
+::: details 包装级联选择器,点击下拉时开始加载远程数据
+
+```vue
+<script lang="ts" setup>
+import { ApiComponent } from '@vben/common-ui';
+
+import { Cascader } from 'ant-design-vue';
+
+const treeData: Record<string, any> = [
+  {
+    label: '浙江',
+    value: 'zhejiang',
+    children: [
+      {
+        value: 'hangzhou',
+        label: '杭州',
+        children: [
+          {
+            value: 'xihu',
+            label: '西湖',
+          },
+          {
+            value: 'sudi',
+            label: '苏堤',
+          },
+        ],
+      },
+      {
+        value: 'jiaxing',
+        label: '嘉兴',
+        children: [
+          {
+            value: 'wuzhen',
+            label: '乌镇',
+          },
+          {
+            value: 'meihuazhou',
+            label: '梅花洲',
+          },
+        ],
+      },
+      {
+        value: 'zhoushan',
+        label: '舟山',
+        children: [
+          {
+            value: 'putuoshan',
+            label: '普陀山',
+          },
+          {
+            value: 'taohuadao',
+            label: '桃花岛',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    label: '江苏',
+    value: 'jiangsu',
+    children: [
+      {
+        value: 'nanjing',
+        label: '南京',
+        children: [
+          {
+            value: 'zhonghuamen',
+            label: '中华门',
+          },
+          {
+            value: 'zijinshan',
+            label: '紫金山',
+          },
+          {
+            value: 'yuhuatai',
+            label: '雨花台',
+          },
+        ],
+      },
+    ],
+  },
+];
+/**
+ * 模拟请求接口
+ */
+function fetchApi(): Promise<Record<string, any>> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(treeData);
+    }, 1000);
+  });
+}
+</script>
+<template>
+  <ApiComponent
+    :api="fetchApi"
+    :component="Cascader"
+    :immediate="false"
+    children-field="children"
+    loading-slot="suffixIcon"
+    visible-event="onDropdownVisibleChange"
+  />
+</template>
+```
+
+:::
+
+## API
+
+### Props
+
+| 属性名 | 描述 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| 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` | - |
+
+```
+
+```

docs/src/components/common-ui/vben-drawer.md

@@ -74,6 +74,7 @@ const [Drawer, drawerApi] = useVbenDrawer({
 
 | 属性名 | 描述 | 类型 | 默认值 |
 | --- | --- | --- | --- |
+| appendToMain | 是否挂载到内容区域（默认挂载到body） | `boolean` | `false` |
 | title | 标题 | `string\|slot` | - |
 | titleTooltip | 标题提示信息 | `string\|slot` | - |
 | description | 描述信息 | `string\|slot` | - |
@@ -88,12 +89,20 @@ const [Drawer, drawerApi] = useVbenDrawer({
 | closeOnPressEscape | esc 关闭弹窗 | `boolean` | `true` |
 | confirmText | 确认按钮文本 | `string\|slot` | `确认` |
 | cancelText | 取消按钮文本 | `string\|slot` | `取消` |
+| placement | 抽屉弹出位置 | `'left'\|'right'\|'top'\|'bottom'` | `right` |
 | showCancelButton | 显示取消按钮 | `boolean` | `true` |
 | showConfirmButton | 显示确认按钮文本 | `boolean` | `true` |
 | class | modal的class，宽度通过这个配置 | `string` | - |
 | contentClass | modal内容区域的class | `string` | - |
 | footerClass | modal底部区域的class | `string` | - |
 | headerClass | modal顶部区域的class | `string` | - |
+| zIndex | 抽屉的ZIndex层级 | `number` | `1000` |
+
+::: info appendToMain
+
+`appendToMain`可以指定将抽屉挂载到内容区域，打开抽屉时，内容区域以外的部分（标签栏、导航菜单等等）不会被遮挡。默认情况下，抽屉会挂载到body上。但是：挂载到内容区域时，作为页面根容器的`Page`组件，需要设置`auto-content-height`属性，以便抽屉能够正确计算高度。
+
+:::
 
 ### Event
 

docs/src/components/common-ui/vben-ellipsis-text.md

@@ -0,0 +1,56 @@
+---
+outline: deep
+---
+
+# Vben EllipsisText 省略文本
+
+框架提供的文本展示组件，可配置超长省略、tooltip提示、展开收起等功能。
+
+> 如果文档内没有参数说明，可以尝试在在线示例内寻找
+
+## 基础用法
+
+通过默认插槽设置文本内容，`maxWidth`属性设置最大宽度。
+
+<DemoPreview dir="demos/vben-ellipsis-text/line" />
+
+## 可折叠的文本块
+
+通过`line`设置折叠后的行数，`expand`属性设置是否支持展开收起。
+
+<DemoPreview dir="demos/vben-ellipsis-text/expand" />
+
+## 自定义提示浮层
+
+通过名为`tooltip`的插槽定制提示信息。
+
+<DemoPreview dir="demos/vben-ellipsis-text/tooltip" />
+
+## API
+
+### Props
+
+| 属性名 | 描述 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| 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' }` |
+
+### Events
+
+| 事件名       | 描述         | 类型                       |
+| ------------ | ------------ | -------------------------- |
+| expandChange | 展开状态改变 | `(isExpand:boolean)=>void` |
+
+### Slots
+
+| 插槽名  | 描述                             |
+| ------- | -------------------------------- |
+| tooltip | 启用文本提示时，用来定制提示内容 |

docs/src/components/common-ui/vben-form.md

@@ -87,7 +87,7 @@ import type { BaseFormComponentType } from '@vben/common-ui';
 import type { Component, SetupContext } from 'vue';
 import { h } from 'vue';
 
-import { globalShareState } from '@vben/common-ui';
+import { globalShareState, IconPicker } from '@vben/common-ui';
 import { $t } from '@vben/locales';
 
 import {
@@ -149,6 +149,7 @@ export type ComponentType =
   | 'TimePicker'
   | 'TreeSelect'
   | 'Upload'
+  | 'IconPicker';
   | BaseFormComponentType;
 
 async function initComponentAdapter() {
@@ -166,6 +167,7 @@ async function initComponentAdapter() {
       return h(Button, { ...props, attrs, type: 'default' }, slots);
     },
     Divider,
+    IconPicker,
     Input: withDefaultPlaceholder(Input, 'input'),
     InputNumber: withDefaultPlaceholder(InputNumber, 'input'),
     InputPassword: withDefaultPlaceholder(InputPassword, 'input'),
@@ -280,10 +282,13 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 | 方法名 | 描述 | 类型 |
 | --- | --- | --- |
 | submitForm | 提交表单 | `(e:Event)=>Promise<Record<string,any>>` |
+| validateAndSubmitForm | 提交并校验表单 | `(e:Event)=>Promise<Record<string,any>>` |
 | resetForm | 重置表单 | `()=>Promise<void>` |
 | setValues | 设置表单值, 默认会过滤不在schema中定义的field, 可通过filterFields形参关闭过滤 | `(fields: Record<string, any>, filterFields?: boolean, shouldValidate?: boolean) => Promise<void>` |
 | getValues | 获取表单值 | `(fields:Record<string, any>,shouldValidate: boolean = false)=>Promise<void>` |
 | validate | 表单校验 | `()=>Promise<void>` |
+| validateField | 校验指定字段 | `(fieldName: string)=>Promise<ValidationResult<unknown>>` |
+| isFieldValid | 检查某个字段是否已通过校验 | `(fieldName: string)=>Promise<boolean>` |
 | resetValidate | 重置表单校验 | `()=>Promise<void>` |
 | updateSchema | 更新formSchema | `(schema:FormSchema[])=>void` |
 | setFieldValue | 设置字段值 | `(field: string, value: any, shouldValidate?: boolean)=>Promise<void>` |
@@ -303,15 +308,19 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 | actionWrapperClass | 表单操作区域class | `any` | - |
 | handleReset | 表单重置回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
 | handleSubmit | 表单提交回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
+| handleValuesChange | 表单值变化回调 | `(values: Record<string, any>,) => void` | - |
+| actionButtonsReverse | 调换操作按钮位置 | `boolean` | `false` |
 | resetButtonOptions | 重置按钮组件参数 | `ActionButtonOptions` | - |
 | submitButtonOptions | 提交按钮组件参数 | `ActionButtonOptions` | - |
 | showDefaultActions | 是否显示默认操作按钮 | `boolean` | `true` |
-| collapsed | 是否折叠，在`是否展开，在showCollapseButton=true`时生效 | `boolean` | `false` |
+| collapsed | 是否折叠，在`showCollapseButton`为`true`时生效 | `boolean` | `false` |
 | collapseTriggerResize | 折叠时，触发`resize`事件 | `boolean` | `false` |
 | collapsedRows | 折叠时保持的行数 | `number` | `1` |
+| fieldMappingTime | 用于将表单内时间区域组件的数组值映射成 2 个字段 | `[string, [string, string], string?][]` | - |
 | commonConfig | 表单项的通用配置，每个配置都会传递到每个表单项，表单项可覆盖 | `FormCommonConfig` | - |
-| schema | 表单项的每一项配置 | `FormSchema` | - |
+| schema | 表单项的每一项配置 | `FormSchema[]` | - |
 | submitOnEnter | 按下回车健时提交表单 | `boolean` | false |
+| submitOnChange | 字段值改变时提交表单(内部防抖，这个属性一般用于表格的搜索表单) | `boolean` | false |
 
 ### TS 类型说明
 
@@ -320,7 +329,7 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 ```ts
 export interface ActionButtonOptions {
   /** 样式 */
-  class?: any;
+  class?: ClassType;
   /** 是否禁用 */
   disabled?: boolean;
   /** 是否加载中 */
@@ -348,10 +357,21 @@ export interface FormCommonConfig {
    * 所有表单项的props
    */
   componentProps?: ComponentProps;
+  /**
+   * 是否紧凑模式(移除表单底部为显示校验错误信息所预留的空间)。
+   * 在有设置校验规则的场景下，建议不要将其设置为true
+   * 默认为false。但用作表格的搜索表单时，默认为true
+   * @default false
+   */
+  compact?: boolean;
   /**
    * 所有表单项的控件样式
    */
   controlClass?: string;
+  /**
+   * 在表单项的Label后显示一个冒号
+   */
+  colon?: boolean;
   /**
    * 所有表单项的禁用状态
    * @default false
@@ -411,13 +431,13 @@ export interface FormSchema<
   dependencies?: FormItemDependencies;
   /** 描述 */
   description?: string;
-  /** 字段名 */
+  /** 字段名，也作为自定义插槽的名称 */
   fieldName: string;
   /** 帮助信息 */
   help?: string;
   /** 表单项 */
   label?: string;
-  // 自定义组件内部渲染
+  /** 自定义组件内部渲染  */
   renderComponentContent?: RenderComponentContentType;
   /** 字段规则 */
   rules?: FormSchemaRuleType;
@@ -434,7 +454,7 @@ export interface FormSchema<
 
 ```ts
 dependencies: {
-  // 只有当 name 字段的值变化时，才会触发联动
+  // 触发字段。只有这些字段值变动时，联动才会触发
   triggerFields: ['name'],
   // 动态判断当前字段是否需要显示，不显示则直接销毁
   if(values,formApi){},
@@ -455,11 +475,11 @@ dependencies: {
 
 ### 表单校验
 
-表单联动需要通过 schema 内的 `rules` 属性进行配置。
+表单校验需要通过 schema 内的 `rules` 属性进行配置。
 
-rules的值可以是一个字符串，也可以是一个zod的schema。
+rules的值可以是字符串（预定义的校验规则名称），也可以是一个zod的schema。
 
-#### 字符串
+#### 预定义的校验规则
 
 ```ts
 // 表示字段必填，默认会根据适配器的required进行国际化
@@ -485,11 +505,16 @@ import { z } from '#/adapter/form';
   rules: z.string().min(1, { message: '请输入字符串' });
 }
 
-// 可选，并且携带默认值
+// 可选(可以是undefined)，并且携带默认值。注意zod的optional不包括空字符串''
 {
    rules: z.string().default('默认值').optional(),
 }
 
+// 可以是空字符串、undefined或者一个邮箱地址
+{
+  rules: z.union(z.string().email().optional(), z.literal(""))
+}
+
 // 复杂校验
 {
    z.string().min(1, { message: "请输入" })
@@ -498,3 +523,20 @@ import { z } from '#/adapter/form';
             });
 }
 ```
+
+## Slots
+
+可以使用以下插槽在表单中插入自定义的内容
+
+| 插槽名        | 描述               |
+| ------------- | ------------------ |
+| reset-before  | 重置按钮之前的位置 |
+| submit-before | 提交按钮之前的位置 |
+| expand-before | 展开按钮之前的位置 |
+| expand-after  | 展开按钮之后的位置 |
+
+::: tip 字段插槽
+
+除了以上内置插槽之外，`schema`属性中每个字段的`fieldName`都可以作为插槽名称，这些字段插槽的优先级高于`component`定义的组件。也就是说，当提供了与`fieldName`同名的插槽时，这些插槽的内容将会作为这些字段的组件，此时`component`的值将会被忽略。
+
+:::

docs/src/components/common-ui/vben-modal.md

@@ -80,6 +80,7 @@ const [Modal, modalApi] = useVbenModal({
 
 | 属性名 | 描述 | 类型 | 默认值 |
 | --- | --- | --- | --- |
+| appendToMain | 是否挂载到内容区域（默认挂载到body） | `boolean` | `false` |
 | title | 标题 | `string\|slot` | - |
 | titleTooltip | 标题提示信息 | `string\|slot` | - |
 | description | 描述信息 | `string\|slot` | - |
@@ -93,18 +94,26 @@ const [Modal, modalApi] = useVbenModal({
 | modal | 显示遮罩 | `boolean` | `true` |
 | header | 显示header | `boolean` | `true` |
 | footer | 显示footer | `boolean\|slot` | `true` |
+| confirmDisabled | 禁用确认按钮 | `boolean` | `false` |
 | confirmLoading | 确认按钮loading状态 | `boolean` | `false` |
 | closeOnClickModal | 点击遮罩关闭弹窗 | `boolean` | `true` |
 | closeOnPressEscape | esc 关闭弹窗 | `boolean` | `true` |
 | confirmText | 确认按钮文本 | `string\|slot` | `确认` |
 | cancelText | 取消按钮文本 | `string\|slot` | `取消` |
 | showCancelButton | 显示取消按钮 | `boolean` | `true` |
-| showConfirmButton | 显示确认按钮文本 | `boolean` | `true` |
+| showConfirmButton | 显示确认按钮 | `boolean` | `true` |
 | class | modal的class，宽度通过这个配置 | `string` | - |
 | contentClass | modal内容区域的class | `string` | - |
 | footerClass | modal底部区域的class | `string` | - |
 | headerClass | modal顶部区域的class | `string` | - |
 | bordered | 是否显示border | `boolean` | `false` |
+| zIndex | 弹窗的ZIndex层级 | `number` | `1000` |
+
+::: info appendToMain
+
+`appendToMain`可以指定将弹窗挂载到内容区域，打开这种弹窗时，内容区域以外的部分（标签栏、导航菜单等等）不会被遮挡。默认情况下，弹窗会挂载到body上。但是：挂载到内容区域时，作为页面根容器的`Page`组件，需要设置`auto-content-height`属性，以便弹窗能够正确计算高度。
+
+:::
 
 ### Event
 

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

@@ -4,4 +4,239 @@ outline: deep
 
 # Vben Vxe Table 表格
 
-文档待补充，如果需要使用，可先行查看 vxe-table 文档和 示例代码，内部有部分注释。
+框架提供的Table 列表组件基于 [vxe-table](https://vxetable.cn/v4/#/grid/api?apiKey=grid)，结合`Vben Form 表单`进行了二次封装。
+
+其中，表头的 **表单搜索** 部分采用了`Vben Form表单`，表格主体部分使用了`vxe-grid`组件，支持表格的分页、排序、筛选等功能。
+
+> 如果文档内没有参数说明，可以尝试在在线示例或者在 [vxe-grid 官方API 文档](https://vxetable.cn/v4/#/grid/api?apiKey=grid) 内寻找
+
+::: info 写在前面
+
+如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，大可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。
+
+:::
+
+## 适配器
+
+表格底层使用 [vxe-table](https://vxetable.cn/#/start/install) 进行实现，所以你可以使用 `vxe-table` 的所有功能。对于不同的 UI 框架，我们提供了适配器，以便更好的适配不同的 UI 框架。
+
+### 适配器说明
+
+每个应用都可以自己配置`vxe-table`的适配器，你可以根据自己的需求。下面是一个简单的配置示例：
+
+::: details vxe-table 表格适配器
+
+```ts
+import { h } from 'vue';
+
+import { setupVbenVxeTable, useVbenVxeGrid } from '@vben/plugins/vxe-table';
+
+import { Button, Image } from 'ant-design-vue';
+
+import { useVbenForm } from './form';
+
+setupVbenVxeTable({
+  configVxeTable: (vxeUI) => {
+    vxeUI.setConfig({
+      grid: {
+        align: 'center',
+        border: false,
+        columnConfig: {
+          resizable: true,
+        },
+        minHeight: 180,
+        formConfig: {
+          // 全局禁用vxe-table的表单配置，使用formOptions
+          enabled: false,
+        },
+        proxyConfig: {
+          autoLoad: true,
+          response: {
+            result: 'items',
+            total: 'total',
+            list: 'items',
+          },
+          showActiveMsg: true,
+          showResponseMsg: false,
+        },
+        round: true,
+        showOverflow: true,
+        size: 'small',
+      },
+    });
+
+    // 表格配置项可以用 cellRender: { name: 'CellImage' },
+    vxeUI.renderer.add('CellImage', {
+      renderTableDefault(_renderOpts, params) {
+        const { column, row } = params;
+        return h(Image, { src: row[column.field] });
+      },
+    });
+
+    // 表格配置项可以用 cellRender: { name: 'CellLink' },
+    vxeUI.renderer.add('CellLink', {
+      renderTableDefault(renderOpts) {
+        const { props } = renderOpts;
+        return h(
+          Button,
+          { size: 'small', type: 'link' },
+          { default: () => props?.text },
+        );
+      },
+    });
+
+    // 这里可以自行扩展 vxe-table 的全局配置，比如自定义格式化
+    // vxeUI.formats.add
+  },
+  useVbenForm,
+});
+
+export { useVbenVxeGrid };
+
+export type * from '@vben/plugins/vxe-table';
+```
+
+:::
+
+## 基础表格
+
+使用 `useVbenVxeGrid` 创建最基础的表格。
+
+<DemoPreview dir="demos/vben-vxe-table/basic" />
+
+## 远程加载
+
+通过指定 `proxyConfig.ajax` 的 `query` 方法，可以实现远程加载数据。
+
+<DemoPreview dir="demos/vben-vxe-table/remote" />
+
+## 树形表格
+
+树形表格的数据源为扁平结构，可以指定`treeConfig`配置项，实现树形表格。
+
+```typescript
+treeConfig: {
+  transform: true, // 指定表格为树形表格
+  parentField: 'parentId', // 父节点字段名
+  rowField: 'id', // 行数据字段名
+},
+```
+
+<DemoPreview dir="demos/vben-vxe-table/tree" />
+
+## 固定表头/列
+
+列固定可选参数： `'left' | 'right' | '' | null`
+
+<DemoPreview dir="demos/vben-vxe-table/fixed" />
+
+## 自定义单元格
+
+自定义单元格有两种实现方式
+
+- 通过 `slots` 插槽
+- 通过 `customCell` 自定义单元格，但是要先添加渲染器
+
+```typescript
+// 表格配置项可以用 cellRender: { name: 'CellImage' },
+vxeUI.renderer.add('CellImage', {
+  renderDefault(_renderOpts, params) {
+    const { column, row } = params;
+    return h(Image, { src: row[column.field] } as any); // 注意此处的Image 组件，来源于Antd，需要自行引入,否则会使用js的Image类
+  },
+});
+
+// 表格配置项可以用 cellRender: { name: 'CellLink' },
+vxeUI.renderer.add('CellLink', {
+  renderDefault(renderOpts) {
+    const { props } = renderOpts;
+    return h(
+      Button,
+      { size: 'small', type: 'link' },
+      { default: () => props?.text },
+    );
+  },
+});
+```
+
+<DemoPreview dir="demos/vben-vxe-table/custom-cell" />
+
+## 搜索表单
+
+**表单搜索** 部分采用了`Vben Form 表单`，参考 [Vben Form 表单文档](/components/common-ui/vben-form)。
+
+当启用了表单搜索时，可以在toolbarConfig中配置`search`为`true`来让表格在工具栏区域显示一个搜索表单控制按钮。
+
+<DemoPreview dir="demos/vben-vxe-table/form" />
+
+## 单元格编辑
+
+通过指定`editConfig.mode`为`cell`，可以实现单元格编辑。
+
+<DemoPreview dir="demos/vben-vxe-table/edit-cell" />
+
+## 行编辑
+
+通过指定`editConfig.mode`为`row`，可以实现行编辑。
+
+<DemoPreview dir="demos/vben-vxe-table/edit-row" />
+
+## 虚拟滚动
+
+通过 scroll-y.enabled 与 scroll-y.gt 组合开启，其中 enabled 为总开关，gt 是指当总行数大于指定行数时自动开启。
+
+> 参考 [vxe-table 官方文档 - 虚拟滚动](https://vxetable.cn/v4/#/component/grid/scroll/vertical)。
+
+<DemoPreview dir="demos/vben-vxe-table/virtual" />
+
+## API
+
+`useVbenVxeGrid` 返回一个数组，第一个元素是表格组件，第二个元素是表格的方法。
+
+```vue
+<script setup lang="ts">
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+// Grid 为表格组件
+// gridApi 为表格的方法
+const [Grid, gridApi] = useVbenVxeGrid({
+  gridOptions: {},
+  formOptions: {},
+  gridEvents: {},
+  // 属性
+  // 事件
+});
+</script>
+
+<template>
+  <Grid />
+</template>
+```
+
+### GridApi
+
+useVbenVxeGrid 返回的第二个参数，是一个对象，包含了一些表单的方法。
+
+| 方法名 | 描述 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| setLoading | 设置loading状态 | `(loading)=>void` | - |
+| setGridOptions | 设置vxe-table grid组件参数 | `(options: Partial<VxeGridProps['gridOptions'])=>void` | - |
+| reload | 重载表格，会进行初始化 | `(params:any)=>void` | - |
+| query | 重载表格，会保留当前分页 | `(params:any)=>void` | - |
+| grid | vxe-table grid实例 | `VxeGridInstance` | - |
+| formApi | vbenForm api实例 | `FormApi` | - |
+| toggleSearchForm | 设置搜索表单显示状态 | `(show?: boolean)=>boolean` | 当省略参数时，则将表单在显示和隐藏两种状态之间切换 |
+
+## Props
+
+所有属性都可以传入 `useVbenVxeGrid` 的第一个参数中。
+
+| 属性名         | 描述               | 类型                |
+| -------------- | ------------------ | ------------------- |
+| tableTitle     | 表格标题           | `string`            |
+| tableTitleHelp | 表格标题帮助信息   | `string`            |
+| gridClass      | grid组件的class    | `string`            |
+| gridOptions    | grid组件的参数     | `VxeTableGridProps` |
+| gridEvents     | grid组件的触发的⌚️ | `VxeGridListeners`  |
+| formOptions    | 表单参数           | `VbenFormProps`     |
+| showSearchForm | 是否显示搜索表单   | `boolean`           |

docs/src/components/introduction.md

@@ -6,6 +6,10 @@
 
 :::
 
+## 布局组件
+
+布局组件一般在页面内容区域用作顶层容器组件，提供一些统一的布局样式和基本功能。
+
 ## 通用组件
 
 通用组件是一些常用的组件，比如弹窗、抽屉、表单等。大部分基于 `Tailwind CSS` 实现，可适用于不同 UI 组件库的应用。

docs/src/components/layout-ui/page.md

@@ -0,0 +1,44 @@
+---
+outline: deep
+---
+
+# Page 常规页面组件
+
+提供一个常规页面布局的组件，包括头部、内容区域、底部三个部分。
+
+::: info 写在前面
+
+本组件是一个基本布局组件。如果有更多的通用页面布局需求（比如双列布局等），可以根据实际需求自行封装。
+
+:::
+
+## 基础用法
+
+将`Page`作为你的业务页面的根组件即可。
+
+### Props
+
+| 属性名 | 描述 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| title | 页面标题 | `string\|slot` | - | - |
+| description | 页面描述（标题下的内容） | `string\|slot` | - | - |
+| contentClass | 内容区域的class | `string` | - | - |
+| headerClass | 头部区域的class | `string` | - | - |
+| footerClass | 底部区域的class | `string` | - | - |
+| autoContentHeight | 自动调整内容区域的高度 | `boolean` | `false` | - |
+
+::: tip 注意
+
+如果`title`、`description`、`extra`三者均未提供有效内容（通过`props`或者`slots`均可），则页面头部区域不会渲染。
+
+:::
+
+### Slots
+
+| 插槽名称    | 描述         |
+| ----------- | ------------ |
+| default     | 页面内容     |
+| title       | 页面标题     |
+| description | 页面描述     |
+| extra       | 页面头部右侧 |
+| footer      | 页面底部     |

docs/src/demos/vben-api-component/cascader/index.vue

@@ -0,0 +1,100 @@
+<script lang="ts" setup>
+import { ApiComponent } from '@vben/common-ui';
+
+import { Cascader } from 'ant-design-vue';
+
+const treeData: Record<string, any> = [
+  {
+    label: '浙江',
+    value: 'zhejiang',
+    children: [
+      {
+        value: 'hangzhou',
+        label: '杭州',
+        children: [
+          {
+            value: 'xihu',
+            label: '西湖',
+          },
+          {
+            value: 'sudi',
+            label: '苏堤',
+          },
+        ],
+      },
+      {
+        value: 'jiaxing',
+        label: '嘉兴',
+        children: [
+          {
+            value: 'wuzhen',
+            label: '乌镇',
+          },
+          {
+            value: 'meihuazhou',
+            label: '梅花洲',
+          },
+        ],
+      },
+      {
+        value: 'zhoushan',
+        label: '舟山',
+        children: [
+          {
+            value: 'putuoshan',
+            label: '普陀山',
+          },
+          {
+            value: 'taohuadao',
+            label: '桃花岛',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    label: '江苏',
+    value: 'jiangsu',
+    children: [
+      {
+        value: 'nanjing',
+        label: '南京',
+        children: [
+          {
+            value: 'zhonghuamen',
+            label: '中华门',
+          },
+          {
+            value: 'zijinshan',
+            label: '紫金山',
+          },
+          {
+            value: 'yuhuatai',
+            label: '雨花台',
+          },
+        ],
+      },
+    ],
+  },
+];
+/**
+ * 模拟请求接口
+ */
+function fetchApi(): Promise<Record<string, any>> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(treeData);
+    }, 1000);
+  });
+}
+</script>
+<template>
+  <ApiComponent
+    :api="fetchApi"
+    :component="Cascader"
+    :immediate="false"
+    children-field="children"
+    loading-slot="suffixIcon"
+    visible-event="onDropdownVisibleChange"
+  />
+</template>

docs/src/demos/vben-ellipsis-text/expand/index.vue

@@ -0,0 +1,10 @@
+<script lang="ts" setup>
+import { EllipsisText } from '@vben/common-ui';
+
+const text = `
+Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。
+`;
+</script>
+<template>
+  <EllipsisText :line="3" expand>{{ text }}</EllipsisText>
+</template>

docs/src/demos/vben-ellipsis-text/line/index.vue

@@ -0,0 +1,10 @@
+<script lang="ts" setup>
+import { EllipsisText } from '@vben/common-ui';
+
+const text = `
+Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。Vben Admin 是一个基于 Vue3.0、Vite、 TypeScript 的后台解决方案，目标是为开发中大型项目提供开箱即用的解决方案。包括二次封装组件、utils、hooks、动态菜单、权限校验、多主题配置、按钮级别权限控制等功能。项目会使用前端较新的技术栈，可以作为项目的启动模版，以帮助你快速搭建企业级中后台产品原型。也可以作为一个示例，用于学习 vue3、vite、ts 等主流技术。该项目会持续跟进最新技术，并将其应用在项目中。
+`;
+</script>
+<template>
+  <EllipsisText :max-width="500">{{ text }}</EllipsisText>
+</template>

docs/src/demos/vben-ellipsis-text/tooltip/index.vue

@@ -0,0 +1,14 @@
+<script lang="ts" setup>
+import { EllipsisText } from '@vben/common-ui';
+</script>
+<template>
+  <EllipsisText :max-width="240">
+    住在我心里孤独的 孤独的海怪 痛苦之王 开始厌倦 深海的光 停滞的海浪
+    <template #tooltip>
+      <div style="text-align: center">
+        《秦皇岛》<br />住在我心里孤独的<br />孤独的海怪 痛苦之王<br />开始厌倦
+        深海的光 停滞的海浪
+      </div>
+    </template>
+  </EllipsisText>
+</template>

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

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

docs/src/demos/vben-vxe-table/custom-cell/index.vue

@@ -0,0 +1,105 @@
+<script lang="ts" setup>
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { Button, Image, Switch, Tag } from 'ant-design-vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { getExampleTableApi } from '../mock-api';
+
+interface RowType {
+  category: string;
+  color: string;
+  id: string;
+  imageUrl: string;
+  open: boolean;
+  price: string;
+  productName: string;
+  releaseDate: string;
+  status: 'error' | 'success' | 'warning';
+}
+
+const gridOptions: VxeGridProps<RowType> = {
+  checkboxConfig: {
+    highlight: true,
+    labelField: 'name',
+  },
+  columns: [
+    { title: '序号', type: 'seq', width: 50 },
+    { field: 'category', title: 'Category', width: 100 },
+    {
+      field: 'imageUrl',
+      slots: { default: 'image-url' },
+      title: 'Image',
+      width: 100,
+    },
+    {
+      cellRender: { name: 'CellImage' },
+      field: 'imageUrl2',
+      title: 'Render Image',
+      width: 130,
+    },
+    {
+      field: 'open',
+      slots: { default: 'open' },
+      title: 'Open',
+      width: 100,
+    },
+    {
+      field: 'status',
+      slots: { default: 'status' },
+      title: 'Status',
+      width: 100,
+    },
+    { field: 'color', title: 'Color', width: 100 },
+    { field: 'productName', title: 'Product Name', width: 200 },
+    { field: 'price', title: 'Price', width: 100 },
+    {
+      field: 'releaseDate',
+      formatter: 'formatDateTime',
+      title: 'Date',
+      width: 200,
+    },
+    {
+      cellRender: { name: 'CellLink', props: { text: '编辑' } },
+      field: 'action',
+      fixed: 'right',
+      title: '操作',
+      width: 120,
+    },
+  ],
+  keepSource: true,
+  pagerConfig: {},
+  proxyConfig: {
+    ajax: {
+      query: async ({ page }) => {
+        return await getExampleTableApi({
+          page: page.currentPage,
+          pageSize: page.pageSize,
+        });
+      },
+    },
+  },
+};
+
+const [Grid] = useVbenVxeGrid({ gridOptions });
+</script>
+
+<template>
+  <div class="vp-raw w-full">
+    <Grid>
+      <template #image-url="{ row }">
+        <Image :src="row.imageUrl" height="30" width="30" />
+      </template>
+      <template #open="{ row }">
+        <Switch v-model:checked="row.open" />
+      </template>
+      <template #status="{ row }">
+        <Tag :color="row.color">{{ row.status }}</Tag>
+      </template>
+      <template #action>
+        <Button type="link">编辑</Button>
+      </template>
+    </Grid>
+  </div>
+</template>

docs/src/demos/vben-vxe-table/edit-cell/index.vue

@@ -0,0 +1,55 @@
+<script lang="ts" setup>
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { getExampleTableApi } from '../mock-api';
+
+interface RowType {
+  category: string;
+  color: string;
+  id: string;
+  price: string;
+  productName: string;
+  releaseDate: string;
+}
+
+const gridOptions: VxeGridProps<RowType> = {
+  columns: [
+    { title: '序号', type: 'seq', width: 50 },
+    { editRender: { name: 'input' }, field: 'category', title: 'Category' },
+    { editRender: { name: 'input' }, field: 'color', title: 'Color' },
+    {
+      editRender: { name: 'input' },
+      field: 'productName',
+      title: 'Product Name',
+    },
+    { field: 'price', title: 'Price' },
+    { field: 'releaseDate', formatter: 'formatDateTime', title: 'Date' },
+  ],
+  editConfig: {
+    mode: 'cell',
+    trigger: 'click',
+  },
+  pagerConfig: {},
+  proxyConfig: {
+    ajax: {
+      query: async ({ page }) => {
+        return await getExampleTableApi({
+          page: page.currentPage,
+          pageSize: page.pageSize,
+        });
+      },
+    },
+  },
+  showOverflow: true,
+};
+
+const [Grid] = useVbenVxeGrid({ gridOptions });
+</script>
+
+<template>
+  <div class="vp-raw w-full">
+    <Grid />
+  </div>
+</template>

docs/src/demos/vben-vxe-table/edit-row/index.vue

@@ -0,0 +1,92 @@
+<script lang="ts" setup>
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { Button, message } from 'ant-design-vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { getExampleTableApi } from '../mock-api';
+
+interface RowType {
+  category: string;
+  color: string;
+  id: string;
+  price: string;
+  productName: string;
+  releaseDate: string;
+}
+
+const gridOptions: VxeGridProps<RowType> = {
+  columns: [
+    { title: '序号', type: 'seq', width: 50 },
+    { editRender: { name: 'input' }, field: 'category', title: 'Category' },
+    { editRender: { name: 'input' }, field: 'color', title: 'Color' },
+    {
+      editRender: { name: 'input' },
+      field: 'productName',
+      title: 'Product Name',
+    },
+    { field: 'price', title: 'Price' },
+    { field: 'releaseDate', formatter: 'formatDateTime', title: 'Date' },
+    { slots: { default: 'action' }, title: '操作' },
+  ],
+  editConfig: {
+    mode: 'row',
+    trigger: 'click',
+  },
+  pagerConfig: {},
+  proxyConfig: {
+    ajax: {
+      query: async ({ page }) => {
+        return await getExampleTableApi({
+          page: page.currentPage,
+          pageSize: page.pageSize,
+        });
+      },
+    },
+  },
+  showOverflow: true,
+};
+
+const [Grid, gridApi] = useVbenVxeGrid({ gridOptions });
+
+function hasEditStatus(row: RowType) {
+  return gridApi.grid?.isEditByRow(row);
+}
+
+function editRowEvent(row: RowType) {
+  gridApi.grid?.setEditRow(row);
+}
+
+async function saveRowEvent(row: RowType) {
+  await gridApi.grid?.clearEdit();
+
+  gridApi.setLoading(true);
+  setTimeout(() => {
+    gridApi.setLoading(false);
+    message.success({
+      content: `保存成功！category=${row.category}`,
+    });
+  }, 600);
+}
+
+const cancelRowEvent = (_row: RowType) => {
+  gridApi.grid?.clearEdit();
+};
+</script>
+
+<template>
+  <div class="vp-raw w-full">
+    <Grid>
+      <template #action="{ row }">
+        <template v-if="hasEditStatus(row)">
+          <Button type="link" @click="saveRowEvent(row)">保存</Button>
+          <Button type="link" @click="cancelRowEvent(row)">取消</Button>
+        </template>
+        <template v-else>
+          <Button type="link" @click="editRowEvent(row)">编辑</Button>
+        </template>
+      </template>
+    </Grid>
+  </div>
+</template>

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

@@ -0,0 +1,67 @@
+<script lang="ts" setup>
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { Button } from 'ant-design-vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { getExampleTableApi } from '../mock-api';
+
+interface RowType {
+  category: string;
+  color: string;
+  id: string;
+  price: string;
+  productName: string;
+  releaseDate: string;
+}
+
+const gridOptions: VxeGridProps<RowType> = {
+  columns: [
+    { fixed: 'left', title: '序号', type: 'seq', width: 50 },
+    { field: 'category', title: 'Category', width: 300 },
+    { field: 'color', title: 'Color', width: 300 },
+    { field: 'productName', title: 'Product Name', width: 300 },
+    { field: 'price', title: 'Price', width: 300 },
+    {
+      field: 'releaseDate',
+      formatter: 'formatDateTime',
+      title: 'DateTime',
+      width: 500,
+    },
+    {
+      field: 'action',
+      fixed: 'right',
+      slots: { default: 'action' },
+      title: '操作',
+      width: 120,
+    },
+  ],
+  pagerConfig: {},
+  proxyConfig: {
+    ajax: {
+      query: async ({ page }) => {
+        return await getExampleTableApi({
+          page: page.currentPage,
+          pageSize: page.pageSize,
+        });
+      },
+    },
+  },
+  rowConfig: {
+    isHover: true,
+  },
+};
+
+const [Grid] = useVbenVxeGrid({ gridOptions });
+</script>
+
+<template>
+  <div class="vp-raw w-full">
+    <Grid>
+      <template #action>
+        <Button type="link">编辑</Button>
+      </template>
+    </Grid>
+  </div>
+</template>

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

@@ -0,0 +1,127 @@
+<script lang="ts" setup>
+import type { VbenFormProps } from '#/adapter/form';
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { message } from 'ant-design-vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { getExampleTableApi } from '../mock-api';
+
+interface RowType {
+  category: string;
+  color: string;
+  id: string;
+  price: string;
+  productName: string;
+  releaseDate: string;
+}
+
+const formOptions: VbenFormProps = {
+  // 默认展开
+  collapsed: false,
+  schema: [
+    {
+      component: 'Input',
+      componentProps: {
+        placeholder: 'Please enter category',
+      },
+      defaultValue: '1',
+      fieldName: 'category',
+      label: 'Category',
+    },
+    {
+      component: 'Input',
+      componentProps: {
+        placeholder: 'Please enter productName',
+      },
+      fieldName: 'productName',
+      label: 'ProductName',
+    },
+    {
+      component: 'Input',
+      componentProps: {
+        placeholder: 'Please enter price',
+      },
+      fieldName: 'price',
+      label: 'Price',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        allowClear: true,
+        options: [
+          {
+            label: 'Color1',
+            value: '1',
+          },
+          {
+            label: 'Color2',
+            value: '2',
+          },
+        ],
+        placeholder: '请选择',
+      },
+      fieldName: 'color',
+      label: 'Color',
+    },
+    {
+      component: 'DatePicker',
+      fieldName: 'datePicker',
+      label: 'Date',
+    },
+  ],
+  // 控制表单是否显示折叠按钮
+  showCollapseButton: true,
+  submitButtonOptions: {
+    content: '查询',
+  },
+  // 是否在字段值改变时提交表单
+  submitOnChange: false,
+  // 按下回车时是否提交表单
+  submitOnEnter: false,
+};
+
+const gridOptions: VxeGridProps<RowType> = {
+  checkboxConfig: {
+    highlight: true,
+    labelField: 'name',
+  },
+  columns: [
+    { title: '序号', type: 'seq', width: 50 },
+    { align: 'left', title: 'Name', type: 'checkbox', width: 100 },
+    { field: 'category', title: 'Category' },
+    { field: 'color', title: 'Color' },
+    { field: 'productName', title: 'Product Name' },
+    { field: 'price', title: 'Price' },
+    { field: 'releaseDate', formatter: 'formatDateTime', title: 'Date' },
+  ],
+  keepSource: true,
+  pagerConfig: {},
+  proxyConfig: {
+    ajax: {
+      query: async ({ page }, formValues) => {
+        message.success(`Query params: ${JSON.stringify(formValues)}`);
+        return await getExampleTableApi({
+          page: page.currentPage,
+          pageSize: page.pageSize,
+          ...formValues,
+        });
+      },
+    },
+  },
+  toolbarConfig: {
+    // 是否显示搜索表单控制按钮
+    // @ts-ignore 正式环境时有完整的类型声明
+    search: true,
+  },
+};
+
+const [Grid] = useVbenVxeGrid({ formOptions, gridOptions });
+</script>
+
+<template>
+  <div class="vp-raw w-full">
+    <Grid />
+  </div>
+</template>

docs/src/demos/vben-vxe-table/mock-api.ts

@@ -0,0 +1,36 @@
+import { MOCK_API_DATA } from './table-data';
+
+export namespace DemoTableApi {
+  export interface PageFetchParams {
+    [key: string]: any;
+    page: number;
+    pageSize: number;
+  }
+}
+
+export function sleep(time = 1000) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(true);
+    }, time);
+  });
+}
+
+/**
+ * 获取示例表格数据
+ */
+async function getExampleTableApi(params: DemoTableApi.PageFetchParams) {
+  return new Promise<{ items: any; total: number }>((resolve) => {
+    const { page, pageSize } = params;
+    const items = MOCK_API_DATA.slice((page - 1) * pageSize, page * pageSize);
+
+    sleep(1000).then(() => {
+      resolve({
+        total: items.length,
+        items,
+      });
+    });
+  });
+}
+
+export { getExampleTableApi };

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

@@ -0,0 +1,112 @@
+<script lang="ts" setup>
+import type { DemoTableApi } from '../mock-api';
+
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { Button } from 'ant-design-vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { MOCK_API_DATA } from '../table-data';
+
+interface RowType {
+  category: string;
+  color: string;
+  id: string;
+  price: string;
+  productName: string;
+  releaseDate: string;
+}
+
+// 数据实例
+// const MOCK_TREE_TABLE_DATA = [
+//   {
+//     date: '2020-08-01',
+//     id: 10_000,
+//     name: 'Test1',
+//     parentId: null,
+//     size: 1024,
+//     type: 'mp3',
+//   },
+// ]
+
+const sleep = (time = 1000) => {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(true);
+    }, time);
+  });
+};
+
+/**
+ * 获取示例表格数据
+ */
+async function getExampleTableApi(params: DemoTableApi.PageFetchParams) {
+  return new Promise<{ items: any; total: number }>((resolve) => {
+    const { page, pageSize } = params;
+    const items = MOCK_API_DATA.slice((page - 1) * pageSize, page * pageSize);
+
+    sleep(1000).then(() => {
+      resolve({
+        total: items.length,
+        items,
+      });
+    });
+  });
+}
+
+const gridOptions: VxeGridProps<RowType> = {
+  checkboxConfig: {
+    highlight: true,
+    labelField: 'name',
+  },
+  columns: [
+    { title: '序号', type: 'seq', width: 50 },
+    { align: 'left', title: 'Name', type: 'checkbox', width: 100 },
+    { field: 'category', title: 'Category' },
+    { field: 'color', title: 'Color' },
+    { field: 'productName', title: 'Product Name' },
+    { field: 'price', title: 'Price' },
+    { field: 'releaseDate', formatter: 'formatDateTime', title: 'DateTime' },
+  ],
+  exportConfig: {},
+  // height: 'auto', // 如果设置为 auto，则必须确保存在父节点且不允许存在相邻元素，否则会出现高度闪动问题
+  keepSource: true,
+  proxyConfig: {
+    ajax: {
+      query: async ({ page }) => {
+        return await getExampleTableApi({
+          page: page.currentPage,
+          pageSize: page.pageSize,
+        });
+      },
+    },
+  },
+  toolbarConfig: {
+    custom: true,
+    export: true,
+    // import: true,
+    refresh: true,
+    zoom: true,
+  },
+};
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  gridOptions,
+});
+</script>
+
+<template>
+  <div class="vp-raw w-full">
+    <Grid>
+      <template #toolbar-tools>
+        <Button class="mr-2" type="primary" @click="() => gridApi.query()">
+          刷新当前页面
+        </Button>
+        <Button type="primary" @click="() => gridApi.reload()">
+          刷新并返回第一页
+        </Button>
+      </template>
+    </Grid>
+  </div>
+</template>

docs/src/demos/vben-vxe-table/table-data.ts

@@ -0,0 +1,384 @@
+interface TableRowData {
+  address: string;
+  age: number;
+  id: number;
+  name: string;
+  nickname: string;
+  role: string;
+}
+
+const roles = ['User', 'Admin', 'Manager', 'Guest'];
+
+export const MOCK_TABLE_DATA: TableRowData[] = (() => {
+  const data: TableRowData[] = [];
+  for (let i = 0; i < 10; i++) {
+    data.push({
+      address: `New York${i}`,
+      age: i + 1,
+      id: i,
+      name: `Test${i}`,
+      nickname: `Test${i}`,
+      role: roles[Math.floor(Math.random() * roles.length)] as string,
+    });
+  }
+  return data;
+})();
+
+export const MOCK_TREE_TABLE_DATA = [
+  {
+    date: '2020-08-01',
+    id: 10_000,
+    name: 'Test1',
+    parentId: null,
+    size: 1024,
+    type: 'mp3',
+  },
+  {
+    date: '2021-04-01',
+    id: 10_050,
+    name: 'Test2',
+    parentId: null,
+    size: 0,
+    type: 'mp4',
+  },
+  {
+    date: '2020-03-01',
+    id: 24_300,
+    name: 'Test3',
+    parentId: 10_050,
+    size: 1024,
+    type: 'avi',
+  },
+  {
+    date: '2021-04-01',
+    id: 20_045,
+    name: 'Test4',
+    parentId: 24_300,
+    size: 600,
+    type: 'html',
+  },
+  {
+    date: '2021-04-01',
+    id: 10_053,
+    name: 'Test5',
+    parentId: 24_300,
+    size: 0,
+    type: 'avi',
+  },
+  {
+    date: '2021-10-01',
+    id: 24_330,
+    name: 'Test6',
+    parentId: 10_053,
+    size: 25,
+    type: 'txt',
+  },
+  {
+    date: '2020-01-01',
+    id: 21_011,
+    name: 'Test7',
+    parentId: 10_053,
+    size: 512,
+    type: 'pdf',
+  },
+  {
+    date: '2021-06-01',
+    id: 22_200,
+    name: 'Test8',
+    parentId: 10_053,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2020-11-01',
+    id: 23_666,
+    name: 'Test9',
+    parentId: null,
+    size: 2048,
+    type: 'xlsx',
+  },
+  {
+    date: '2021-06-01',
+    id: 23_677,
+    name: 'Test10',
+    parentId: 23_666,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2021-06-01',
+    id: 23_671,
+    name: 'Test11',
+    parentId: 23_677,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2021-06-01',
+    id: 23_672,
+    name: 'Test12',
+    parentId: 23_677,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2021-06-01',
+    id: 23_688,
+    name: 'Test13',
+    parentId: 23_666,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2021-06-01',
+    id: 23_681,
+    name: 'Test14',
+    parentId: 23_688,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2021-06-01',
+    id: 23_682,
+    name: 'Test15',
+    parentId: 23_688,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2020-10-01',
+    id: 24_555,
+    name: 'Test16',
+    parentId: null,
+    size: 224,
+    type: 'avi',
+  },
+  {
+    date: '2021-06-01',
+    id: 24_566,
+    name: 'Test17',
+    parentId: 24_555,
+    size: 1024,
+    type: 'js',
+  },
+  {
+    date: '2021-06-01',
+    id: 24_577,
+    name: 'Test18',
+    parentId: 24_555,
+    size: 1024,
+    type: 'js',
+  },
+];
+
+export const MOCK_API_DATA = [
+  {
+    available: true,
+    category: 'Computers',
+    color: 'purple',
+    currency: 'NAD',
+    description:
+      'Ergonomic executive chair upholstered in bonded black leather and PVC padded seat and back for all-day comfort and support',
+    id: '45a613df-227a-4907-a89f-4a7f1252ca0c',
+    imageUrl: 'https://avatars.githubusercontent.com/u/62715097',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/75395683',
+    inProduction: false,
+    open: true,
+    price: '48.89',
+    productName: 'Handcrafted Steel Salad',
+    quantity: 70,
+    rating: 3.780_582_329_574_367,
+    releaseDate: '2024-09-09T04:06:57.793Z',
+    status: 'error',
+    tags: ['Bespoke', 'Handmade', 'Luxurious'],
+    weight: 1.031_015_671_912_002_5,
+  },
+  {
+    available: true,
+    category: 'Toys',
+    color: 'green',
+    currency: 'CZK',
+    description:
+      'The Nagasaki Lander is the trademarked name of several series of Nagasaki sport bikes, that started with the 1984 ABC800J',
+    id: 'd02e5ee9-bc98-4de2-98fa-25a6567ecc19',
+    imageUrl: 'https://avatars.githubusercontent.com/u/51512330',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/58698113',
+    inProduction: false,
+    open: false,
+    price: '68.15',
+    productName: 'Generic Cotton Gloves',
+    quantity: 3,
+    rating: 1.681_749_367_682_703_3,
+    releaseDate: '2024-06-16T09:00:36.806Z',
+    status: 'warning',
+    tags: ['Rustic', 'Handcrafted', 'Recycled'],
+    weight: 9.601_076_149_300_575,
+  },
+  {
+    available: true,
+    category: 'Beauty',
+    color: 'teal',
+    currency: 'OMR',
+    description:
+      'The Apollotech B340 is an affordable wireless mouse with reliable connectivity, 12 months battery life and modern design',
+    id: '2b72521c-225c-4e64-8030-611b76b10b37',
+    imageUrl: 'https://avatars.githubusercontent.com/u/50300075',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/36541691',
+    inProduction: true,
+    open: true,
+    price: '696.94',
+    productName: 'Gorgeous Soft Ball',
+    quantity: 50,
+    rating: 2.361_581_777_372_057_5,
+    releaseDate: '2024-06-03T13:24:19.809Z',
+    status: 'warning',
+    tags: ['Gorgeous', 'Ergonomic', 'Licensed'],
+    weight: 8.882_340_049_286_19,
+  },
+  {
+    available: true,
+    category: 'Games',
+    color: 'silver',
+    currency: 'SOS',
+    description:
+      'Carbonite web goalkeeper gloves are ergonomically designed to give easy fit',
+    id: 'bafab694-3801-452c-b102-9eb519bd1143',
+    imageUrl: 'https://avatars.githubusercontent.com/u/89827115',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/55952747',
+    inProduction: false,
+    open: false,
+    price: '553.84',
+    productName: 'Bespoke Soft Computer',
+    quantity: 29,
+    rating: 2.176_412_873_760_271_7,
+    releaseDate: '2024-09-17T12:16:27.034Z',
+    status: 'error',
+    tags: ['Elegant', 'Rustic', 'Recycled'],
+    weight: 9.653_285_869_978_038,
+  },
+  {
+    available: true,
+    category: 'Toys',
+    color: 'indigo',
+    currency: 'BIF',
+    description:
+      'Andy shoes are designed to keeping in mind durability as well as trends, the most stylish range of shoes & sandals',
+    id: 'bf6dea6b-2a55-441d-8773-937e03d99389',
+    imageUrl: 'https://avatars.githubusercontent.com/u/21431092',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/3771350',
+    inProduction: true,
+    open: true,
+    price: '237.39',
+    productName: 'Handcrafted Cotton Mouse',
+    quantity: 54,
+    rating: 4.363_265_388_265_461,
+    releaseDate: '2023-10-23T13:42:34.947Z',
+    status: 'error',
+    tags: ['Unbranded', 'Handmade', 'Generic'],
+    weight: 9.513_203_612_535_571,
+  },
+  {
+    available: false,
+    category: 'Tools',
+    color: 'violet',
+    currency: 'TZS',
+    description:
+      'New ABC 13 9370, 13.3, 5th Gen CoreA5-8250U, 8GB RAM, 256GB SSD, power UHD Graphics, OS 10 Home, OS Office A & J 2016',
+    id: '135ba6ab-32ee-4989-8189-5cfa658ef970',
+    imageUrl: 'https://avatars.githubusercontent.com/u/29946092',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/23842994',
+    inProduction: false,
+    open: false,
+    price: '825.25',
+    productName: 'Awesome Bronze Ball',
+    quantity: 94,
+    rating: 4.251_159_804_726_753,
+    releaseDate: '2023-12-30T07:31:43.464Z',
+    status: 'warning',
+    tags: ['Handmade', 'Elegant', 'Unbranded'],
+    weight: 2.247_473_385_732_636_8,
+  },
+  {
+    available: true,
+    category: 'Automotive',
+    color: 'teal',
+    currency: 'BOB',
+    description: 'The Football Is Good For Training And Recreational Purposes',
+    id: '652ef256-7d4e-48b7-976c-7afaa781ea92',
+    imageUrl: 'https://avatars.githubusercontent.com/u/2531904',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/15215990',
+    inProduction: false,
+    open: false,
+    price: '780.49',
+    productName: 'Oriental Rubber Pants',
+    quantity: 70,
+    rating: 2.636_323_417_377_916,
+    releaseDate: '2024-02-23T23:30:49.628Z',
+    status: 'success',
+    tags: ['Unbranded', 'Elegant', 'Unbranded'],
+    weight: 4.812_965_858_018_838,
+  },
+  {
+    available: false,
+    category: 'Garden',
+    color: 'plum',
+    currency: 'LRD',
+    description:
+      'The slim & simple Maple Gaming Keyboard from Dev Byte comes with a sleek body and 7- Color RGB LED Back-lighting for smart functionality',
+    id: '3ea24798-6589-40cc-85f0-ab78752244a0',
+    imageUrl: 'https://avatars.githubusercontent.com/u/23165285',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/14595665',
+    inProduction: false,
+    open: true,
+    price: '583.85',
+    productName: 'Handcrafted Concrete Hat',
+    quantity: 15,
+    rating: 1.371_600_527_752_802_7,
+    releaseDate: '2024-03-02T19:40:50.255Z',
+    status: 'error',
+    tags: ['Rustic', 'Sleek', 'Ergonomic'],
+    weight: 4.926_949_366_405_728_4,
+  },
+  {
+    available: false,
+    category: 'Industrial',
+    color: 'salmon',
+    currency: 'AUD',
+    description:
+      'The Apollotech B340 is an affordable wireless mouse with reliable connectivity, 12 months battery life and modern design',
+    id: '997113dd-f6e4-4acc-9790-ef554c7498d1',
+    imageUrl: 'https://avatars.githubusercontent.com/u/49021914',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/4690621',
+    inProduction: true,
+    open: false,
+    price: '67.99',
+    productName: 'Generic Rubber Bacon',
+    quantity: 68,
+    rating: 4.129_840_682_128_08,
+    releaseDate: '2023-12-17T01:40:25.415Z',
+    status: 'error',
+    tags: ['Oriental', 'Small', 'Handcrafted'],
+    weight: 1.080_114_331_801_906_4,
+  },
+  {
+    available: false,
+    category: 'Tools',
+    color: 'sky blue',
+    currency: 'NOK',
+    description:
+      'The Nagasaki Lander is the trademarked name of several series of Nagasaki sport bikes, that started with the 1984 ABC800J',
+    id: 'f697a250-6cb2-46c8-b0f7-871ab1f2fa8d',
+    imageUrl: 'https://avatars.githubusercontent.com/u/95928385',
+    imageUrl2: 'https://avatars.githubusercontent.com/u/47588244',
+    inProduction: false,
+    open: false,
+    price: '613.89',
+    productName: 'Gorgeous Frozen Ball',
+    quantity: 55,
+    rating: 1.646_947_205_998_534_6,
+    releaseDate: '2024-10-13T12:31:04.929Z',
+    status: 'warning',
+    tags: ['Handmade', 'Unbranded', 'Unbranded'],
+    weight: 9.430_690_557_758_114,
+  },
+];

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

@@ -0,0 +1,80 @@
+<script lang="ts" setup>
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { Button } from 'ant-design-vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+import { MOCK_TREE_TABLE_DATA } from '../table-data';
+
+interface RowType {
+  date: string;
+  id: number;
+  name: string;
+  parentId: null | number;
+  size: number;
+  type: string;
+}
+
+// 数据实例
+// const MOCK_TREE_TABLE_DATA = [
+//   {
+//     date: '2020-08-01',
+//     id: 10_000,
+//     name: 'Test1',
+//     parentId: null,
+//     size: 1024,
+//     type: 'mp3',
+//   },
+//   {
+//     date: '2021-04-01',
+//     id: 10_050,
+//     name: 'Test2',
+//     parentId: 10_000,
+//     size: 0,
+//     type: 'mp4',
+//   },
+// ];
+
+const gridOptions: VxeGridProps<RowType> = {
+  columns: [
+    { type: 'seq', width: 70 },
+    { field: 'name', minWidth: 300, title: 'Name', treeNode: true },
+    { field: 'size', title: 'Size' },
+    { field: 'type', title: 'Type' },
+    { field: 'date', title: 'Date' },
+  ],
+  data: MOCK_TREE_TABLE_DATA,
+  pagerConfig: {
+    enabled: false,
+  },
+  treeConfig: {
+    parentField: 'parentId',
+    rowField: 'id',
+    transform: true,
+  },
+};
+
+const [Grid, gridApi] = useVbenVxeGrid({ gridOptions });
+
+const expandAll = () => {
+  gridApi.grid?.setAllTreeExpand(true);
+};
+
+const collapseAll = () => {
+  gridApi.grid?.setAllTreeExpand(false);
+};
+</script>
+
+<template>
+  <div class="vp-raw h-[300px] w-full">
+    <Grid>
+      <template #toolbar-tools>
+        <Button class="mr-2" type="primary" @click="expandAll">
+          展开全部
+        </Button>
+        <Button type="primary" @click="collapseAll"> 折叠全部 </Button>
+      </template>
+    </Grid>
+  </div>
+</template>

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

@@ -0,0 +1,64 @@
+<script lang="ts" setup>
+import type { VxeGridProps } from '#/adapter/vxe-table';
+
+import { onMounted } from 'vue';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+
+interface RowType {
+  id: number;
+  name: string;
+  role: string;
+  sex: string;
+}
+
+const gridOptions: VxeGridProps<RowType> = {
+  columns: [
+    { type: 'seq', width: 70 },
+    { field: 'name', title: 'Name' },
+    { field: 'role', title: 'Role' },
+    { field: 'sex', title: 'Sex' },
+  ],
+  data: [],
+  height: 'auto',
+  pagerConfig: {
+    enabled: false,
+  },
+  scrollY: {
+    enabled: true,
+    gt: 0,
+  },
+  showOverflow: true,
+};
+
+const [Grid, gridApi] = useVbenVxeGrid({ gridOptions });
+
+// 模拟行数据
+const loadList = (size = 200) => {
+  try {
+    const dataList: RowType[] = [];
+    for (let i = 0; i < size; i++) {
+      dataList.push({
+        id: 10_000 + i,
+        name: `Test${i}`,
+        role: 'Developer',
+        sex: '男',
+      });
+    }
+    gridApi.setGridOptions({ data: dataList });
+  } catch (error) {
+    console.error('Failed to load data:', error);
+    // Implement user-friendly error handling
+  }
+};
+
+onMounted(() => {
+  loadList(1000);
+});
+</script>
+
+<template>
+  <div class="vp-raw h-[500px] w-full">
+    <Grid />
+  </div>
+</template>

docs/src/en/guide/essentials/route.md

@@ -2,42 +2,66 @@
 outline: deep
 ---
 
-# Routing and Menus
+# Routes and Menus
 
-In the project, the framework provides a basic routing system and **automatically generates the corresponding menu structure based on the routing file**.
+::: info
 
-## Route Types
+This page is translated by machine translation and may not be very accurate.
 
-Routes are divided into static routes and dynamic routes. Static routes are routes that have been determined when the project starts. Dynamic routes are generally routes that are dynamically generated based on the user's permissions after the user logs in.
+:::
+
+In the project, the framework provides a basic routing system and **automatically generates the corresponding menu structure based on the routing files**.
+
+## Types of Routes
+
+Routes are divided into core routes, static routes, and dynamic routes. Core routes are built-in routes of the framework, including root routes, login routes, 404 routes, etc.; static routes are routes that are determined when the project starts; dynamic routes are generally generated dynamically based on the user's permissions after the user logs in.
+
+Both static and dynamic routes go through permission control, which can be controlled by configuring the `authority` field in the `meta` property of the route.
+
+### Core Routes
+
+Core routes are built-in routes of the framework, including root routes, login routes, 404 routes, etc. The configuration of core routes is in the `src/router/routes/core` directory under the application.
+
+::: tip
+
+Core routes are mainly used for the basic functions of the framework, so it is not recommended to put business-related routes in core routes. It is recommended to put business-related routes in static or dynamic routes.
+
+:::
 
 ### Static Routes
 
-If your page project does not require permission control, you can directly use static routes. The configuration of static routes is in the `src/router/routes/index` directory under the application. Open the commented file content:
+The configuration of static routes is in the `src/router/routes/index` directory under the application. Open the commented file content:
+
+::: tip
+
+Permission control is controlled by the `authority` field in the `meta` property of the route. If your page project does not require permission control, you can omit the `authority` field.
+
+:::
 
 ```ts
-// If necessary, you can open your own comments and create folders
+// Uncomment if needed and create the folder
 // const externalRouteFiles = import.meta.glob('./external/**/*.ts', { eager: true }); // [!code --]
 const staticRouteFiles = import.meta.glob('./static/**/*.ts', { eager: true }); // [!code ++]
-/** Dynamic routing */
+/** Dynamic routes */
 const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles);
 
-/** External routing lists, which can be accessed without Layout, may be used for embedding in other systems */
+/** External route list, these pages can be accessed without Layout, possibly used for embedding in other systems */
 // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles) // [!code --]
 const externalRoutes: RouteRecordRaw[] = []; // [!code --]
 const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles); // [!code ++]
 ```
 
-### Dynamic routing
+### Dynamic Routes
 
-The configuration of dynamic routing is in the corresponding application `src/router/routes/modules` directory. All routing files are stored in this directory. The content format of each file is as follows, which is consistent with the routing configuration format of Vue Router. The following is the configuration of secondary routes and multi-level routes.
+The configuration of dynamic routes is in the `src/router/routes/modules` directory under the corresponding application. This directory contains all the route files. The content format of each file is consistent with the Vue Router route configuration format. Below is the configuration of secondary and multi-level routes.
 
-## Define the route
+## Route Definition
 
-Static routes and dynamic routes are configured in the same way. The configuration of the level-2 and multi-level routes is as follows:
+The configuration method of static routes and dynamic routes is the same. Below is the configuration of secondary and multi-level routes:
 
-### Secondary route
+### Secondary Routes
 
-::: details Example code of the secondary route
+::: details Secondary Route Example Code
 
 ```ts
 import type { RouteRecordRaw } from 'vue-router';
@@ -81,17 +105,16 @@ export default routes;
 
 :::
 
-### Multilevel routing
+### Multi-level Routes
 
 ::: tip
 
-- The parent route of multi-level routing does not need to set the 'component' attribute, only the 'children' attribute needs to be set. Unless you really need to display content under nested parent routing.
-
-- If there are no special circumstances, the 'redirect' attribute of the parent route does not need to be specified and will default to the first child route.
+- The parent route of multi-level routes does not need to set the `component` property, just set the `children` property. Unless you really need to display content nested under the parent route.
+- In most cases, the `redirect` property of the parent route does not need to be specified, it will default to the first child route.
 
 :::
 
-::: details Multilevel Routing Example Code
+::: details Multi-level Route Example Code
 
 ```ts
 import type { RouteRecordRaw } from 'vue-router';
@@ -112,7 +135,7 @@ const routes: RouteRecordRaw[] = [
     path: '/demos',
     redirect: '/demos/access',
     children: [
-      // 嵌套菜单
+      // Nested menu
       {
         meta: {
           icon: 'ic:round-menu',
@@ -208,13 +231,13 @@ export default routes;
 
 :::
 
-## Add a New Page
+## Adding a New Page
 
 To add a new page, you only need to add a route and the corresponding page component.
 
-### Add a Route
+### Adding a Route
 
-Add a route object in the corresponding routing file as follows:
+Add a route object in the corresponding route file, as follows:
 
 ```ts
 import type { RouteRecordRaw } from 'vue-router';
@@ -251,9 +274,9 @@ const routes: RouteRecordRaw[] = [
 export default routes;
 ```
 
-### Add Page Component
+### Adding a Page Component
 
-In `#/views/home/`, add a new `index.vue` file as follows:
+In `#/views/home/`, add a new `index.vue` file, as follows:
 
 ```vue
 <template>
@@ -265,11 +288,11 @@ In `#/views/home/`, add a new `index.vue` file as follows:
 
 ### Verification
 
-At this point, the page has been added. Access `http://localhost:5555/home/index` to see the corresponding page.
+At this point, the page has been added. Visit `http://localhost:5555/home/index` to see the corresponding page.
 
 ## Route Configuration
 
-The route configuration mainly resides in the `meta` attribute of the route object. Below are some commonly used configuration items：
+The route configuration items are mainly in the `meta` property of the route object. The following are common configuration items:
 
 ```ts {5-8}
 const routes = [
@@ -293,22 +316,21 @@ interface RouteMeta {
    */
   activeIcon?: string;
   /**
-   * The currently active menu, used when you want to activate a parent menu instead of the existing one
-   * @default false
+   * The currently active menu, sometimes you don't want to activate the existing menu, use this to activate the parent menu
    */
   activePath?: string;
   /**
-   * Whether to affix the tab
+   * Whether to fix the tab
    * @default false
    */
   affixTab?: boolean;
   /**
-   * The order of the affixed tab
+   * The order of fixed tabs
    * @default 0
    */
   affixTabOrder?: number;
   /**
-   * Specific role identifiers required for access
+   * Specific roles required to access
    * @default []
    */
   authority?: string[];
@@ -331,22 +353,22 @@ interface RouteMeta {
     | 'warning'
     | string;
   /**
-   * Children of the current route do not show in the menu
+   * The children of the current route are not displayed in the menu
    * @default false
    */
   hideChildrenInMenu?: boolean;
   /**
-   * The current route does not show in the breadcrumb
+   * The current route is not displayed in the breadcrumb
    * @default false
    */
   hideInBreadcrumb?: boolean;
   /**
-   * The current route does not show in the menu
+   * The current route is not displayed in the menu
    * @default false
    */
   hideInMenu?: boolean;
   /**
-   * The current route does not show in tabs
+   * The current route is not displayed in the tab
    * @default false
    */
   hideInTab?: boolean;
@@ -359,16 +381,16 @@ interface RouteMeta {
    */
   iframeSrc?: string;
   /**
-   * Ignore access, can be accessed directly
+   * Ignore permissions, can be accessed directly
    * @default false
    */
   ignoreAccess?: boolean;
   /**
-   * Enable KeepAlive caching
+   * Enable KeepAlive cache
    */
   keepAlive?: boolean;
   /**
-   * External link - redirect path
+   * External link - jump path
    */
   link?: string;
   /**
@@ -381,7 +403,7 @@ interface RouteMeta {
    */
   maxNumOfOpenTab?: number;
   /**
-   * The menu is visible, but access will be redirected to 403
+   * The menu can be seen, but access will be redirected to 403
    */
   menuVisibleWithForbidden?: boolean;
   /**
@@ -389,9 +411,13 @@ interface RouteMeta {
    */
   openInNewWindow?: boolean;
   /**
-   * Used for route->menu sorting
+   * Used for route -> menu sorting
    */
   order?: number;
+  /**
+   * Parameters carried by the menu
+   */
+  query?: Recordable;
   /**
    * Title name
    */
@@ -404,153 +430,169 @@ interface RouteMeta {
 ### title
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the page title, which will be displayed in the menu and tabs. It is generally used in conjunction with internationalization.
+Used to configure the title of the page, which will be displayed in the menu and tab. Generally used with internationalization.
 
 ### icon
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the page icon, which will be displayed in the menu and tabs. It is generally used in conjunction with an icon library. If it is an `http` link, the image will be automatically loaded.
+Used to configure the icon of the page, which will be displayed in the menu and tab. Generally used with an icon library, if it is an `http` link, the image will be loaded automatically.
 
 ### activeIcon
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the active icon of the page, which will be displayed in the menu. It is generally used in conjunction with an icon library. If it is an `http` link, the image will be automatically loaded.
+Used to configure the active icon of the page, which will be displayed in the menu. Generally used with an icon library, if it is an `http` link, the image will be loaded automatically.
 
 ### keepAlive
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
-Used to configure whether the page caching is enabled. Once enabled, the page will be cached and not reloaded, only effective when tabs are enabled.
+Used to configure whether the page cache is enabled. When enabled, the page will be cached and will not reload, only effective when the tab is enabled.
 
 ### hideInMenu
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
-Used to configure whether the page is hidden in the menu. If hidden, the page will not be displayed in the menu.
+Used to configure whether the page is hidden in the menu. When hidden, the page will not be displayed in the menu.
 
 ### hideInTab
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
-Used to configure whether the page is hidden in tabs. If hidden, the page will not be displayed in tabs.
+Used to configure whether the page is hidden in the tab. When hidden, the page will not be displayed in the tab.
 
 ### hideInBreadcrumb
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
-Used to configure whether the page is hidden in the breadcrumb. If hidden, the page will not be displayed in the breadcrumb.
+Used to configure whether the page is hidden in the breadcrumb. When hidden, the page will not be displayed in the breadcrumb.
 
 ### hideChildrenInMenu
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
-Used to configure whether the child pages of the page are hidden in the menu. If hidden, the child pages will not be displayed in the menu.
+Used to configure whether the subpages of the page are hidden in the menu. When hidden, the subpages will not be displayed in the menu.
 
 ### authority
 
 - Type: `string[]`
-- Default value: `[]`
+- Default: `[]`
 
-Used to configure the page's permissions. Only users with corresponding permissions can access the page. If not configured, no permissions are required.
+Used to configure the permissions of the page. Only users with the corresponding permissions can access the page. If not configured, no permissions are required.
 
 ### badge
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the page's badge, which will be displayed in the menu.
+Used to configure the badge of the page, which will be displayed in the menu.
 
 ### badgeType
 
 - Type: `'dot' | 'normal'`
-- Default value: `'normal'`
+- Default: `'normal'`
 
-Used to configure the type of the page's badge. `dot` is a small red dot, `normal` is text.
+Used to configure the badge type of the page. `dot` is a small red dot, `normal` is text.
 
 ### badgeVariants
 
 - Type: `'default' | 'destructive' | 'primary' | 'success' | 'warning' | string`
-- Default value: `'success'`
+- Default: `'success'`
 
-Used to configure the color of the page's badge.
+Used to configure the badge color of the page.
 
 ### activePath
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the currently active menu. Sometimes when the page is not displayed in the menu, it is used to activate the parent menu.
+Used to configure the currently active menu. Sometimes the page is not displayed in the menu, and this is used to activate the parent menu.
 
 ### affixTab
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
-Used to configure whether the page tab is pinned. Once pinned, the page cannot be closed.
+Used to configure whether the page is fixed in the tab. When fixed, the page cannot be closed.
 
 ### affixTabOrder
 
 - Type: `number`
-- Default value: `0`
+- Default: `0`
 
-Used to configure the order of the pinned page tabs, sorted in ascending order.
+Used to configure the order of fixed tabs, sorted in ascending order.
 
 ### iframeSrc
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the `iframe` address of the embedded page. Once set, the corresponding page will be embedded in the current page.
+Used to configure the `iframe` address of the embedded page. When set, the corresponding page will be embedded in the current page.
 
 ### ignoreAccess
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
 Used to configure whether the page ignores permissions and can be accessed directly.
 
 ### link
 
 - Type: `string`
-- Default value: `''`
+- Default: `''`
 
-Used to configure the external link jump path, which will be opened in a new window.
+Used to configure the external link jump path, which will open in a new window.
 
 ### maxNumOfOpenTab
 
 - Type: `number`
-- Default value: `-1`
+- Default: `-1`
 
-Used to configure the maximum number of open tabs. Once set, the earliest opened tab will be automatically closed when a new tab is opened (only effective when opening tabs with the same name).
+Used to configure the maximum number of open tabs. When set, the earliest opened tab will be automatically closed when opening a new tab (only effective when opening tabs with the same name).
 
 ### menuVisibleWithForbidden
 
 - Type: `boolean`
-- Default value: `false`
+- Default: `false`
 
 Used to configure whether the page can be seen in the menu, but access will be redirected to 403.
 
+### openInNewWindow
+
+- Type: `boolean`
+- Default: `false`
+
+When set to `true`, the page will open in a new window.
+
 ### order
 
 - Type: `number`
-- Default value: `0`
+- Default: `0`
 
-Used to configure the page's order, for routing to menu sorting.
+Used to configure the sorting of the page, used for route to menu sorting.
+
+_Note:_ Sorting is only effective for first-level menus. The sorting of second-level menus needs to be set in the corresponding first-level menu in code order.
+
+### query
+
+- Type: `Recordable`
+- Default: `{}`
+
+Used to configure the menu parameters of the page, which will be passed to the page in the menu.
 
 ## Route Refresh
 
-The way to refresh the route is as follows:
+The route refresh method is as follows:
 
 ```vue
 <script setup lang="ts">

docs/src/en/guide/essentials/settings.md

@@ -217,6 +217,7 @@ const defaultPreferences: Preferences = {
     globalSearch: true,
   },
   sidebar: {
+    autoActivateChild: false,
     collapsed: false,
     collapsedShowTitle: false,
     enable: true,

docs/src/en/guide/essentials/styles.md

@@ -72,7 +72,7 @@ const { b, e, is } = useNamespace('menu');
 </template>
 <style lang="scss" scoped>
 // If you use it within the application, this line of code can be omitted as it has already been globally introduced in all applications
-@import '@vben/styles/global';
+@use '@vben/styles/global' as *;
 @include b('menu') {
   color: black;
 

docs/src/en/guide/introduction/vben.md

@@ -18,7 +18,7 @@
 - **Permission Validation**: Comprehensive permission validation solutions, including button-level permission control.
 - **Multi-Theme**: Built-in multiple theme configurations & dark mode to meet personalized needs.
 - **Dynamic Menu**: Supports dynamic menus that can display based on permissions.
-- **Mock Data**: High-performance local Mock data solution based on Nitro.
+- **Mock Data**: High-performance local Mock data solution based on `Nitro`.
 - **Rich Components**: Provides a wide range of components to meet most business needs.
 - **Standardization**: Code quality is ensured with tools like `ESLint`, `Prettier`, `Stylelint`, `Publint`, and `CSpell`.
 - **Engineering**: Development efficiency is improved with tools like `Pnpm Monorepo`, `TurboRepo`, and `Changeset`.
@@ -26,9 +26,9 @@
 
 ## Browser Support
 
-**Local development** is recommended using the **latest version of Chrome**. **Versions below Chrome 80 are not supported**.
+- **Local development** is recommended using the **latest version of Chrome**. **Versions below Chrome 80 are not supported**.
 
-**Production environment** supports modern browsers, IE is not supported.
+- **Production environment** supports modern browsers, IE is not supported.
 
 | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png" alt="IE" width="24px" height="24px"  />](http://godban.github.io/browsers-support-badges/)IE | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt=" Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Safari |
 | :-: | :-: | :-: | :-: | :-: |
@@ -37,12 +37,10 @@
 ## Contribution
 
 - [Vben Admin](https://github.com/vbenjs/vue-vben-admin) is still being actively updated. Contributions are welcome to help maintain and improve the project, aiming to create a better mid- to backend solution.
-- If you wish to join us, you can provide suggestions or submit pull requests. We will invite you to join based on your activity.
+- If you wish to join us, you can start by contributing in the following ways, and we will invite you to join based on your activity.
 
 ::: info Join Us
 
-If you wish to join us, you can start by contributing in the following ways, and we will invite you to join based on your activity:
-
 - Regularly submit `PRs`.
 - Provide valuable suggestions.
 - Participate in discussions and help resolve some `issues`.

docs/src/guide/essentials/icons.md

@@ -67,7 +67,7 @@ import { SvgTestIcon } from '@vben/icons';
 </template>
 ```
 
-## Tailwind CSS 图标 <Badge text="不推荐" type="danger"/>
+## Tailwind CSS 图标
 
 ### 使用
 

docs/src/guide/essentials/route.md

@@ -8,11 +8,29 @@ outline: deep
 
 ## 路由类型
 
-路由分为静态路由和动态路由，静态路由是在项目启动时就已经确定的路由。动态路由一般是在用户登录后，根据用户的权限动态生成的路由。
+路由分为核心路由、静态路由和动态路由，核心路由是框架内置的路由，包含了根路由、登录路由、404路由等；静态路由是在项目启动时就已经确定的路由；动态路由一般是在用户登录后，根据用户的权限动态生成的路由。
+
+静态路由和动态路由都会走权限控制，可以通过配置路由的 `meta` 属性中的 `authority` 字段来控制权限，可以参考[路由权限控制](https://github.com/vbenjs/vue-vben-admin/blob/main/playground/src/router/routes/modules/demos.ts)。
+
+### 核心路由
+
+核心路由是框架内置的路由，包含了根路由、登录路由、404路由等，核心路由的配置在应用下 `src/router/routes/core` 目录下
+
+::: tip
+
+核心路由主要用于框架的基础功能，因此不建议将业务相关的路由放在核心路由中，推荐将业务相关的路由放在静态路由或动态路由中。
+
+:::
 
 ### 静态路由
 
-如果你的页面项目不需要权限控制，可以直接使用静态路由，静态路由的配置在应用下 `src/router/routes/index` 目录下，打开注释的文件内容:
+静态路由的配置在应用下 `src/router/routes/index` 目录下，打开注释的文件内容:
+
+::: tip
+
+权限控制是通过路由的 `meta` 属性中的 `authority` 字段来控制的，如果你的页面项目不需要权限控制，可以不设置 `authority` 字段。
+
+:::
 
 ```ts
 // 有需要可以自行打开注释，并创建文件夹

docs/src/guide/essentials/settings.md

@@ -164,6 +164,7 @@ import { defineOverridesPreferences } from '@vben/preferences';
 /**
  * @description 项目配置文件
  * 只需要覆盖项目中的一部分配置，不需要的配置不用覆盖，会自动使用默认配置
+ * !!! 更改配置后请清空缓存，否则可能不生效
  */
 export const overridesPreferences = defineOverridesPreferences({
   // overrides
@@ -239,6 +240,7 @@ const defaultPreferences: Preferences = {
     globalSearch: true,
   },
   sidebar: {
+    autoActivateChild: false,
     collapsed: false,
     collapsedShowTitle: false,
     enable: true,
@@ -536,5 +538,4 @@ interface Preferences {
 
 - `overridesPreferences`方法只需要覆盖项目中的一部分配置，不需要的配置不用覆盖，会自动使用默认配置。
 - 任何配置项都可以覆盖，只需要在`overridesPreferences`方法内覆盖即可，不要修改默认配置文件。
-
-:::
+- 更改配置后请清空缓存，否则可能不生效。:::

docs/src/guide/essentials/styles.md

@@ -72,7 +72,7 @@ const { b, e, is } = useNamespace('menu');
 </template>
 <style lang="scss" scoped>
 // 如果你在应用内使用，这行代码可以省略，已经在所有的应用内全局引入了
-@import '@vben/styles/global';
+@use '@vben/styles/global' as *;
 @include b('menu') {
   color: black;
 

docs/src/guide/in-depth/ui-framework.md

@@ -4,7 +4,7 @@
 
 ## 新增组件库应用
 
-如果你想用其他别的组件库，你只需要按一下步骤进行操作：
+如果你想用其他别的组件库，你只需要按以下步骤进行操作：
 
 1. 在`apps`内创建一个新的文件夹，例如`apps/web-xxx`。
 2. 更改`apps/web-xxx/package.json`的`name`字段为`web-xxx`。

docs/src/guide/introduction/quick-start.md

@@ -66,7 +66,9 @@ pnpm install
 
 ::: tip 注意
 
-项目只支持使用 `pnpm` 进行依赖安装，默认会使用 `corepack` 来安装指定版本的 `pnpm`。:
+- 项目只支持使用 `pnpm` 进行依赖安装，默认会使用 `corepack` 来安装指定版本的 `pnpm`。:
+- 如果你的网络环境无法访问npm源，你可以设置系统的环境变量`COREPACK_REGISTRY=https://registry.npmmirror.com`，然后再执行`pnpm install`。
+- 如果你不想使用`corepack`，你需要禁用`corepack`，然后使用你自己的`pnpm`进行安装。
 
 :::
 

docs/src/guide/introduction/vben.md

@@ -18,7 +18,7 @@
 - **权限验证**：完善的权限验证方案，按钮级别权限控制。
 - **多主题**：内置多种主题配置和黑暗模式，满足个性化需求。
 - **动态菜单**：支持动态菜单，可以根据权限配置显示菜单。
-- **Mock 数据**：基于 Nitro 的本地高性能 Mock 数据方案。
+- **Mock 数据**：基于 `Nitro` 的本地高性能 Mock 数据方案。
 - **组件丰富**：提供了丰富的组件，可以满足大部分的业务需求。
 - **规范**：代码规范，使用 `ESLint`、`Prettier`、`Stylelint`、`Publint`、`CSpell` 等工具保证代码质量。
 - **工程化**：使用 `Pnpm Monorepo`、`TurboRepo`、`Changeset` 等工具，提高开发效率。
@@ -26,9 +26,9 @@
 
 ## 浏览器支持
 
-**本地开发**推荐使用`Chrome 最新版`浏览器，**不支持**`Chrome 80`以下版本。
+- **本地开发**推荐使用`Chrome 最新版`浏览器，**不支持**`Chrome 80`以下版本。
 
-**生产环境**支持现代浏览器，不支持 IE。
+- **生产环境**支持现代浏览器，不支持 IE。
 
 | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png" alt="IE" width="24px" height="24px"  />](http://godban.github.io/browsers-support-badges/)IE | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt=" Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)Safari |
 | :-: | :-: | :-: | :-: | :-: |
@@ -37,13 +37,13 @@
 ## 贡献
 
 - [Vben Admin](https://github.com/vbenjs/vue-vben-admin) 还在持续更新中，本项目欢迎您的参与，共同维护，逐步完善，打造更好的中后台解决方案。
-- 如果你想加入我们，可以提供有价值的建议或者参与讨论，协助解决 issue，- 如果你想加入我们，可以提供有价值的建议或者参与讨论，协助解决 issue，我们会根据你的活跃度邀请你加入。。
+- 如果你有兴趣加入我们，可以通过以下方式开始，我们会根据你的活跃度邀请你加入。
 
 ::: info 加入我们
 
 - 长期提交 `PR`。
-- 提供一些好的建议。
-- 参与讨论，帮助解决一些 `issue`。
+- 提供有价值的建议。
+- 参与讨论，帮助解决 `issue`。
 - 共同维护文档。
 
 :::

internal/lint-configs/commitlint-config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/commitlint-config",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",

internal/lint-configs/eslint-config/src/configs/typescript.ts

@@ -22,7 +22,7 @@ export async function typescript(): Promise<Linter.Config[]> {
           ecmaVersion: 'latest',
           extraFileExtensions: ['.vue'],
           jsxPragma: 'React',
-          project: './tsconfig.*?.json',
+          project: './tsconfig.*.json',
           sourceType: 'module',
         },
       },

internal/lint-configs/eslint-config/src/configs/unicorn.ts

@@ -18,6 +18,7 @@ export async function unicorn(): Promise<Linter.Config[]> {
         'unicorn/better-regex': 'off',
         'unicorn/consistent-destructuring': 'off',
         'unicorn/consistent-function-scoping': 'off',
+        'unicorn/expiring-todo-comments': 'off',
         'unicorn/filename-case': 'off',
         'unicorn/import-style': 'off',
         'unicorn/no-array-for-each': 'off',

internal/lint-configs/eslint-config/src/configs/vue.ts

@@ -4,7 +4,6 @@ import { interopDefault } from '../util';
 
 export async function vue(): Promise<Linter.Config[]> {
   const [pluginVue, parserVue, parserTs] = await Promise.all([
-    // @ts-expect-error missing types
     interopDefault(import('eslint-plugin-vue')),
     interopDefault(import('vue-eslint-parser')),
     // @ts-expect-error missing types

internal/lint-configs/stylelint-config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/stylelint-config",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",

internal/node-utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/node-utils",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",

internal/tailwind-config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/tailwind-config",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",

internal/tsconfig/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/tsconfig",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",

internal/vite-config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben/vite-config",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",

internal/vite-config/src/config/application.ts

@@ -1,4 +1,4 @@
-import type { UserConfig } from 'vite';
+import type { CSSOptions, UserConfig } from 'vite';
 
 import type { DefineApplicationOptions } from '../typing';
 
@@ -6,6 +6,7 @@ import path, { relative } from 'node:path';
 
 import { findMonorepoRoot } from '@vben/node-utils';
 
+import { NodePackageImporter } from 'sass';
 import { defineConfig, loadEnv, mergeConfig } from 'vite';
 
 import { defaultImportmapOptions, getDefaultPwaOptions } from '../options';
@@ -85,7 +86,7 @@ function defineApplicationConfig(userConfigPromise?: DefineApplicationOptions) {
           clientFiles: [
             './index.html',
             './src/bootstrap.ts',
-            './src/{views,layouts,router,store,api}/*',
+            './src/{views,layouts,router,store,api,adapter}/*',
           ],
         },
       },
@@ -99,7 +100,7 @@ function defineApplicationConfig(userConfigPromise?: DefineApplicationOptions) {
   });
 }
 
-function createCssOptions(injectGlobalScss = true) {
+function createCssOptions(injectGlobalScss = true): CSSOptions {
   const root = findMonorepoRoot();
   return {
     preprocessorOptions: injectGlobalScss
@@ -109,11 +110,12 @@ function createCssOptions(injectGlobalScss = true) {
               const relativePath = relative(root, filepath);
               // apps下的包注入全局样式
               if (relativePath.startsWith(`apps${path.sep}`)) {
-                return `@import "@vben/styles/global";\n${content}`;
+                return `@use "@vben/styles/global" as *;\n${content}`;
               }
               return content;
             },
-            api: 'modern-compiler',
+            api: 'modern',
+            importers: [new NodePackageImporter()],
           },
         }
       : {},

internal/vite-config/src/plugins/index.ts

@@ -243,4 +243,5 @@ export {
   viteDtsPlugin,
   viteHtmlPlugin,
   viteVisualizerPlugin,
+  viteVxeTableImportsPlugin,
 };

internal/vite-config/src/utils/env.ts

@@ -1,5 +1,6 @@
 import type { ApplicationPluginOptions } from '../typing';
 
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { fs } from '@vben/node-utils';
@@ -21,12 +22,11 @@ function getConfFiles() {
   const script = process.env.npm_lifecycle_script as string;
   const reg = /--mode ([\d_a-z]+)/;
   const result = reg.exec(script);
-
+  let mode = 'production';
   if (result) {
-    const mode = result[1];
-    return ['.env', `.env.${mode}`];
+    mode = result[1] as string;
   }
-  return ['.env', '.env.production'];
+  return ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`];
 }
 
 /**
@@ -42,11 +42,14 @@ async function loadEnv<T = Record<string, string>>(
 
   for (const confFile of confFiles) {
     try {
-      const envPath = await fs.readFile(join(process.cwd(), confFile), {
-        encoding: 'utf8',
-      });
-      const env = dotenv.parse(envPath);
-      envConfig = { ...envConfig, ...env };
+      const confFilePath = join(process.cwd(), confFile);
+      if (existsSync(confFilePath)) {
+        const envPath = await fs.readFile(confFilePath, {
+          encoding: 'utf8',
+        });
+        const env = dotenv.parse(envPath);
+        envConfig = { ...envConfig, ...env };
+      }
     } catch (error) {
       console.error(`Error while parsing ${confFile}`, error);
     }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vben-admin-monorepo",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "private": true,
   "keywords": [
     "monorepo",
@@ -97,9 +97,9 @@
   },
   "engines": {
     "node": ">=20.10.0",
-    "pnpm": ">=9.5.0"
+    "pnpm": ">=9.12.0"
   },
-  "packageManager": "pnpm@9.12.3",
+  "packageManager": "pnpm@9.15.1",
   "pnpm": {
     "peerDependencyRules": {
       "allowedVersions": {
@@ -110,6 +110,7 @@
       "@ast-grep/napi": "catalog:",
       "@ctrl/tinycolor": "catalog:",
       "clsx": "catalog:",
+      "esbuild": "0.24.0",
       "pinia": "catalog:",
       "vue": "catalog:"
     },

packages/@core/base/design/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vben-core/design",
-  "version": "5.4.4",
+  "version": "5.5.2",
   "homepage": "https://github.com/vbenjs/vue-vben-admin",
   "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",
   "repository": {
@@ -28,7 +28,7 @@
     ".": {
       "types": "./src/index.ts",
       "development": "./src/index.ts",
-      "default": "./dist/style.css"
+      "default": "./dist/design.css"
     }
   },
   "publishConfig": {