From e05f28613d81f7afcacc0782618225f18c9defc3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=AB=98=E8=89=B3=E5=85=B5?= <yanbing.gao@aliyun.com>
Date: Wed, 8 Apr 2026 16:33:08 +0800
Subject: [PATCH] feat: support preview mask closable

---
 README.md              |  2 ++
 src/Preview/index.tsx  |  4 +++-
 tests/preview.test.tsx | 27 +++++++++++++++++++++++++++
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 56c3203e..1874d079 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,7 @@ export default () => (
 | --- | --- | --- | --- |
 | open | boolean | - | Whether the preview is open or not |
 | closeIcon | React.ReactNode | - | Custom close icon |
+| maskClosable | boolean | true | Whether to close preview on clicking mask |
 | src | string | - | Customize preview src |
 | movable | boolean | true | Enable drag |
 | scaleStep | number | 0.5 | The number to which the scale is increased or decreased |
@@ -114,6 +115,7 @@ export default () => (
 | movable | boolean | true | Enable drag |
 | current | number | - | Current index |
 | closeIcon | React.ReactNode | - | Custom close icon |
+| maskClosable | boolean | true | Whether to close preview on clicking mask |
 | scaleStep | number | 0.5 | The number to which the scale is increased or decreased |
 | minScale | number | 1 | Min scale |
 | maxScale | number | 50 | Max scale |
diff --git a/src/Preview/index.tsx b/src/Preview/index.tsx
index 065fdb13..b27d80e0 100644
--- a/src/Preview/index.tsx
+++ b/src/Preview/index.tsx
@@ -87,6 +87,7 @@ export interface InternalPreviewConfig {
   open?: boolean;
   getContainer?: PortalProps['getContainer'];
   zIndex?: number;
+  maskClosable?: boolean;
   afterOpenChange?: (open: boolean) => void;
 
   // Operation
@@ -174,6 +175,7 @@ const Preview: React.FC<PreviewProps> = props => {
     onClose,
     open,
     afterOpenChange,
+    maskClosable = true,
     icons = {},
     closeIcon,
     getContainer,
@@ -450,7 +452,7 @@ const Preview: React.FC<PreviewProps> = props => {
               <div
                 className={clsx(`${prefixCls}-mask`, classNames.mask)}
                 style={styles.mask}
-                onClick={onClose}
+                onClick={maskClosable ? onClose : undefined}
               />
 
               {/* Body */}
diff --git a/tests/preview.test.tsx b/tests/preview.test.tsx
index f81744c6..3a8250a5 100644
--- a/tests/preview.test.tsx
+++ b/tests/preview.test.tsx
@@ -101,6 +101,33 @@ describe('Preview', () => {
     expect(onPreviewCloseMock).toHaveBeenCalledWith(false);
   });
 
+  it('maskClosable should control mask close behavior only', () => {
+    const onPreviewOpenChange = jest.fn();
+    const { container } = render(
+      <Image
+        src="https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
+        preview={{
+          maskClosable: false,
+          onOpenChange: onPreviewOpenChange,
+        }}
+      />,
+    );
+
+    fireEvent.click(container.querySelector('.rc-image'));
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    onPreviewOpenChange.mockReset();
+
+    fireEvent.click(document.querySelector('.rc-image-preview-mask'));
+    expect(document.querySelector('.rc-image-preview')).toBeTruthy();
+    expect(onPreviewOpenChange).not.toHaveBeenCalled();
+
+    fireEvent.click(document.querySelector('.rc-image-preview-close'));
+    expect(onPreviewOpenChange).toHaveBeenCalledWith(false);
+  });
+
   it('Unmount', () => {
     const { container, unmount } = render(
       <Image src="https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png" />,