From d0da14ac81ab82666b30b53f3df61cf81b3c1a6f Mon Sep 17 00:00:00 2001
From: dogle <15707274049@163.com>
Date: Wed, 21 Oct 2026 15:50:15 +0800
Subject: [PATCH 1/2] fix: disable group preview when preview is false or null

---
 src/Image.tsx               | 10 ++++----
 src/PreviewGroup.tsx        | 48 +++++++++++++++++++++----------------
 src/context.ts              |  1 +
 tests/previewGroup.test.tsx | 25 +++++++++++++++++++
 4 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/src/Image.tsx b/src/Image.tsx
index 30ab9ce1..cf9f67f7 100644
--- a/src/Image.tsx
+++ b/src/Image.tsx
@@ -43,8 +43,10 @@ export interface PreviewConfig extends Omit<InternalPreviewConfig, 'countRender'
 
 export type SemanticName = 'root' | 'image' | 'cover';
 
-export interface ImageProps
-  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder' | 'onClick' | 'onKeyDown'> {
+export interface ImageProps extends Omit<
+  React.ImgHTMLAttributes<HTMLImageElement>,
+  'placeholder' | 'onClick' | 'onKeyDown'
+> {
   // Misc
   prefixCls?: string;
   previewPrefixCls?: string;
@@ -116,7 +118,7 @@ const ImageInternal: CompoundedComponent<ImageProps> = props => {
   const groupContext = useContext(PreviewGroupContext);
 
   // ========================== Preview ===========================
-  const canPreview = !!preview;
+  const canPreview = !!preview && (!groupContext || groupContext.canPreview);
 
   const {
     src: previewSrc,
@@ -243,7 +245,7 @@ const ImageInternal: CompoundedComponent<ImageProps> = props => {
         onClick={canPreview ? onPreview : onClick}
         role={canPreview ? 'button' : otherProps.role}
         tabIndex={canPreview && otherProps.tabIndex == null ? 0 : otherProps.tabIndex}
-        aria-label={canPreview ? otherProps['aria-label'] ?? alt : otherProps['aria-label']}
+        aria-label={canPreview ? (otherProps['aria-label'] ?? alt) : otherProps['aria-label']}
         onKeyDown={onPreviewKeyDown}
         style={{
           width,
diff --git a/src/PreviewGroup.tsx b/src/PreviewGroup.tsx
index 519e9080..b9f8d838 100644
--- a/src/PreviewGroup.tsx
+++ b/src/PreviewGroup.tsx
@@ -55,6 +55,8 @@ const Group: React.FC<PreviewGroupProps> = ({
     ...restProps
   } = preview && typeof preview === 'object' ? preview : ({} as GroupPreviewConfig);
 
+  const canPreview = preview !== false && preview !== null;
+
   // ========================== Items ===========================
   const [mergedItems, register, fromItems] = usePreviewItems(items);
 
@@ -80,6 +82,10 @@ const Group: React.FC<PreviewGroupProps> = ({
 
   const onPreviewFromImage = React.useCallback<OnGroupPreview>(
     (id, imageSrc, mouseX, mouseY) => {
+      if (!canPreview) {
+        return;
+      }
+
       const index = fromItems
         ? mergedItems.findIndex(item => item.data.src === imageSrc)
         : mergedItems.findIndex(item => item.id === id);
@@ -91,7 +97,7 @@ const Group: React.FC<PreviewGroupProps> = ({
 
       setKeepOpenIndex(true);
     },
-    [mergedItems, fromItems],
+    [canPreview, mergedItems, fromItems],
   );
 
   // Reset current when reopen
@@ -119,31 +125,33 @@ const Group: React.FC<PreviewGroupProps> = ({
 
   // ========================= Context ==========================
   const previewGroupContext = React.useMemo(
-    () => ({ register, onPreview: onPreviewFromImage }),
-    [register, onPreviewFromImage],
+    () => ({ register, onPreview: onPreviewFromImage, canPreview }),
+    [register, onPreviewFromImage, canPreview],
   );
 
   // ========================== Render ==========================
   return (
     <PreviewGroupContext.Provider value={previewGroupContext}>
       {children}
-      <Preview
-        aria-hidden={!isShowPreview}
-        open={isShowPreview}
-        prefixCls={previewPrefixCls}
-        onClose={onPreviewClose}
-        mousePosition={mousePosition}
-        imgCommonProps={imgCommonProps}
-        src={src}
-        fallback={fallback}
-        icons={icons}
-        current={current}
-        count={mergedItems.length}
-        onChange={onInternalChange}
-        {...restProps}
-        classNames={classNames?.popup}
-        styles={styles?.popup}
-      />
+      {canPreview && (
+        <Preview
+          aria-hidden={!isShowPreview}
+          open={isShowPreview}
+          prefixCls={previewPrefixCls}
+          onClose={onPreviewClose}
+          mousePosition={mousePosition}
+          imgCommonProps={imgCommonProps}
+          src={src}
+          fallback={fallback}
+          icons={icons}
+          current={current}
+          count={mergedItems.length}
+          onChange={onInternalChange}
+          {...restProps}
+          classNames={classNames?.popup}
+          styles={styles?.popup}
+        />
+      )}
     </PreviewGroupContext.Provider>
   );
 };
diff --git a/src/context.ts b/src/context.ts
index 030627ff..68305b60 100644
--- a/src/context.ts
+++ b/src/context.ts
@@ -4,6 +4,7 @@ import type { OnGroupPreview, RegisterImage } from './interface';
 export interface PreviewGroupContextProps {
   register: RegisterImage;
   onPreview: OnGroupPreview;
+  canPreview: boolean;
 }
 
 export const PreviewGroupContext = React.createContext<PreviewGroupContextProps | null>(null);
diff --git a/tests/previewGroup.test.tsx b/tests/previewGroup.test.tsx
index c13b6337..83b39cfc 100644
--- a/tests/previewGroup.test.tsx
+++ b/tests/previewGroup.test.tsx
@@ -108,6 +108,31 @@ describe('PreviewGroup', () => {
     expect(document.querySelector('.rc-image-preview')).toBeFalsy();
   });
 
+  it('group preview={false} should disable preview', () => {
+    const { container } = render(
+      <Image.PreviewGroup preview={false}>
+        <Image src="src1" />
+      </Image.PreviewGroup>,
+    );
+
+    fireEvent.click(container.querySelector('.rc-image'));
+
+    expect(document.querySelector('.rc-image-preview')).toBeFalsy();
+    expect(container.querySelector('.rc-image-cover')).toBeFalsy();
+  });
+
+  it('group preview={null} should disable preview', () => {
+    const { container } = render(
+      <Image.PreviewGroup preview={null as unknown as boolean}>
+        <Image src="src1" />
+      </Image.PreviewGroup>,
+    );
+
+    fireEvent.click(container.querySelector('.rc-image'));
+
+    expect(document.querySelector('.rc-image-preview')).toBeFalsy();
+  });
+
   it('Keyboard Enter should open preview from group image', () => {
     const { container } = render(
       <Image.PreviewGroup>

From ed90229f00fc477a4c1cf6d2d2ff567e6fe46a46 Mon Sep 17 00:00:00 2001
From: dogle <15707274049@163.com>
Date: Wed, 21 Oct 2026 16:36:37 +0800
Subject: [PATCH 2/2] fix: reset uncontrolled open state when group preview is
 disabled

---
 src/PreviewGroup.tsx        |  6 ++++++
 tests/previewGroup.test.tsx | 40 +++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/src/PreviewGroup.tsx b/src/PreviewGroup.tsx
index b9f8d838..0c6d70f2 100644
--- a/src/PreviewGroup.tsx
+++ b/src/PreviewGroup.tsx
@@ -111,6 +111,12 @@ const Group: React.FC<PreviewGroupProps> = ({
     }
   }, [isShowPreview]);
 
+  React.useEffect(() => {
+    if (!canPreview) {
+      setShowPreview(false);
+    }
+  }, [canPreview, setShowPreview]);
+
   // ========================== Events ==========================
   const onInternalChange: GroupPreviewConfig['onChange'] = (next, prev) => {
     setCurrent(next);
diff --git a/tests/previewGroup.test.tsx b/tests/previewGroup.test.tsx
index 83b39cfc..2089b10c 100644
--- a/tests/previewGroup.test.tsx
+++ b/tests/previewGroup.test.tsx
@@ -133,6 +133,46 @@ describe('PreviewGroup', () => {
     expect(document.querySelector('.rc-image-preview')).toBeFalsy();
   });
 
+  it('should not reopen preview after disable and re-enable', () => {
+    const { container, rerender } = render(
+      <Image.PreviewGroup>
+        <Image src="src1" />
+      </Image.PreviewGroup>,
+    );
+
+    fireEvent.click(container.querySelector('.rc-image'));
+    act(() => {
+      jest.runAllTimers();
+    });
+    expect(document.querySelector('.rc-image-preview')).toBeTruthy();
+
+    rerender(
+      <Image.PreviewGroup preview={false}>
+        <Image src="src1" />
+      </Image.PreviewGroup>,
+    );
+    act(() => {
+      jest.runAllTimers();
+    });
+    expect(document.querySelector('.rc-image-preview')).toBeFalsy();
+
+    rerender(
+      <Image.PreviewGroup>
+        <Image src="src1" />
+      </Image.PreviewGroup>,
+    );
+    act(() => {
+      jest.runAllTimers();
+    });
+    expect(document.querySelector('.rc-image-preview')).toBeFalsy();
+
+    fireEvent.click(container.querySelector('.rc-image'));
+    act(() => {
+      jest.runAllTimers();
+    });
+    expect(document.querySelector('.rc-image-preview')).toBeTruthy();
+  });
+
   it('Keyboard Enter should open preview from group image', () => {
     const { container } = render(
       <Image.PreviewGroup>