From 4e4ffc439cd2f035481a7f5cdc5b93b7e593d2ae Mon Sep 17 00:00:00 2001
From: dullathanol <327533967@qq.com>
Date: Tue, 7 Apr 2026 11:41:39 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=94=AF=E6=8C=81=20overflow=20?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E4=BB=A5=E5=85=81=E8=AE=B8=E6=8B=96=E6=8B=BD?=
 =?UTF-8?q?=E8=B6=85=E5=87=BA=E5=8F=AF=E8=A7=86=E5=8C=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/src/components/common-ui/vben-modal.md                | 3 ++-
 packages/@core/ui-kit/popup-ui/src/modal/modal-api.ts      | 1 +
 packages/@core/ui-kit/popup-ui/src/modal/modal.ts          | 5 +++++
 packages/@core/ui-kit/popup-ui/src/modal/modal.vue         | 2 ++
 .../@core/ui-kit/popup-ui/src/modal/use-modal-draggable.ts | 7 +++++--
 5 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/src/components/common-ui/vben-modal.md b/docs/src/components/common-ui/vben-modal.md
index 4d99f59f4..65c2912d4 100644
--- a/docs/src/components/common-ui/vben-modal.md
+++ b/docs/src/components/common-ui/vben-modal.md
@@ -34,7 +34,7 @@ Modal 内的内容一般业务中，会比较复杂，所以我们可以将 moda
 
 ## 开启拖拽
 
-通过 `draggable` 参数，可开启拖拽功能。
+通过 `draggable` 参数，可开启拖拽功能。若需要拖动范围超出可视区，可设置 `overflow: true`（需已开启 `draggable`）。
 
 <DemoPreview dir="demos/vben-modal/draggable" />
 
@@ -101,6 +101,7 @@ const [Modal, modalApi] = useVbenModal({
 | fullscreen | 全屏显示 | `boolean` | `false` |
 | fullscreenButton | 显示全屏按钮 | `boolean` | `true` |
 | draggable | 可拖拽 | `boolean` | `false` |
+| overflow | 拖动范围可以超出可视区 | `boolean` | `false` |
 | closable | 显示关闭按钮 | `boolean` | `true` |
 | centered | 居中显示 | `boolean` | `false` |
 | modal | 显示遮罩 | `boolean` | `true` |
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 650155871..9bfda4e90 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
@@ -46,6 +46,7 @@ export class ModalApi {
       contentClass: '',
       destroyOnClose: true,
       draggable: false,
+      overflow: false,
       footer: true,
       footerClass: '',
       fullscreen: false,
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 4debaff4b..0ce29412b 100644
--- a/packages/@core/ui-kit/popup-ui/src/modal/modal.ts
+++ b/packages/@core/ui-kit/popup-ui/src/modal/modal.ts
@@ -110,6 +110,11 @@ export interface ModalProps {
    * 是否自动聚焦
    */
   openAutoFocus?: boolean;
+  /**
+   * 拖动范围是否可以超出可视区
+   * @default false
+   */
+  overflow?: boolean;
   /**
    * 弹窗遮罩模糊效果
    */
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 a01871c65..1947b2254 100644
--- a/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
+++ b/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
@@ -81,6 +81,7 @@ const {
   description,
   destroyOnClose,
   draggable,
+  overflow,
   footer: showFooter,
   footerClass,
   fullscreen,
@@ -122,6 +123,7 @@ const { dragging, transform } = useModalDraggable(
   shouldDraggable,
   getAppendTo,
   shouldCentered,
+  overflow,
 );
 
 const firstOpened = ref(false);
diff --git a/packages/@core/ui-kit/popup-ui/src/modal/use-modal-draggable.ts b/packages/@core/ui-kit/popup-ui/src/modal/use-modal-draggable.ts
index 84910b744..a7bcba555 100644
--- a/packages/@core/ui-kit/popup-ui/src/modal/use-modal-draggable.ts
+++ b/packages/@core/ui-kit/popup-ui/src/modal/use-modal-draggable.ts
@@ -15,6 +15,7 @@ export function useModalDraggable(
   draggable: ComputedRef<boolean>,
   containerSelector?: ComputedRef<string | undefined>,
   centered?: ComputedRef<boolean>,
+  overflow?: ComputedRef<boolean>,
 ) {
   const transform = reactive({
     offsetX: 0,
@@ -67,8 +68,10 @@ export function useModalDraggable(
       let moveX = offsetX + e.clientX - downX;
       let moveY = offsetY + e.clientY - downY;
 
-      moveX = Math.min(Math.max(moveX, minLeft), maxLeft);
-      moveY = Math.min(Math.max(moveY, minTop), maxTop);
+      if (!overflow?.value) {
+        moveX = Math.min(Math.max(moveX, minLeft), maxLeft);
+        moveY = Math.min(Math.max(moveY, minTop), maxTop);
+      }
 
       transform.offsetX = moveX;
       transform.offsetY = moveY;