From b8bffd884ca8fd060d66483e217340a1695e2340 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Fri, 10 Jan 2025 20:52:31 +0800
Subject: [PATCH 1/7] feat: allow close tab when mouse middle button click
 (#5347)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 偏好设置增加鼠标中键关闭标签页的设置
---
 .../__tests__/__snapshots__/config.test.ts.snap   |  1 +
 packages/@core/preferences/src/config.ts          |  1 +
 packages/@core/preferences/src/types.ts           |  2 ++
 .../tabs-ui/src/components/tabs-chrome/tabs.vue   | 15 +++++++++++++++
 .../ui-kit/tabs-ui/src/components/tabs/tabs.vue   | 15 +++++++++++++++
 packages/@core/ui-kit/tabs-ui/src/types.ts        |  7 ++++++-
 .../effects/layouts/src/basic/tabbar/tabbar.vue   |  1 +
 .../widgets/preferences/blocks/layout/tabbar.vue  |  6 ++++++
 .../widgets/preferences/preferences-drawer.vue    |  4 ++++
 packages/locales/src/langs/en-US/preferences.json |  3 +++
 packages/locales/src/langs/zh-CN/preferences.json |  1 +
 11 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap b/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap
index 81df9682..486bf048 100644
--- a/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap
+++ b/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap
@@ -80,6 +80,7 @@ exports[`defaultPreferences immutability test > should not modify the config obj
     "enable": true,
     "height": 38,
     "keepAlive": true,
+    "middleClickToClose": false,
     "persist": true,
     "showIcon": true,
     "showMaximize": true,
diff --git a/packages/@core/preferences/src/config.ts b/packages/@core/preferences/src/config.ts
index 10971de5..8f82e4fc 100644
--- a/packages/@core/preferences/src/config.ts
+++ b/packages/@core/preferences/src/config.ts
@@ -80,6 +80,7 @@ const defaultPreferences: Preferences = {
     enable: true,
     height: 38,
     keepAlive: true,
+    middleClickToClose: false,
     persist: true,
     showIcon: true,
     showMaximize: true,
diff --git a/packages/@core/preferences/src/types.ts b/packages/@core/preferences/src/types.ts
index f8b35242..b554b219 100644
--- a/packages/@core/preferences/src/types.ts
+++ b/packages/@core/preferences/src/types.ts
@@ -168,6 +168,8 @@ interface TabbarPreferences {
   height: number;
   /** 开启标签页缓存功能 */
   keepAlive: boolean;
+  /** 是否点击中键时关闭标签 */
+  middleClickToClose: boolean;
   /** 是否持久化标签 */
   persist: boolean;
   /** 是否开启多标签页图标 */
diff --git a/packages/@core/ui-kit/tabs-ui/src/components/tabs-chrome/tabs.vue b/packages/@core/ui-kit/tabs-ui/src/components/tabs-chrome/tabs.vue
index 7ab875a7..eb977ce4 100644
--- a/packages/@core/ui-kit/tabs-ui/src/components/tabs-chrome/tabs.vue
+++ b/packages/@core/ui-kit/tabs-ui/src/components/tabs-chrome/tabs.vue
@@ -56,6 +56,20 @@ const tabsView = computed(() => {
     } as TabConfig;
   });
 });
+
+function onMouseDown(e: MouseEvent, tab: TabConfig) {
+  if (
+    e.button === 1 &&
+    tab.closable &&
+    !tab.affixTab &&
+    tabsView.value.length > 1 &&
+    props.middleClickToClose
+  ) {
+    e.preventDefault();
+    e.stopPropagation();
+    emit('close', tab.key);
+  }
+}
 </script>
 
 <template>
@@ -82,6 +96,7 @@ const tabsView = computed(() => {
         class="tabs-chrome__item draggable translate-all group relative -mr-3 flex h-full select-none items-center"
         data-tab-item="true"
         @click="active = tab.key"
+        @mousedown="onMouseDown($event, tab)"
       >
         <VbenContextMenu
           :handler-data="tab"
diff --git a/packages/@core/ui-kit/tabs-ui/src/components/tabs/tabs.vue b/packages/@core/ui-kit/tabs-ui/src/components/tabs/tabs.vue
index ba77aabe..6197ff96 100644
--- a/packages/@core/ui-kit/tabs-ui/src/components/tabs/tabs.vue
+++ b/packages/@core/ui-kit/tabs-ui/src/components/tabs/tabs.vue
@@ -62,6 +62,20 @@ const tabsView = computed(() => {
     } as TabConfig;
   });
 });
+
+function onMouseDown(e: MouseEvent, tab: TabConfig) {
+  if (
+    e.button === 1 &&
+    tab.closable &&
+    !tab.affixTab &&
+    tabsView.value.length > 1 &&
+    props.middleClickToClose
+  ) {
+    e.preventDefault();
+    e.stopPropagation();
+    emit('close', tab.key);
+  }
+}
 </script>
 
 <template>
@@ -85,6 +99,7 @@ const tabsView = computed(() => {
         class="tab-item [&:not(.is-active)]:hover:bg-accent translate-all group relative flex cursor-pointer select-none"
         data-tab-item="true"
         @click="active = tab.key"
+        @mousedown="onMouseDown($event, tab)"
       >
         <VbenContextMenu
           :handler-data="tab"
diff --git a/packages/@core/ui-kit/tabs-ui/src/types.ts b/packages/@core/ui-kit/tabs-ui/src/types.ts
index 842fd42c..19ecf03a 100644
--- a/packages/@core/ui-kit/tabs-ui/src/types.ts
+++ b/packages/@core/ui-kit/tabs-ui/src/types.ts
@@ -33,6 +33,11 @@ export interface TabsProps {
    * 仅限 tabs-chrome
    */
   maxWidth?: number;
+  /**
+   * @zh_CN 点击中键时关闭Tab
+   */
+  middleClickToClose?: boolean;
+
   /**
    * @zh_CN tab最小宽度
    * 仅限 tabs-chrome
@@ -43,11 +48,11 @@ export interface TabsProps {
    * @zh_CN 是否显示图标
    */
   showIcon?: boolean;
-
   /**
    * @zh_CN 标签页风格
    */
   styleType?: TabsStyleType;
+
   /**
    * @zh_CN 选项卡数据
    */
diff --git a/packages/effects/layouts/src/basic/tabbar/tabbar.vue b/packages/effects/layouts/src/basic/tabbar/tabbar.vue
index 64ed8cba..b67b3a4a 100644
--- a/packages/effects/layouts/src/basic/tabbar/tabbar.vue
+++ b/packages/effects/layouts/src/basic/tabbar/tabbar.vue
@@ -57,6 +57,7 @@ if (!preferences.tabbar.persist) {
     :style-type="preferences.tabbar.styleType"
     :tabs="currentTabs"
     :wheelable="preferences.tabbar.wheelable"
+    :middle-click-to-close="preferences.tabbar.middleClickToClose"
     @close="handleClose"
     @sort-tabs="tabbarStore.sortTabs"
     @unpin="unpinTab"
diff --git a/packages/effects/layouts/src/widgets/preferences/blocks/layout/tabbar.vue b/packages/effects/layouts/src/widgets/preferences/blocks/layout/tabbar.vue
index e613f516..4c116e5a 100644
--- a/packages/effects/layouts/src/widgets/preferences/blocks/layout/tabbar.vue
+++ b/packages/effects/layouts/src/widgets/preferences/blocks/layout/tabbar.vue
@@ -22,6 +22,9 @@ const tabbarWheelable = defineModel<boolean>('tabbarWheelable');
 const tabbarStyleType = defineModel<string>('tabbarStyleType');
 const tabbarShowMore = defineModel<boolean>('tabbarShowMore');
 const tabbarShowMaximize = defineModel<boolean>('tabbarShowMaximize');
+const tabbarMiddleClickToClose = defineModel<boolean>(
+  'tabbarMiddleClickToClose',
+);
 
 const styleItems = computed((): SelectOption[] => [
   {
@@ -61,6 +64,9 @@ const styleItems = computed((): SelectOption[] => [
   >
     {{ $t('preferences.tabbar.wheelable') }}
   </SwitchItem>
+  <SwitchItem v-model="tabbarMiddleClickToClose" :disabled="!tabbarEnable">
+    {{ $t('preferences.tabbar.middleClickClose') }}
+  </SwitchItem>
   <SwitchItem v-model="tabbarShowIcon" :disabled="!tabbarEnable">
     {{ $t('preferences.tabbar.icon') }}
   </SwitchItem>
diff --git a/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue b/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue
index 50f0dbff..6761e8a3 100644
--- a/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue
+++ b/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue
@@ -116,6 +116,9 @@ const tabbarPersist = defineModel<boolean>('tabbarPersist');
 const tabbarDraggable = defineModel<boolean>('tabbarDraggable');
 const tabbarWheelable = defineModel<boolean>('tabbarWheelable');
 const tabbarStyleType = defineModel<string>('tabbarStyleType');
+const tabbarMiddleClickToClose = defineModel<boolean>(
+  'tabbarMiddleClickToClose',
+);
 
 const navigationStyleType = defineModel<NavigationStyleType>(
   'navigationStyleType',
@@ -362,6 +365,7 @@ async function handleReset() {
                 v-model:tabbar-show-more="tabbarShowMore"
                 v-model:tabbar-style-type="tabbarStyleType"
                 v-model:tabbar-wheelable="tabbarWheelable"
+                v-model:tabbar-middle-click-to-close="tabbarMiddleClickToClose"
               />
             </Block>
             <Block :title="$t('preferences.widget.title')">
diff --git a/packages/locales/src/langs/en-US/preferences.json b/packages/locales/src/langs/en-US/preferences.json
index 51643de1..c115d94a 100644
--- a/packages/locales/src/langs/en-US/preferences.json
+++ b/packages/locales/src/langs/en-US/preferences.json
@@ -19,6 +19,8 @@
   "twoColumnTip": "Vertical Two Column Menu Mode",
   "headerSidebarNav": "Header Vertical",
   "headerSidebarNavTip": "Header Full Width, Sidebar Navigation Mode",
+  "headerTwoColumn": "Header Two Column",
+  "headerTwoColumnTip": "Header Navigation & Sidebar Two Column co-exists",
   "mixedMenu": "Mixed Menu",
   "mixedMenuTip": "Vertical & Horizontal Menu Co-exists",
   "fullContent": "Full Content",
@@ -62,6 +64,7 @@
     "persist": "Persist Tabs",
     "draggable": "Enable Draggable Sort",
     "wheelable": "Support Mouse Wheel",
+    "middleClickClose": "Close Tab when Mouse Middle Button Click",
     "wheelableTip": "When enabled, the Tabbar area responds to vertical scrolling events of the scroll wheel.",
     "styleType": {
       "title": "Tabs Style",
diff --git a/packages/locales/src/langs/zh-CN/preferences.json b/packages/locales/src/langs/zh-CN/preferences.json
index ca867695..7e90a1da 100644
--- a/packages/locales/src/langs/zh-CN/preferences.json
+++ b/packages/locales/src/langs/zh-CN/preferences.json
@@ -64,6 +64,7 @@
     "persist": "持久化标签页",
     "draggable": "启动拖拽排序",
     "wheelable": "启用纵向滚轮响应",
+    "middleClickClose": "点击鼠标中键关闭标签页",
     "wheelableTip": "开启后，标签栏区域可以响应滚轮的纵向滚动事件。\n关闭时，只能响应系统的横向滚动事件（需要按下Shift再滚动滚轮）",
     "styleType": {
       "title": "标签页风格",

From 1a04a05b79dccd0ee923cbbf7a014c5b259db97e Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Sat, 11 Jan 2025 10:56:54 +0800
Subject: [PATCH 2/7] perf: modal and drawer api support chain calls (#5351)

* perf: modal and drawer api support chain calls

* fix: typo
---
 docs/src/components/common-ui/vben-drawer.md  |  8 ++--
 docs/src/components/common-ui/vben-modal.md   |  6 +--
 docs/src/demos/vben-drawer/dynamic/index.vue  |  3 +-
 .../demos/vben-drawer/shared-data/index.vue   | 11 ++---
 docs/src/demos/vben-modal/dynamic/index.vue   |  3 +-
 .../demos/vben-modal/shared-data/index.vue    | 11 ++---
 .../ui-kit/popup-ui/src/drawer/drawer-api.ts  |  2 +
 .../ui-kit/popup-ui/src/modal/modal-api.ts    |  2 +
 .../src/views/examples/drawer/index.vue       | 41 +++++++++----------
 playground/src/views/examples/modal/index.vue | 25 +++++------
 10 files changed, 57 insertions(+), 55 deletions(-)

diff --git a/docs/src/components/common-ui/vben-drawer.md b/docs/src/components/common-ui/vben-drawer.md
index e2409daa..43cb9889 100644
--- a/docs/src/components/common-ui/vben-drawer.md
+++ b/docs/src/components/common-ui/vben-drawer.md
@@ -133,13 +133,13 @@ const [Drawer, drawerApi] = useVbenDrawer({
 | close-icon     | 关闭按钮图标        |
 | extra          | 额外内容(标题右侧)  |
 
-### modalApi
+### drawerApi
 
-| 事件名 | 描述 | 类型 |
+| 方法 | 描述 | 类型 |
 | --- | --- | --- |
-| setState | 动态设置弹窗状态属性 | `setState(props) \| setState((prev)=>(props))` |
+| setState | 动态设置弹窗状态属性 | `(((prev: ModalState) => Partial<ModalState>)\| Partial<ModalState>)=>drawerApi` |
 | open | 打开弹窗 | `()=>void` |
 | close | 关闭弹窗 | `()=>void` |
-| setData | 设置共享数据 | `<T>(data:T)=>void` |
+| setData | 设置共享数据 | `<T>(data:T)=>drawerApi` |
 | getData | 获取共享数据 | `<T>()=>T` |
 | useStore | 获取可响应式状态 | - |
diff --git a/docs/src/components/common-ui/vben-modal.md b/docs/src/components/common-ui/vben-modal.md
index 9e422d18..45204bff 100644
--- a/docs/src/components/common-ui/vben-modal.md
+++ b/docs/src/components/common-ui/vben-modal.md
@@ -143,11 +143,11 @@ const [Modal, modalApi] = useVbenModal({
 
 ### modalApi
 
-| 事件名 | 描述 | 类型 |
+| 方法 | 描述 | 类型 |
 | --- | --- | --- |
-| setState | 动态设置弹窗状态属性 | `setState(props) \| setState((prev)=>(props))` |
+| setState | 动态设置弹窗状态属性 | `(((prev: ModalState) => Partial<ModalState>)\| Partial<ModalState>)=>modalApi` |
 | open | 打开弹窗 | `()=>void` |
 | close | 关闭弹窗 | `()=>void` |
-| setData | 设置共享数据 | `<T>(data:T)=>void` |
+| setData | 设置共享数据 | `<T>(data:T)=>modalApi` |
 | getData | 获取共享数据 | `<T>()=>T` |
 | useStore | 获取可响应式状态 | - |
diff --git a/docs/src/demos/vben-drawer/dynamic/index.vue b/docs/src/demos/vben-drawer/dynamic/index.vue
index ad7e6565..95464023 100644
--- a/docs/src/demos/vben-drawer/dynamic/index.vue
+++ b/docs/src/demos/vben-drawer/dynamic/index.vue
@@ -13,8 +13,7 @@ function open() {
 }
 
 function handleUpdateTitle() {
-  drawerApi.setState({ title: '外部动态标题' });
-  drawerApi.open();
+  drawerApi.setState({ title: '外部动态标题' }).open();
 }
 </script>
 
diff --git a/docs/src/demos/vben-drawer/shared-data/index.vue b/docs/src/demos/vben-drawer/shared-data/index.vue
index 04885f15..fef6cb05 100644
--- a/docs/src/demos/vben-drawer/shared-data/index.vue
+++ b/docs/src/demos/vben-drawer/shared-data/index.vue
@@ -9,11 +9,12 @@ const [Drawer, drawerApi] = useVbenDrawer({
 });
 
 function open() {
-  drawerApi.setData({
-    content: '外部传递的数据 content',
-    payload: '外部传递的数据 payload',
-  });
-  drawerApi.open();
+  drawerApi
+    .setData({
+      content: '外部传递的数据 content',
+      payload: '外部传递的数据 payload',
+    })
+    .open();
 }
 </script>
 
diff --git a/docs/src/demos/vben-modal/dynamic/index.vue b/docs/src/demos/vben-modal/dynamic/index.vue
index 718e532b..1b025545 100644
--- a/docs/src/demos/vben-modal/dynamic/index.vue
+++ b/docs/src/demos/vben-modal/dynamic/index.vue
@@ -13,8 +13,7 @@ function openModal() {
 }
 
 function handleUpdateTitle() {
-  modalApi.setState({ title: '外部动态标题' });
-  modalApi.open();
+  modalApi.setState({ title: '外部动态标题' }).open();
 }
 </script>
 
diff --git a/docs/src/demos/vben-modal/shared-data/index.vue b/docs/src/demos/vben-modal/shared-data/index.vue
index 58c35e24..91afeb70 100644
--- a/docs/src/demos/vben-modal/shared-data/index.vue
+++ b/docs/src/demos/vben-modal/shared-data/index.vue
@@ -9,11 +9,12 @@ const [Modal, modalApi] = useVbenModal({
 });
 
 function openModal() {
-  modalApi.setData({
-    content: '外部传递的数据 content',
-    payload: '外部传递的数据 payload',
-  });
-  modalApi.open();
+  modalApi
+    .setData({
+      content: '外部传递的数据 content',
+      payload: '外部传递的数据 payload',
+    })
+    .open();
 }
 </script>
 
diff --git a/packages/@core/ui-kit/popup-ui/src/drawer/drawer-api.ts b/packages/@core/ui-kit/popup-ui/src/drawer/drawer-api.ts
index ffb585f9..398e4f90 100644
--- a/packages/@core/ui-kit/popup-ui/src/drawer/drawer-api.ts
+++ b/packages/@core/ui-kit/popup-ui/src/drawer/drawer-api.ts
@@ -141,6 +141,7 @@ export class DrawerApi {
 
   setData<T>(payload: T) {
     this.sharedData.payload = payload;
+    return this;
   }
 
   setState(
@@ -153,5 +154,6 @@ export class DrawerApi {
     } else {
       this.store.setState((prev) => ({ ...prev, ...stateOrFn }));
     }
+    return this;
   }
 }
diff --git a/packages/@core/ui-kit/popup-ui/src/modal/modal-api.ts b/packages/@core/ui-kit/popup-ui/src/modal/modal-api.ts
index 037a0909..cc08260d 100644
--- a/packages/@core/ui-kit/popup-ui/src/modal/modal-api.ts
+++ b/packages/@core/ui-kit/popup-ui/src/modal/modal-api.ts
@@ -151,6 +151,7 @@ export class ModalApi {
 
   setData<T>(payload: T) {
     this.sharedData.payload = payload;
+    return this;
   }
 
   setState(
@@ -163,5 +164,6 @@ export class ModalApi {
     } else {
       this.store.setState((prev) => ({ ...prev, ...stateOrFn }));
     }
+    return this;
   }
 }
diff --git a/playground/src/views/examples/drawer/index.vue b/playground/src/views/examples/drawer/index.vue
index 308b386b..d50aeb22 100644
--- a/playground/src/views/examples/drawer/index.vue
+++ b/playground/src/views/examples/drawer/index.vue
@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-import type { DrawerPlacement } from '@vben/common-ui';
+import type { DrawerPlacement, DrawerState } from '@vben/common-ui';
 
 import { Page, useVbenDrawer } from '@vben/common-ui';
 
@@ -42,25 +42,21 @@ const [FormDrawer, formDrawerApi] = useVbenDrawer({
 });
 
 function openBaseDrawer(placement: DrawerPlacement = 'right') {
-  baseDrawerApi.setState({ placement });
-  baseDrawerApi.open();
+  baseDrawerApi.setState({ placement }).open();
 }
 
 function openInContentDrawer(placement: DrawerPlacement = 'right') {
-  inContentDrawerApi.setState({ class: '', placement });
+  const state: Partial<DrawerState> = { class: '', placement };
   if (placement === 'top') {
     // 页面顶部区域的层级只有200，所以设置一个低于200的值，抽屉从顶部滑出来的时候才比较合适
-    inContentDrawerApi.setState({ zIndex: 199 });
-  } else {
-    inContentDrawerApi.setState({ zIndex: undefined });
+    state.zIndex = 199;
   }
-  inContentDrawerApi.open();
+  inContentDrawerApi.setState(state).open();
 }
 
 function openMaxContentDrawer() {
   // 这里只是用来演示方便。实际上自己使用的时候可以直接将这些配置卸载Drawer的属性里
-  inContentDrawerApi.setState({ class: 'w-full', placement: 'right' });
-  inContentDrawerApi.open();
+  inContentDrawerApi.setState({ class: 'w-full', placement: 'right' }).open();
 }
 
 function openAutoHeightDrawer() {
@@ -72,24 +68,25 @@ function openDynamicDrawer() {
 }
 
 function handleUpdateTitle() {
-  dynamicDrawerApi.setState({ title: '外部动态标题' });
-  dynamicDrawerApi.open();
+  dynamicDrawerApi.setState({ title: '外部动态标题' }).open();
 }
 
 function openSharedDrawer() {
-  sharedDrawerApi.setData({
-    content: '外部传递的数据 content',
-    payload: '外部传递的数据 payload',
-  });
-  sharedDrawerApi.open();
+  sharedDrawerApi
+    .setData({
+      content: '外部传递的数据 content',
+      payload: '外部传递的数据 payload',
+    })
+    .open();
 }
 
 function openFormDrawer() {
-  formDrawerApi.setData({
-    // 表单值
-    values: { field1: 'abc', field2: '123' },
-  });
-  formDrawerApi.open();
+  formDrawerApi
+    .setData({
+      // 表单值
+      values: { field1: 'abc', field2: '123' },
+    })
+    .open();
 }
 </script>
 
diff --git a/playground/src/views/examples/modal/index.vue b/playground/src/views/examples/modal/index.vue
index 4176f14e..7c6cdf48 100644
--- a/playground/src/views/examples/modal/index.vue
+++ b/playground/src/views/examples/modal/index.vue
@@ -63,24 +63,25 @@ function openDynamicModal() {
 }
 
 function openSharedModal() {
-  sharedModalApi.setData({
-    content: '外部传递的数据 content',
-    payload: '外部传递的数据 payload',
-  });
-  sharedModalApi.open();
+  sharedModalApi
+    .setData({
+      content: '外部传递的数据 content',
+      payload: '外部传递的数据 payload',
+    })
+    .open();
 }
 
 function handleUpdateTitle() {
-  dynamicModalApi.setState({ title: '外部动态标题' });
-  dynamicModalApi.open();
+  dynamicModalApi.setState({ title: '外部动态标题' }).open();
 }
 
 function openFormModal() {
-  formModalApi.setData({
-    // 表单值
-    values: { field1: 'abc' },
-  });
-  formModalApi.open();
+  formModalApi
+    .setData({
+      // 表单值
+      values: { field1: 'abc' },
+    })
+    .open();
 }
 </script>
 

From 467689525f688f719142dc6181caff8c720ed1ad Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Sat, 11 Jan 2025 12:12:50 +0800
Subject: [PATCH 3/7] perf: add nested modal demo (#5353)

---
 playground/src/views/examples/modal/index.vue | 105 ++++++++++++------
 .../src/views/examples/modal/nested-demo.vue  |  24 ++++
 2 files changed, 95 insertions(+), 34 deletions(-)
 create mode 100644 playground/src/views/examples/modal/nested-demo.vue

diff --git a/playground/src/views/examples/modal/index.vue b/playground/src/views/examples/modal/index.vue
index 7c6cdf48..4b35f598 100644
--- a/playground/src/views/examples/modal/index.vue
+++ b/playground/src/views/examples/modal/index.vue
@@ -1,7 +1,7 @@
 <script lang="ts" setup>
 import { Page, useVbenModal } from '@vben/common-ui';
 
-import { Button, Card } from 'ant-design-vue';
+import { Button, Card, Flex } from 'ant-design-vue';
 
 import DocButton from '../doc-button.vue';
 import AutoHeightDemo from './auto-height-demo.vue';
@@ -10,6 +10,7 @@ import DragDemo from './drag-demo.vue';
 import DynamicDemo from './dynamic-demo.vue';
 import FormModalDemo from './form-modal-demo.vue';
 import InContentModalDemo from './in-content-demo.vue';
+import NestedDemo from './nested-demo.vue';
 import SharedDataDemo from './shared-data-demo.vue';
 
 const [BaseModal, baseModalApi] = useVbenModal({
@@ -42,6 +43,10 @@ const [FormModal, formModalApi] = useVbenModal({
   connectedComponent: FormModalDemo,
 });
 
+const [NestedModal, nestedModalApi] = useVbenModal({
+  connectedComponent: NestedDemo,
+});
+
 function openBaseModal() {
   baseModalApi.open();
 }
@@ -71,6 +76,10 @@ function openSharedModal() {
     .open();
 }
 
+function openNestedModal() {
+  nestedModalApi.open();
+}
+
 function handleUpdateTitle() {
   dynamicModalApi.setState({ title: '外部动态标题' }).open();
 }
@@ -101,44 +110,72 @@ function openFormModal() {
     <DynamicModal />
     <SharedDataModal />
     <FormModal />
-    <Card class="mb-4" title="基本使用">
-      <p class="mb-3">一个基础的弹窗示例</p>
-      <Button type="primary" @click="openBaseModal">打开弹窗</Button>
-    </Card>
+    <NestedModal />
+    <Flex wrap="wrap" class="w-full" gap="10">
+      <Card class="w-[300px]" title="基本使用">
+        <p>一个基础的弹窗示例</p>
+        <template #actions>
+          <Button type="primary" @click="openBaseModal">打开弹窗</Button>
+        </template>
+      </Card>
 
-    <Card class="mb-4" title="指定容器">
-      <p class="mb-3">在内容区域打开弹窗的示例</p>
-      <Button type="primary" @click="openInContentModal">打开弹窗</Button>
-    </Card>
+      <Card class="w-[300px]" title="指定容器">
+        <p>在内容区域打开弹窗的示例</p>
+        <template #actions>
+          <Button type="primary" @click="openInContentModal">打开弹窗</Button>
+        </template>
+      </Card>
 
-    <Card class="mb-4" title="内容高度自适应">
-      <p class="mb-3">可根据内容并自动调整高度</p>
-      <Button type="primary" @click="openAutoHeightModal">打开弹窗</Button>
-    </Card>
+      <Card class="w-[300px]" title="内容高度自适应">
+        <p>可根据内容并自动调整高度</p>
+        <template #actions>
+          <Button type="primary" @click="openAutoHeightModal">
+            打开弹窗
+          </Button>
+        </template>
+      </Card>
 
-    <Card class="mb-4" title="可拖拽示例">
-      <p class="mb-3">配置 draggable 可开启拖拽功能</p>
-      <Button type="primary" @click="openDragModal">打开弹窗</Button>
-    </Card>
+      <Card class="w-[300px]" title="可拖拽示例">
+        <p>配置 draggable 可开启拖拽功能</p>
+        <template #actions>
+          <Button type="primary" @click="openDragModal"> 打开弹窗 </Button>
+        </template>
+      </Card>
 
-    <Card class="mb-4" title="动态配置示例">
-      <p class="mb-3">通过 setState 动态调整弹窗数据</p>
-      <Button type="primary" @click="openDynamicModal">打开弹窗</Button>
-      <Button class="ml-2" type="primary" @click="handleUpdateTitle">
-        从外部修改标题并打开
-      </Button>
-    </Card>
+      <Card class="w-[300px]" title="动态配置示例">
+        <p>通过 setState 动态调整弹窗数据</p>
+        <template #extra>
+          <Button type="link" @click="openDynamicModal">打开弹窗</Button>
+        </template>
+        <template #actions>
+          <Button type="primary" @click="handleUpdateTitle">
+            外部修改标题并打开
+          </Button>
+        </template>
+      </Card>
 
-    <Card class="mb-4" title="内外数据共享示例">
-      <p class="mb-3">通过共享 sharedData 来进行数据交互</p>
-      <Button type="primary" @click="openSharedModal">
-        打开弹窗并传递数据
-      </Button>
-    </Card>
+      <Card class="w-[300px]" title="内外数据共享示例">
+        <p>通过共享 sharedData 来进行数据交互</p>
+        <template #actions>
+          <Button type="primary" @click="openSharedModal">
+            打开弹窗并传递数据
+          </Button>
+        </template>
+      </Card>
 
-    <Card class="mb-4" title="表单弹窗示例">
-      <p class="mb-3">弹窗与表单结合</p>
-      <Button type="primary" @click="openFormModal"> 打开弹窗 </Button>
-    </Card>
+      <Card class="w-[300px]" title="表单弹窗示例">
+        <p>弹窗与表单结合</p>
+        <template #actions>
+          <Button type="primary" @click="openFormModal"> 打开表单弹窗 </Button>
+        </template>
+      </Card>
+
+      <Card class="w-[300px]" title="嵌套弹窗示例">
+        <p>在已经打开的弹窗中再次打开弹窗</p>
+        <template #actions>
+          <Button type="primary" @click="openNestedModal">打开嵌套弹窗</Button>
+        </template>
+      </Card>
+    </Flex>
   </Page>
 </template>
diff --git a/playground/src/views/examples/modal/nested-demo.vue b/playground/src/views/examples/modal/nested-demo.vue
new file mode 100644
index 00000000..6251fd05
--- /dev/null
+++ b/playground/src/views/examples/modal/nested-demo.vue
@@ -0,0 +1,24 @@
+<script lang="ts" setup>
+import { useVbenModal } from '@vben/common-ui';
+
+import { Button } from 'ant-design-vue';
+
+import DragDemo from './drag-demo.vue';
+
+const [Modal] = useVbenModal({
+  destroyOnClose: true,
+});
+const [BaseModal, baseModalApi] = useVbenModal({
+  connectedComponent: DragDemo,
+});
+
+function openNestedModal() {
+  baseModalApi.open();
+}
+</script>
+<template>
+  <Modal title="嵌套弹窗示例">
+    <Button @click="openNestedModal" type="primary">打开子弹窗</Button>
+    <BaseModal />
+  </Modal>
+</template>

From a2637313f8feef384f985b317442baa5b5fca764 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Sat, 11 Jan 2025 17:35:59 +0800
Subject: [PATCH 4/7] feat: integrate new component `Tippy` with demo (#5355)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 添加新的工具提示组件Tippy
---
 apps/web-antd/src/bootstrap.ts                |   4 +
 apps/web-ele/src/bootstrap.ts                 |   4 +
 apps/web-naive/src/bootstrap.ts               |   4 +
 packages/effects/common-ui/package.json       |   5 +-
 .../effects/common-ui/src/components/index.ts |   1 +
 .../src/components/tippy/directive.ts         | 100 ++++++++
 .../common-ui/src/components/tippy/index.ts   |  66 +++++
 playground/src/bootstrap.ts                   |   4 +
 .../src/router/routes/modules/examples.ts     |   9 +
 playground/src/views/examples/tippy/index.vue | 226 ++++++++++++++++++
 pnpm-lock.yaml                                |  38 +++
 pnpm-workspace.yaml                           |   2 +
 12 files changed, 462 insertions(+), 1 deletion(-)
 create mode 100644 packages/effects/common-ui/src/components/tippy/directive.ts
 create mode 100644 packages/effects/common-ui/src/components/tippy/index.ts
 create mode 100644 playground/src/views/examples/tippy/index.vue

diff --git a/apps/web-antd/src/bootstrap.ts b/apps/web-antd/src/bootstrap.ts
index 963d1c7f..30ab9988 100644
--- a/apps/web-antd/src/bootstrap.ts
+++ b/apps/web-antd/src/bootstrap.ts
@@ -1,6 +1,7 @@
 import { createApp, watchEffect } from 'vue';
 
 import { registerAccessDirective } from '@vben/access';
+import { initTippy } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { initStores } from '@vben/stores';
 import '@vben/styles';
@@ -29,6 +30,9 @@ async function bootstrap(namespace: string) {
   // 安装权限指令
   registerAccessDirective(app);
 
+  // 初始化 tippy
+  initTippy(app);
+
   // 配置路由及路由守卫
   app.use(router);
 
diff --git a/apps/web-ele/src/bootstrap.ts b/apps/web-ele/src/bootstrap.ts
index ad1dce0f..9cdb0863 100644
--- a/apps/web-ele/src/bootstrap.ts
+++ b/apps/web-ele/src/bootstrap.ts
@@ -1,6 +1,7 @@
 import { createApp, watchEffect } from 'vue';
 
 import { registerAccessDirective } from '@vben/access';
+import { initTippy } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { initStores } from '@vben/stores';
 import '@vben/styles';
@@ -32,6 +33,9 @@ async function bootstrap(namespace: string) {
   // 安装权限指令
   registerAccessDirective(app);
 
+  // 初始化 tippy
+  initTippy(app);
+
   // 配置路由及路由守卫
   app.use(router);
 
diff --git a/apps/web-naive/src/bootstrap.ts b/apps/web-naive/src/bootstrap.ts
index 40416d82..d4172b28 100644
--- a/apps/web-naive/src/bootstrap.ts
+++ b/apps/web-naive/src/bootstrap.ts
@@ -1,6 +1,7 @@
 import { createApp, watchEffect } from 'vue';
 
 import { registerAccessDirective } from '@vben/access';
+import { initTippy } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { initStores } from '@vben/stores';
 import '@vben/styles';
@@ -28,6 +29,9 @@ async function bootstrap(namespace: string) {
   // 安装权限指令
   registerAccessDirective(app);
 
+  // 初始化 tippy
+  initTippy(app);
+
   // 配置路由及路由守卫
   app.use(router);
 
diff --git a/packages/effects/common-ui/package.json b/packages/effects/common-ui/package.json
index 83ca5b29..dc8ee773 100644
--- a/packages/effects/common-ui/package.json
+++ b/packages/effects/common-ui/package.json
@@ -22,6 +22,7 @@
   "dependencies": {
     "@vben-core/form-ui": "workspace:*",
     "@vben-core/popup-ui": "workspace:*",
+    "@vben-core/preferences": "workspace:*",
     "@vben-core/shadcn-ui": "workspace:*",
     "@vben-core/shared": "workspace:*",
     "@vben/constants": "workspace:*",
@@ -32,8 +33,10 @@
     "@vueuse/core": "catalog:",
     "@vueuse/integrations": "catalog:",
     "qrcode": "catalog:",
+    "tippy.js": "catalog:",
     "vue": "catalog:",
-    "vue-router": "catalog:"
+    "vue-router": "catalog:",
+    "vue-tippy": "catalog:"
   },
   "devDependencies": {
     "@types/qrcode": "catalog:"
diff --git a/packages/effects/common-ui/src/components/index.ts b/packages/effects/common-ui/src/components/index.ts
index 6bba5526..e1874de7 100644
--- a/packages/effects/common-ui/src/components/index.ts
+++ b/packages/effects/common-ui/src/components/index.ts
@@ -5,6 +5,7 @@ export * from './ellipsis-text';
 export * from './icon-picker';
 export * from './page';
 export * from './resize';
+export * from './tippy';
 export * from '@vben-core/form-ui';
 export * from '@vben-core/popup-ui';
 
diff --git a/packages/effects/common-ui/src/components/tippy/directive.ts b/packages/effects/common-ui/src/components/tippy/directive.ts
new file mode 100644
index 00000000..ed277d6a
--- /dev/null
+++ b/packages/effects/common-ui/src/components/tippy/directive.ts
@@ -0,0 +1,100 @@
+import type { ComputedRef, Directive } from 'vue';
+
+import { useTippy } from 'vue-tippy';
+
+export default function useTippyDirective(isDark: ComputedRef<boolean>) {
+  const directive: Directive = {
+    mounted(el, binding, vnode) {
+      const opts =
+        typeof binding.value === 'string'
+          ? { content: binding.value }
+          : binding.value || {};
+
+      const modifiers = Object.keys(binding.modifiers || {});
+      const placement = modifiers.find((modifier) => modifier !== 'arrow');
+      const withArrow = modifiers.includes('arrow');
+
+      if (placement) {
+        opts.placement = opts.placement || placement;
+      }
+
+      if (withArrow) {
+        opts.arrow = opts.arrow === undefined ? true : opts.arrow;
+      }
+
+      if (vnode.props && vnode.props.onTippyShow) {
+        opts.onShow = function (...args: any[]) {
+          return vnode.props?.onTippyShow(...args);
+        };
+      }
+
+      if (vnode.props && vnode.props.onTippyShown) {
+        opts.onShown = function (...args: any[]) {
+          return vnode.props?.onTippyShown(...args);
+        };
+      }
+
+      if (vnode.props && vnode.props.onTippyHidden) {
+        opts.onHidden = function (...args: any[]) {
+          return vnode.props?.onTippyHidden(...args);
+        };
+      }
+
+      if (vnode.props && vnode.props.onTippyHide) {
+        opts.onHide = function (...args: any[]) {
+          return vnode.props?.onTippyHide(...args);
+        };
+      }
+
+      if (vnode.props && vnode.props.onTippyMount) {
+        opts.onMount = function (...args: any[]) {
+          return vnode.props?.onTippyMount(...args);
+        };
+      }
+
+      if (el.getAttribute('title') && !opts.content) {
+        opts.content = el.getAttribute('title');
+        el.removeAttribute('title');
+      }
+
+      if (el.getAttribute('content') && !opts.content) {
+        opts.content = el.getAttribute('content');
+      }
+
+      useTippy(el, opts);
+    },
+    unmounted(el) {
+      if (el.$tippy) {
+        el.$tippy.destroy();
+      } else if (el._tippy) {
+        el._tippy.destroy();
+      }
+    },
+
+    updated(el, binding) {
+      const opts =
+        typeof binding.value === 'string'
+          ? { content: binding.value, theme: isDark.value ? '' : 'light' }
+          : Object.assign(
+              { theme: isDark.value ? '' : 'light' },
+              binding.value,
+            );
+
+      if (el.getAttribute('title') && !opts.content) {
+        opts.content = el.getAttribute('title');
+        el.removeAttribute('title');
+      }
+
+      if (el.getAttribute('content') && !opts.content) {
+        opts.content = el.getAttribute('content');
+      }
+
+      if (el.$tippy) {
+        el.$tippy.setProps(opts || {});
+      } else if (el._tippy) {
+        el._tippy.setProps(opts || {});
+      }
+    },
+  };
+  return directive;
+}
diff --git a/packages/effects/common-ui/src/components/tippy/index.ts b/packages/effects/common-ui/src/components/tippy/index.ts
new file mode 100644
index 00000000..344a7bda
--- /dev/null
+++ b/packages/effects/common-ui/src/components/tippy/index.ts
@@ -0,0 +1,66 @@
+import type { DefaultProps, Props } from 'tippy.js';
+
+import type { App, SetupContext } from 'vue';
+
+import { h, watchEffect } from 'vue';
+import { setDefaultProps, Tippy as TippyComponent } from 'vue-tippy';
+
+import { usePreferences } from '@vben-core/preferences';
+
+import useTippyDirective from './directive';
+
+import 'tippy.js/dist/tippy.css';
+import 'tippy.js/themes/light.css';
+import 'tippy.js/animations/scale.css';
+import 'tippy.js/animations/scale-subtle.css';
+import 'tippy.js/animations/scale-extreme.css';
+import 'tippy.js/animations/shift-away.css';
+import 'tippy.js/animations/perspective.css';
+
+const { isDark } = usePreferences();
+export type TippyProps = Props & {
+  animation?:
+    | 'fade'
+    | 'perspective'
+    | 'scale'
+    | 'scale-extreme'
+    | 'scale-subtle'
+    | 'shift-away'
+    | boolean;
+  theme?: 'auto' | 'dark' | 'light';
+};
+
+export function initTippy(app: App<Element>, options?: DefaultProps) {
+  setDefaultProps({
+    allowHTML: true,
+    delay: [500, 200],
+    theme: isDark.value ? '' : 'light',
+    ...options,
+  });
+  if (!options || !Reflect.has(options, 'theme') || options.theme === 'auto') {
+    watchEffect(() => {
+      setDefaultProps({ theme: isDark.value ? '' : 'light' });
+    });
+  }
+
+  app.directive('tippy', useTippyDirective(isDark));
+}
+
+export const Tippy = (props: any, { attrs, slots }: SetupContext) => {
+  let theme: string = (attrs.theme as string) ?? 'auto';
+  if (theme === 'auto') {
+    theme = isDark.value ? '' : 'light';
+  }
+  if (theme === 'dark') {
+    theme = '';
+  }
+  return h(
+    TippyComponent,
+    {
+      ...props,
+      ...attrs,
+      theme,
+    },
+    slots,
+  );
+};
diff --git a/playground/src/bootstrap.ts b/playground/src/bootstrap.ts
index 09b8cfa8..d82c8e5e 100644
--- a/playground/src/bootstrap.ts
+++ b/playground/src/bootstrap.ts
@@ -1,6 +1,7 @@
 import { createApp, watchEffect } from 'vue';
 
 import { registerAccessDirective } from '@vben/access';
+import { initTippy } from '@vben/common-ui';
 import { preferences } from '@vben/preferences';
 import { initStores } from '@vben/stores';
 import '@vben/styles';
@@ -30,6 +31,9 @@ async function bootstrap(namespace: string) {
   // 安装权限指令
   registerAccessDirective(app);
 
+  // 初始化 tippy
+  initTippy(app);
+
   // 配置路由及路由守卫
   app.use(router);
 
diff --git a/playground/src/router/routes/modules/examples.ts b/playground/src/router/routes/modules/examples.ts
index b02bc4da..79689787 100644
--- a/playground/src/router/routes/modules/examples.ts
+++ b/playground/src/router/routes/modules/examples.ts
@@ -248,6 +248,15 @@ const routes: RouteRecordRaw[] = [
           title: $t('examples.layout.col-page'),
         },
       },
+      {
+        name: 'TippyDemo',
+        path: '/examples/tippy',
+        component: () => import('#/views/examples/tippy/index.vue'),
+        meta: {
+          icon: 'material-symbols:chat-bubble',
+          title: 'Tippy',
+        },
+      },
     ],
   },
 ];
diff --git a/playground/src/views/examples/tippy/index.vue b/playground/src/views/examples/tippy/index.vue
new file mode 100644
index 00000000..d73c4559
--- /dev/null
+++ b/playground/src/views/examples/tippy/index.vue
@@ -0,0 +1,226 @@
+<script lang="ts" setup>
+import { computed, reactive } from 'vue';
+
+import { Page, Tippy } from '@vben/common-ui';
+
+import { Button, Card, Flex } from 'ant-design-vue';
+
+import { useVbenForm } from '#/adapter/form';
+
+const props = reactive({
+  animation: 'shift-away',
+  arrow: true,
+  content: '这是一个提示',
+  delay: 200,
+  duration: 200,
+  followCursor: '',
+  hideOnClick: '',
+  maxWidth: 'none',
+  placement: 'top',
+  theme: 'dark',
+});
+
+const tippyProps = computed(() => {
+  return {
+    ...props,
+    followCursor: ['', 'true'].includes(props.followCursor)
+      ? !!props.followCursor
+      : props.followCursor,
+    hideOnClick: ['', 'true'].includes(props.hideOnClick)
+      ? !!props.hideOnClick
+      : props.hideOnClick,
+  };
+});
+
+const [Form] = useVbenForm({
+  handleValuesChange(values) {
+    Object.assign(props, { ...values });
+  },
+  schema: [
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        options: [
+          { label: 'shift-away', value: 'shift-away' },
+          { label: 'scale', value: 'scale' },
+          { label: 'scale-extreme', value: 'scale-extreme' },
+          { label: 'scale-subtle', value: 'scale-subtle' },
+          { label: 'perspective', value: 'perspective' },
+          { label: 'fade', value: 'fade' },
+        ],
+      },
+      defaultValue: props.animation,
+      fieldName: 'animation',
+      label: '动画',
+    },
+    {
+      component: 'InputNumber',
+      defaultValue: props.duration,
+      fieldName: 'duration',
+      label: '动画时长',
+    },
+    {
+      component: 'Input',
+      defaultValue: props.content,
+      fieldName: 'content',
+      label: '内容',
+    },
+    {
+      component: 'Switch',
+      defaultValue: props.arrow,
+      fieldName: 'arrow',
+      label: '箭头',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        options: [
+          { label: '不跟随', value: '' },
+          { label: '完全跟随', value: 'true' },
+          { label: '仅横向', value: 'horizontal' },
+          { label: '仅纵向', value: 'vertical' },
+          { label: '仅初始', value: 'initial' },
+        ],
+      },
+      defaultValue: props.followCursor,
+      fieldName: 'followCursor',
+      label: '跟随指针',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        options: [
+          { label: '否', value: '' },
+          { label: '是', value: 'true' },
+          { label: '仅内部点击', value: 'toggle' },
+        ],
+      },
+      defaultValue: props.hideOnClick,
+      fieldName: 'hideOnClick',
+      label: '点击后隐藏',
+    },
+    {
+      component: 'InputNumber',
+      defaultValue: 100,
+      fieldName: 'delay',
+      label: '延时',
+    },
+
+    {
+      component: 'RadioGroup',
+      componentProps: {
+        options: [
+          { label: 'auto', value: 'auto' },
+          { label: 'dark', value: 'dark' },
+          { label: 'light', value: 'light' },
+        ],
+      },
+      defaultValue: props.theme,
+      fieldName: 'theme',
+      label: '主题',
+    },
+    {
+      component: 'Input',
+      componentProps: {
+        placeholder: 'none、200px',
+      },
+      defaultValue: props.maxWidth,
+      fieldName: 'maxWidth',
+      label: '最大宽度',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        options: [
+          { label: '顶部', value: 'top' },
+          { label: '顶左', value: 'top-start' },
+          { label: '顶右', value: 'top-end' },
+          { label: '底部', value: 'bottom' },
+          { label: '底左', value: 'bottom-start' },
+          { label: '底右', value: 'bottom-end' },
+          { label: '左侧', value: 'left' },
+          { label: '左上', value: 'left-start' },
+          { label: '左下', value: 'left-end' },
+          { label: '右侧', value: 'right' },
+          { label: '右上', value: 'right-start' },
+          { label: '右下', value: 'right-end' },
+        ],
+      },
+      defaultValue: 'top',
+      fieldName: 'placement',
+      label: '位置',
+    },
+  ],
+  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+});
+
+function goDoc() {
+  window.open('https://atomiks.github.io/tippyjs/v6/all-props/');
+}
+</script>
+<template>
+  <Page title="Tippy">
+    <template #description>
+      <div class="flex items-center">
+        <p>
+          Tippy
+          是一个轻量级的提示工具库，它可以用来创建各种交互式提示，如工具提示、引导提示等。
+        </p>
+        <Button type="link" size="small" @click="goDoc">查看文档</Button>
+      </div>
+    </template>
+    <Card title="指令形式使用">
+      <p class="mb-4">
+        指令形式使用比较简洁，直接在需要展示tooltip的组件上用v-tippy传递配置，适用于固定内容的工具提示。
+      </p>
+      <Flex warp="warp" gap="20">
+        <Button v-tippy="'这是一个提示，使用了默认的配置'">默认配置</Button>
+
+        <Button
+          v-tippy="{ theme: 'light', content: '这是一个提示，总是light主题' }"
+        >
+          指定主题
+        </Button>
+        <Button
+          v-tippy="{
+            theme: 'light',
+            content: '这个提示将在点燃组件100毫秒后激活',
+            delay: 100,
+          }"
+        >
+          指定延时
+        </Button>
+        <Button
+          v-tippy="{
+            content: '本提示的动画为`scale`',
+            animation: 'scale',
+          }"
+        >
+          指定动画
+        </Button>
+      </Flex>
+    </Card>
+    <Card title="组件形式使用" class="mt-4">
+      <div class="flex w-full justify-center">
+        <Tippy v-bind="tippyProps">
+          <Button>鼠标移到这个组件上来体验效果</Button>
+        </Tippy>
+      </div>
+
+      <Form class="mt-4" />
+      <template #actions>
+        <p
+          class="text-secondary-foreground hover:text-secondary-foreground cursor-default"
+        >
+          更多配置请
+          <Button type="link" size="small" @click="goDoc">查看文档</Button>
+          ，这里只列出了一些常用的配置
+        </p>
+      </template>
+    </Card>
+  </Page>
+</template>
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d3359584..1f59633b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -420,6 +420,9 @@ catalogs:
     theme-colors:
       specifier: ^0.1.0
       version: 0.1.0
+    tippy.js:
+      specifier: ^6.2.5
+      version: 6.3.7
     turbo:
       specifier: ^2.3.3
       version: 2.3.3
@@ -474,6 +477,9 @@ catalogs:
     vue-router:
       specifier: ^4.5.0
       version: 4.5.0
+    vue-tippy:
+      specifier: ^6.6.0
+      version: 6.6.0
     vue-tsc:
       specifier: 2.1.10
       version: 2.1.10
@@ -1488,6 +1494,9 @@ importers:
       '@vben-core/popup-ui':
         specifier: workspace:*
         version: link:../../@core/ui-kit/popup-ui
+      '@vben-core/preferences':
+        specifier: workspace:*
+        version: link:../../@core/preferences
       '@vben-core/shadcn-ui':
         specifier: workspace:*
         version: link:../../@core/ui-kit/shadcn-ui
@@ -1518,12 +1527,18 @@ importers:
       qrcode:
         specifier: 'catalog:'
         version: 1.5.4
+      tippy.js:
+        specifier: 'catalog:'
+        version: 6.3.7
       vue:
         specifier: ^3.5.13
         version: 3.5.13(typescript@5.7.3)
       vue-router:
         specifier: 'catalog:'
         version: 4.5.0(vue@3.5.13(typescript@5.7.3))
+      vue-tippy:
+        specifier: 'catalog:'
+        version: 6.6.0(vue@3.5.13(typescript@5.7.3))
     devDependencies:
       '@types/qrcode':
         specifier: 'catalog:'
@@ -3802,6 +3817,9 @@ packages:
   '@polka/url@1.0.0-next.28':
     resolution: {integrity: sha512-8LduaNlMZGwdZ6qWrKlfa+2M4gahzFkprZiAt2TF8uS0qQgBizKXpXURqvTJ4WtmupWxaLqjRb2UCTe72mu+Aw==}
 
+  '@popperjs/core@2.11.8':
+    resolution: {integrity: sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A==}
+
   '@redocly/ajv@8.11.2':
     resolution: {integrity: sha512-io1JpnwtIcvojV7QKDUSIuMN/ikdOUd1ReEnUnMKGfDVridQZ31J0MmIuqwuRjWDZfmvr+Q0MqCcfHM2gTivOg==}
 
@@ -8872,6 +8890,7 @@ packages:
   rollup-plugin-visualizer@5.13.1:
     resolution: {integrity: sha512-vMg8i6BprL8aFm9DKvL2c8AwS8324EgymYQo9o6E26wgVvwMhsJxS37aNL6ZsU7X9iAcMYwdME7gItLfG5fwJg==}
     engines: {node: '>=18'}
+    deprecated: Contains unintended breaking changes
     hasBin: true
     peerDependencies:
       rolldown: 1.x
@@ -9518,6 +9537,9 @@ packages:
     resolution: {integrity: sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==}
     engines: {node: '>=14.0.0'}
 
+  tippy.js@6.3.7:
+    resolution: {integrity: sha512-E1d3oP2emgJ9dRQZdf3Kkn0qJgI6ZLpyS5z6ZkY1DF3kaQaBsGZsndEpHwx+eC+tYM41HaSNvNtLx8tU57FzTQ==}
+
   tmp@0.0.33:
     resolution: {integrity: sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==}
     engines: {node: '>=0.6.0'}
@@ -10097,6 +10119,11 @@ packages:
     peerDependencies:
       vue: ^3.5.13
 
+  vue-tippy@6.6.0:
+    resolution: {integrity: sha512-ISRIUQDlcEP05K1nCbvlVcd8yuWS6S3dI91qD0A2slgtwwWjih8Fn9Aymq4SNaHQsdiP5+MLRPZVDxFjKMPgKA==}
+    peerDependencies:
+      vue: ^3.5.13
+
   vue-tsc@2.1.10:
     resolution: {integrity: sha512-RBNSfaaRHcN5uqVqJSZh++Gy/YUzryuv9u1aFWhsammDJXNtUiJMNoJ747lZcQ68wUQFx6E73y4FY3D8E7FGMA==}
     hasBin: true
@@ -12722,6 +12749,8 @@ snapshots:
 
   '@polka/url@1.0.0-next.28': {}
 
+  '@popperjs/core@2.11.8': {}
+
   '@redocly/ajv@8.11.2':
     dependencies:
       fast-deep-equal: 3.1.3
@@ -19034,6 +19063,10 @@ snapshots:
 
   tinyspy@3.0.2: {}
 
+  tippy.js@6.3.7:
+    dependencies:
+      '@popperjs/core': 2.11.8
+
   tmp@0.0.33:
     dependencies:
       os-tmpdir: 1.0.2
@@ -19728,6 +19761,11 @@ snapshots:
       '@vue/devtools-api': 6.6.4
       vue: 3.5.13(typescript@5.7.3)
 
+  vue-tippy@6.6.0(vue@3.5.13(typescript@5.7.3)):
+    dependencies:
+      tippy.js: 6.3.7
+      vue: 3.5.13(typescript@5.7.3)
+
   vue-tsc@2.1.10(typescript@5.7.3):
     dependencies:
       '@volar/typescript': 2.4.11
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 3a054ec6..3830d757 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -156,6 +156,7 @@ catalog:
   tailwindcss: ^3.4.17
   tailwindcss-animate: ^1.0.7
   theme-colors: ^0.1.0
+  tippy.js: ^6.2.5
   turbo: ^2.3.3
   typescript: ^5.7.3
   unbuild: ^3.2.0
@@ -175,6 +176,7 @@ catalog:
   vue-eslint-parser: ^9.4.3
   vue-i18n: ^11.0.1
   vue-router: ^4.5.0
+  vue-tippy: ^6.6.0
   vue-tsc: 2.1.10
   vxe-pc-ui: ^4.3.67
   vxe-table: 4.10.0

From cb9c8db5ba53f8d75230877791c6de2c45fa24dc Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Sat, 11 Jan 2025 20:42:38 +0800
Subject: [PATCH 5/7] feat: improve `tippy` demo (#5357)

---
 .../common-ui/src/components/tippy/index.ts   |  27 +-
 .../src/router/routes/modules/examples.ts     |   2 +-
 playground/src/views/examples/tippy/index.vue | 275 +++++++++++-------
 3 files changed, 191 insertions(+), 113 deletions(-)

diff --git a/packages/effects/common-ui/src/components/tippy/index.ts b/packages/effects/common-ui/src/components/tippy/index.ts
index 344a7bda..6080e582 100644
--- a/packages/effects/common-ui/src/components/tippy/index.ts
+++ b/packages/effects/common-ui/src/components/tippy/index.ts
@@ -10,25 +10,26 @@ import { usePreferences } from '@vben-core/preferences';
 import useTippyDirective from './directive';
 
 import 'tippy.js/dist/tippy.css';
+import 'tippy.js/dist/backdrop.css';
 import 'tippy.js/themes/light.css';
 import 'tippy.js/animations/scale.css';
-import 'tippy.js/animations/scale-subtle.css';
-import 'tippy.js/animations/scale-extreme.css';
+import 'tippy.js/animations/shift-toward.css';
 import 'tippy.js/animations/shift-away.css';
 import 'tippy.js/animations/perspective.css';
 
 const { isDark } = usePreferences();
-export type TippyProps = Props & {
-  animation?:
-    | 'fade'
-    | 'perspective'
-    | 'scale'
-    | 'scale-extreme'
-    | 'scale-subtle'
-    | 'shift-away'
-    | boolean;
-  theme?: 'auto' | 'dark' | 'light';
-};
+export type TippyProps = Partial<
+  Props & {
+    animation?:
+      | 'fade'
+      | 'perspective'
+      | 'scale'
+      | 'shift-away'
+      | 'shift-toward'
+      | boolean;
+    theme?: 'auto' | 'dark' | 'light';
+  }
+>;
 
 export function initTippy(app: App<Element>, options?: DefaultProps) {
   setDefaultProps({
diff --git a/playground/src/router/routes/modules/examples.ts b/playground/src/router/routes/modules/examples.ts
index 79689787..449bbc2c 100644
--- a/playground/src/router/routes/modules/examples.ts
+++ b/playground/src/router/routes/modules/examples.ts
@@ -253,7 +253,7 @@ const routes: RouteRecordRaw[] = [
         path: '/examples/tippy',
         component: () => import('#/views/examples/tippy/index.vue'),
         meta: {
-          icon: 'material-symbols:chat-bubble',
+          icon: 'mdi:message-settings-outline',
           title: 'Tippy',
         },
       },
diff --git a/playground/src/views/examples/tippy/index.vue b/playground/src/views/examples/tippy/index.vue
index d73c4559..ff7985dd 100644
--- a/playground/src/views/examples/tippy/index.vue
+++ b/playground/src/views/examples/tippy/index.vue
@@ -1,5 +1,7 @@
 <script lang="ts" setup>
-import { computed, reactive } from 'vue';
+import type { TippyProps } from '@vben/common-ui';
+
+import { reactive } from 'vue';
 
 import { Page, Tippy } from '@vben/common-ui';
 
@@ -7,129 +9,91 @@ import { Button, Card, Flex } from 'ant-design-vue';
 
 import { useVbenForm } from '#/adapter/form';
 
-const props = reactive({
+const tippyProps = reactive<TippyProps>({
   animation: 'shift-away',
   arrow: true,
   content: '这是一个提示',
-  delay: 200,
+  delay: [200, 200],
   duration: 200,
-  followCursor: '',
-  hideOnClick: '',
+  followCursor: false,
+  hideOnClick: false,
+  inertia: true,
   maxWidth: 'none',
   placement: 'top',
   theme: 'dark',
+  trigger: 'mouseenter focusin',
 });
 
-const tippyProps = computed(() => {
-  return {
-    ...props,
-    followCursor: ['', 'true'].includes(props.followCursor)
-      ? !!props.followCursor
-      : props.followCursor,
-    hideOnClick: ['', 'true'].includes(props.hideOnClick)
-      ? !!props.hideOnClick
-      : props.hideOnClick,
-  };
-});
+function parseBoolean(value: string) {
+  switch (value) {
+    case 'false': {
+      return false;
+    }
+    case 'true': {
+      return true;
+    }
+    default: {
+      return value;
+    }
+  }
+}
 
 const [Form] = useVbenForm({
   handleValuesChange(values) {
-    Object.assign(props, { ...values });
+    Object.assign(tippyProps, {
+      ...values,
+      delay: [values.delay1, values.delay2],
+      followCursor: parseBoolean(values.followCursor),
+      hideOnClick: parseBoolean(values.hideOnClick),
+      trigger: values.trigger.join(' '),
+    });
   },
   schema: [
-    {
-      component: 'Select',
-      componentProps: {
-        class: 'w-full',
-        options: [
-          { label: 'shift-away', value: 'shift-away' },
-          { label: 'scale', value: 'scale' },
-          { label: 'scale-extreme', value: 'scale-extreme' },
-          { label: 'scale-subtle', value: 'scale-subtle' },
-          { label: 'perspective', value: 'perspective' },
-          { label: 'fade', value: 'fade' },
-        ],
-      },
-      defaultValue: props.animation,
-      fieldName: 'animation',
-      label: '动画',
-    },
-    {
-      component: 'InputNumber',
-      defaultValue: props.duration,
-      fieldName: 'duration',
-      label: '动画时长',
-    },
-    {
-      component: 'Input',
-      defaultValue: props.content,
-      fieldName: 'content',
-      label: '内容',
-    },
-    {
-      component: 'Switch',
-      defaultValue: props.arrow,
-      fieldName: 'arrow',
-      label: '箭头',
-    },
-    {
-      component: 'Select',
-      componentProps: {
-        class: 'w-full',
-        options: [
-          { label: '不跟随', value: '' },
-          { label: '完全跟随', value: 'true' },
-          { label: '仅横向', value: 'horizontal' },
-          { label: '仅纵向', value: 'vertical' },
-          { label: '仅初始', value: 'initial' },
-        ],
-      },
-      defaultValue: props.followCursor,
-      fieldName: 'followCursor',
-      label: '跟随指针',
-    },
-    {
-      component: 'Select',
-      componentProps: {
-        class: 'w-full',
-        options: [
-          { label: '否', value: '' },
-          { label: '是', value: 'true' },
-          { label: '仅内部点击', value: 'toggle' },
-        ],
-      },
-      defaultValue: props.hideOnClick,
-      fieldName: 'hideOnClick',
-      label: '点击后隐藏',
-    },
-    {
-      component: 'InputNumber',
-      defaultValue: 100,
-      fieldName: 'delay',
-      label: '延时',
-    },
-
     {
       component: 'RadioGroup',
       componentProps: {
+        buttonStyle: 'solid',
+        class: 'w-full',
         options: [
-          { label: 'auto', value: 'auto' },
-          { label: 'dark', value: 'dark' },
-          { label: 'light', value: 'light' },
+          { label: '自动', value: 'auto' },
+          { label: '暗色', value: 'dark' },
+          { label: '亮色', value: 'light' },
         ],
+        optionType: 'button',
       },
-      defaultValue: props.theme,
+      defaultValue: tippyProps.theme,
       fieldName: 'theme',
       label: '主题',
     },
     {
-      component: 'Input',
+      component: 'Select',
       componentProps: {
-        placeholder: 'none、200px',
+        class: 'w-full',
+        options: [
+          { label: '向上滑入', value: 'shift-away' },
+          { label: '向下滑入', value: 'shift-toward' },
+          { label: '缩放', value: 'scale' },
+          { label: '透视', value: 'perspective' },
+          { label: '淡入', value: 'fade' },
+        ],
       },
-      defaultValue: props.maxWidth,
-      fieldName: 'maxWidth',
-      label: '最大宽度',
+      defaultValue: tippyProps.animation,
+      fieldName: 'animation',
+      label: '动画类型',
+    },
+    {
+      component: 'RadioGroup',
+      componentProps: {
+        buttonStyle: 'solid',
+        options: [
+          { label: '是', value: true },
+          { label: '否', value: false },
+        ],
+        optionType: 'button',
+      },
+      defaultValue: tippyProps.inertia,
+      fieldName: 'inertia',
+      label: '动画惯性',
     },
     {
       component: 'Select',
@@ -150,11 +114,124 @@ const [Form] = useVbenForm({
           { label: '右下', value: 'right-end' },
         ],
       },
-      defaultValue: 'top',
+      defaultValue: tippyProps.placement,
       fieldName: 'placement',
       label: '位置',
     },
+    {
+      component: 'InputNumber',
+      componentProps: {
+        addonAfter: '毫秒',
+      },
+      defaultValue: tippyProps.duration,
+      fieldName: 'duration',
+      label: '动画时长',
+    },
+    {
+      component: 'InputNumber',
+      componentProps: {
+        addonAfter: '毫秒',
+      },
+      defaultValue: 100,
+      fieldName: 'delay1',
+      label: '显示延时',
+    },
+    {
+      component: 'InputNumber',
+      componentProps: {
+        addonAfter: '毫秒',
+      },
+      defaultValue: 100,
+      fieldName: 'delay2',
+      label: '隐藏延时',
+    },
+    {
+      component: 'Input',
+      defaultValue: tippyProps.content,
+      fieldName: 'content',
+      label: '内容',
+    },
+    {
+      component: 'RadioGroup',
+      componentProps: {
+        buttonStyle: 'solid',
+        options: [
+          { label: '是', value: true },
+          { label: '否', value: false },
+        ],
+        optionType: 'button',
+      },
+      defaultValue: tippyProps.arrow,
+      fieldName: 'arrow',
+      label: '指示箭头',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        options: [
+          { label: '不跟随', value: 'false' },
+          { label: '完全跟随', value: 'true' },
+          { label: '仅横向', value: 'horizontal' },
+          { label: '仅纵向', value: 'vertical' },
+          { label: '仅初始', value: 'initial' },
+        ],
+      },
+      defaultValue: tippyProps.followCursor?.toString(),
+      fieldName: 'followCursor',
+      label: '跟随指针',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        mode: 'multiple',
+        options: [
+          { label: '鼠标移入', value: 'mouseenter' },
+          { label: '被点击', value: 'click' },
+          { label: '获得焦点', value: 'focusin' },
+          { label: '无触发，仅手动', value: 'manual' },
+        ],
+      },
+      defaultValue: tippyProps.trigger?.split(' '),
+      fieldName: 'trigger',
+      label: '触发方式',
+    },
+    {
+      component: 'Select',
+      componentProps: {
+        class: 'w-full',
+        options: [
+          { label: '否', value: 'false' },
+          { label: '是', value: 'true' },
+          { label: '仅内部', value: 'toggle' },
+        ],
+      },
+      defaultValue: tippyProps.hideOnClick?.toString(),
+      dependencies: {
+        componentProps(_, formAction) {
+          return {
+            disabled: !formAction.values.trigger.includes('click'),
+          };
+        },
+        triggerFields: ['trigger'],
+      },
+      fieldName: 'hideOnClick',
+      help: '只有在触发方式为`click`时才有效',
+      label: '点击后隐藏',
+    },
+    {
+      component: 'Input',
+      componentProps: {
+        allowClear: true,
+        placeholder: 'none、200px',
+      },
+      defaultValue: tippyProps.maxWidth,
+      fieldName: 'maxWidth',
+      label: '最大宽度',
+    },
   ],
+  showDefaultActions: false,
   wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
 });
 

From 6719e2679f2f3a40222f5eda6a2b14fe0fb3d64f Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Sat, 11 Jan 2025 23:37:17 +0800
Subject: [PATCH 6/7] feat: popup component support overlay blur effect (#5359)

---
 docs/src/components/common-ui/vben-drawer.md  |  1 +
 docs/src/components/common-ui/vben-modal.md   |  1 +
 .../ui-kit/popup-ui/src/drawer/drawer.ts      |  6 ++++-
 .../ui-kit/popup-ui/src/drawer/drawer.vue     |  2 ++
 .../@core/ui-kit/popup-ui/src/modal/modal.ts  |  4 ++++
 .../@core/ui-kit/popup-ui/src/modal/modal.vue |  2 ++
 .../shadcn-ui/src/ui/dialog/DialogContent.vue |  8 ++++++-
 .../shadcn-ui/src/ui/sheet/SheetContent.vue   | 16 +++++++++++--
 .../src/views/examples/drawer/base-demo.vue   |  3 +++
 .../src/views/examples/drawer/index.vue       |  7 ++++++
 .../src/views/examples/modal/blur-demo.vue    | 23 +++++++++++++++++++
 playground/src/views/examples/modal/index.vue | 17 ++++++++++++++
 12 files changed, 86 insertions(+), 4 deletions(-)
 create mode 100644 playground/src/views/examples/modal/blur-demo.vue

diff --git a/docs/src/components/common-ui/vben-drawer.md b/docs/src/components/common-ui/vben-drawer.md
index 43cb9889..04420855 100644
--- a/docs/src/components/common-ui/vben-drawer.md
+++ b/docs/src/components/common-ui/vben-drawer.md
@@ -101,6 +101,7 @@ const [Drawer, drawerApi] = useVbenDrawer({
 | footerClass | modal底部区域的class | `string` | - |
 | headerClass | modal顶部区域的class | `string` | - |
 | zIndex | 抽屉的ZIndex层级 | `number` | `1000` |
+| overlayBlur | 遮罩模糊度 | `number` | - |
 
 ::: info appendToMain
 
diff --git a/docs/src/components/common-ui/vben-modal.md b/docs/src/components/common-ui/vben-modal.md
index 45204bff..f3e2a17b 100644
--- a/docs/src/components/common-ui/vben-modal.md
+++ b/docs/src/components/common-ui/vben-modal.md
@@ -111,6 +111,7 @@ const [Modal, modalApi] = useVbenModal({
 | headerClass | modal顶部区域的class | `string` | - |
 | bordered | 是否显示border | `boolean` | `false` |
 | zIndex | 弹窗的ZIndex层级 | `number` | `1000` |
+| overlayBlur | 遮罩模糊度 | `number` | - |
 
 ::: info appendToMain
 
diff --git a/packages/@core/ui-kit/popup-ui/src/drawer/drawer.ts b/packages/@core/ui-kit/popup-ui/src/drawer/drawer.ts
index d2825bd6..c43677d3 100644
--- a/packages/@core/ui-kit/popup-ui/src/drawer/drawer.ts
+++ b/packages/@core/ui-kit/popup-ui/src/drawer/drawer.ts
@@ -85,12 +85,16 @@ export interface DrawerProps {
    * 是否自动聚焦
    */
   openAutoFocus?: boolean;
+  /**
+   * 弹窗遮罩模糊效果
+   */
+  overlayBlur?: number;
+
   /**
    * 抽屉位置
    * @default right
    */
   placement?: DrawerPlacement;
-
   /**
    * 是否显示取消按钮
    * @default true
diff --git a/packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue b/packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue
index 30687bd3..1b1a4a50 100644
--- a/packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue
+++ b/packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue
@@ -68,6 +68,7 @@ const {
   loading: showLoading,
   modal,
   openAutoFocus,
+  overlayBlur,
   placement,
   showCancelButton,
   showConfirmButton,
@@ -140,6 +141,7 @@ const getAppendTo = computed(() => {
       :open="state?.isOpen"
       :side="placement"
       :z-index="zIndex"
+      :overlay-blur="overlayBlur"
       @close-auto-focus="handleFocusOutside"
       @closed="() => drawerApi?.onClosed()"
       @escape-key-down="escapeKeyDown"
diff --git a/packages/@core/ui-kit/popup-ui/src/modal/modal.ts b/packages/@core/ui-kit/popup-ui/src/modal/modal.ts
index e69019fb..14225e8c 100644
--- a/packages/@core/ui-kit/popup-ui/src/modal/modal.ts
+++ b/packages/@core/ui-kit/popup-ui/src/modal/modal.ts
@@ -99,6 +99,10 @@ export interface ModalProps {
    * 是否自动聚焦
    */
   openAutoFocus?: boolean;
+  /**
+   * 弹窗遮罩模糊效果
+   */
+  overlayBlur?: number;
   /**
    * 是否显示取消按钮
    * @default true
diff --git a/packages/@core/ui-kit/popup-ui/src/modal/modal.vue b/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
index 4e7d7ca7..ae02a245 100644
--- a/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
+++ b/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
@@ -77,6 +77,7 @@ const {
   loading: showLoading,
   modal,
   openAutoFocus,
+  overlayBlur,
   showCancelButton,
   showConfirmButton,
   title,
@@ -196,6 +197,7 @@ const getAppendTo = computed(() => {
       :open="state?.isOpen"
       :show-close="closable"
       :z-index="zIndex"
+      :overlay-blur="overlayBlur"
       close-class="top-3"
       @close-auto-focus="handleFocusOutside"
       @closed="() => modalApi?.onClosed()"
diff --git a/packages/@core/ui-kit/shadcn-ui/src/ui/dialog/DialogContent.vue b/packages/@core/ui-kit/shadcn-ui/src/ui/dialog/DialogContent.vue
index 67bf64a6..bf91f7e9 100644
--- a/packages/@core/ui-kit/shadcn-ui/src/ui/dialog/DialogContent.vue
+++ b/packages/@core/ui-kit/shadcn-ui/src/ui/dialog/DialogContent.vue
@@ -25,6 +25,7 @@ const props = withDefaults(
       closeClass?: ClassType;
       modal?: boolean;
       open?: boolean;
+      overlayBlur?: number;
       showClose?: boolean;
       zIndex?: number;
     }
@@ -82,7 +83,12 @@ defineExpose({
     <Transition name="fade">
       <DialogOverlay
         v-if="open && modal"
-        :style="{ zIndex, position }"
+        :style="{
+          zIndex,
+          position,
+          backdropFilter:
+            overlayBlur && overlayBlur > 0 ? `blur(${overlayBlur}px)` : 'none',
+        }"
         @click="() => emits('close')"
       />
     </Transition>
diff --git a/packages/@core/ui-kit/shadcn-ui/src/ui/sheet/SheetContent.vue b/packages/@core/ui-kit/shadcn-ui/src/ui/sheet/SheetContent.vue
index f8e22168..4ab6231c 100644
--- a/packages/@core/ui-kit/shadcn-ui/src/ui/sheet/SheetContent.vue
+++ b/packages/@core/ui-kit/shadcn-ui/src/ui/sheet/SheetContent.vue
@@ -17,6 +17,7 @@ interface SheetContentProps extends DialogContentProps {
   class?: any;
   modal?: boolean;
   open?: boolean;
+  overlayBlur?: number;
   side?: SheetVariants['side'];
   zIndex?: number;
 }
@@ -75,12 +76,23 @@ function onAnimationEnd(event: AnimationEvent) {
 <template>
   <DialogPortal :to="appendTo">
     <Transition name="fade">
-      <SheetOverlay v-if="open && modal" :style="{ zIndex, position }" />
+      <SheetOverlay
+        v-if="open && modal"
+        :style="{
+          zIndex,
+          position,
+          backdropFilter:
+            overlayBlur && overlayBlur > 0 ? `blur(${overlayBlur}px)` : 'none',
+        }"
+      />
     </Transition>
     <DialogContent
       ref="contentRef"
       :class="cn(sheetVariants({ side }), props.class)"
-      :style="{ zIndex, position }"
+      :style="{
+        zIndex,
+        position,
+      }"
       @animationend="onAnimationEnd"
       v-bind="{ ...forwarded, ...$attrs }"
     >
diff --git a/playground/src/views/examples/drawer/base-demo.vue b/playground/src/views/examples/drawer/base-demo.vue
index ffa5e390..11c65130 100644
--- a/playground/src/views/examples/drawer/base-demo.vue
+++ b/playground/src/views/examples/drawer/base-demo.vue
@@ -7,6 +7,9 @@ const [Drawer, drawerApi] = useVbenDrawer({
   onCancel() {
     drawerApi.close();
   },
+  onClosed() {
+    drawerApi.setState({ overlayBlur: 0, placement: 'right' });
+  },
   onConfirm() {
     message.info('onConfirm');
     // drawerApi.close();
diff --git a/playground/src/views/examples/drawer/index.vue b/playground/src/views/examples/drawer/index.vue
index d50aeb22..7773240d 100644
--- a/playground/src/views/examples/drawer/index.vue
+++ b/playground/src/views/examples/drawer/index.vue
@@ -45,6 +45,10 @@ function openBaseDrawer(placement: DrawerPlacement = 'right') {
   baseDrawerApi.setState({ placement }).open();
 }
 
+function openBlurDrawer() {
+  baseDrawerApi.setState({ overlayBlur: 5 }).open();
+}
+
 function openInContentDrawer(placement: DrawerPlacement = 'right') {
   const state: Partial<DrawerState> = { class: '', placement };
   if (placement === 'top') {
@@ -124,6 +128,9 @@ function openFormDrawer() {
       <Button class="mb-2 ml-2" type="primary" @click="openBaseDrawer('top')">
         顶部打开
       </Button>
+      <Button class="mb-2 ml-2" type="primary" @click="openBlurDrawer">
+        遮罩层模糊效果
+      </Button>
     </Card>
 
     <Card class="mb-4" title="在内容区域打开">
diff --git a/playground/src/views/examples/modal/blur-demo.vue b/playground/src/views/examples/modal/blur-demo.vue
new file mode 100644
index 00000000..432ce0da
--- /dev/null
+++ b/playground/src/views/examples/modal/blur-demo.vue
@@ -0,0 +1,23 @@
+<script lang="ts" setup>
+import { ref, watch } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { Slider } from 'ant-design-vue';
+
+const blur = ref(5);
+const [Modal, modalApi] = useVbenModal({
+  overlayBlur: blur.value,
+});
+watch(blur, (val) => {
+  modalApi.setState({
+    overlayBlur: val,
+  });
+});
+</script>
+<template>
+  <Modal title="遮罩层模糊">
+    <p>调整滑块来改变遮罩层模糊程度：{{ blur }}</p>
+    <Slider v-model:value="blur" :max="30" :min="0" />
+  </Modal>
+</template>
diff --git a/playground/src/views/examples/modal/index.vue b/playground/src/views/examples/modal/index.vue
index 4b35f598..8d26b8be 100644
--- a/playground/src/views/examples/modal/index.vue
+++ b/playground/src/views/examples/modal/index.vue
@@ -6,6 +6,7 @@ import { Button, Card, Flex } from 'ant-design-vue';
 import DocButton from '../doc-button.vue';
 import AutoHeightDemo from './auto-height-demo.vue';
 import BaseDemo from './base-demo.vue';
+import BlurDemo from './blur-demo.vue';
 import DragDemo from './drag-demo.vue';
 import DynamicDemo from './dynamic-demo.vue';
 import FormModalDemo from './form-modal-demo.vue';
@@ -47,6 +48,10 @@ const [NestedModal, nestedModalApi] = useVbenModal({
   connectedComponent: NestedDemo,
 });
 
+const [BlurModal, blurModalApi] = useVbenModal({
+  connectedComponent: BlurDemo,
+});
+
 function openBaseModal() {
   baseModalApi.open();
 }
@@ -80,6 +85,10 @@ function openNestedModal() {
   nestedModalApi.open();
 }
 
+function openBlurModal() {
+  blurModalApi.open();
+}
+
 function handleUpdateTitle() {
   dynamicModalApi.setState({ title: '外部动态标题' }).open();
 }
@@ -111,6 +120,7 @@ function openFormModal() {
     <SharedDataModal />
     <FormModal />
     <NestedModal />
+    <BlurModal />
     <Flex wrap="wrap" class="w-full" gap="10">
       <Card class="w-[300px]" title="基本使用">
         <p>一个基础的弹窗示例</p>
@@ -176,6 +186,13 @@ function openFormModal() {
           <Button type="primary" @click="openNestedModal">打开嵌套弹窗</Button>
         </template>
       </Card>
+
+      <Card class="w-[300px]" title="遮罩模糊示例">
+        <p>遮罩层应用类似毛玻璃的模糊效果</p>
+        <template #actions>
+          <Button type="primary" @click="openBlurModal">打开弹窗</Button>
+        </template>
+      </Card>
     </Flex>
   </Page>
 </template>

From b785bc5704e6299ec2e34b5839b40a2ea4d05401 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Sun, 12 Jan 2025 09:54:37 +0800
Subject: [PATCH 7/7] fix: useEcharts return invalid instance (#5360)

---
 .../effects/plugins/src/echarts/use-echarts.ts   | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/packages/effects/plugins/src/echarts/use-echarts.ts b/packages/effects/plugins/src/echarts/use-echarts.ts
index ec5786e8..d2e96ebb 100644
--- a/packages/effects/plugins/src/echarts/use-echarts.ts
+++ b/packages/effects/plugins/src/echarts/use-echarts.ts
@@ -2,6 +2,8 @@ import type { EChartsOption } from 'echarts';
 
 import type { Ref } from 'vue';
 
+import type { Nullable } from '@vben/types';
+
 import type EchartsUI from './echarts-ui.vue';
 
 import { computed, nextTick, watch } from 'vue';
@@ -50,7 +52,10 @@ function useEcharts(chartRef: Ref<EchartsUIType>) {
     return chartInstance;
   };
 
-  const renderEcharts = (options: EChartsOption, clear = true) => {
+  const renderEcharts = (
+    options: EChartsOption,
+    clear = true,
+  ): Promise<Nullable<echarts.ECharts>> => {
     cacheOptions = options;
     const currentOptions = {
       ...options,
@@ -58,9 +63,8 @@ function useEcharts(chartRef: Ref<EchartsUIType>) {
     };
     return new Promise((resolve) => {
       if (chartRef.value?.offsetHeight === 0) {
-        useTimeoutFn(() => {
-          renderEcharts(currentOptions);
-          resolve(null);
+        useTimeoutFn(async () => {
+          resolve(await renderEcharts(currentOptions));
         }, 30);
         return;
       }
@@ -72,7 +76,7 @@ function useEcharts(chartRef: Ref<EchartsUIType>) {
           }
           clear && chartInstance?.clear();
           chartInstance?.setOption(currentOptions);
-          resolve(null);
+          resolve(chartInstance);
         }, 30);
       });
     });
@@ -109,7 +113,7 @@ function useEcharts(chartRef: Ref<EchartsUIType>) {
   return {
     renderEcharts,
     resize,
-    chartInstance,
+    getChartInstance: () => chartInstance,
   };
 }