Ant Design Image 嵌套 Modal 使用指南：弹框内嵌图片预览的完整实现与 z-index 原理

本篇围绕 Ant Design Image 组件的官方示例 nested（“嵌套在弹框当中使用”）展开，完整呈现三层嵌套 Modal 内嵌 Image 与 Image.PreviewGroup 的可用代码，并结合 components/image/index.tsx、components/_util/hooks/useZIndex.ts 等源码，讲清预览浮层在多层弹框中如何正确计算 z-index、如何合并 ConfigProvider 配置，以及哪些 preview 属性已废弃。

场景：为什么“嵌套在弹框中”值得单独做一个示例

弹框类组件（Modal、Drawer 等）都会提升自身 z-index，当弹框再嵌套弹框时，层级会逐层累加。此时若在弹框内部使用 Image 的点击预览（放大查看），预览浮层必须出现在最上层弹框之上，否则会出现“预览图被弹框遮罩盖住”的层级错乱问题。

官方把这个场景固化成了独立示例 nested.tsx，并在自动化测试 components/image/tests/index.test.tsx 中专门断言了“嵌套 Modal 下 z-index 应该正确”。本文以该示例为主体，拆解其结构与背后的实现。

完整示例代码

下面是 components/image/demo/nested.tsx 的完整代码，可直接复制到业务项目运行：

import React, { useState } from 'react';
import { Button, Divider, Image, Modal } from 'antd';

const App: React.FC = () => {
  const [show1, setShow1] = useState(false);
  const [show2, setShow2] = useState(false);
  const [show3, setShow3] = useState(false);
  return (
    <>
      <Button
        onClick={() => {
          setShow1(true);
        }}
      >
        showModal
      </Button>
      <Modal
        open={show1}
        afterOpenChange={(open) => {
          setShow1(open);
        }}
        onCancel={() => {
          setShow1(false);
        }}
        onOk={() => setShow1(false)}
      >
        <Button
          onClick={() => {
            setShow2(true);
          }}
        >
          test2
        </Button>
        <Modal
          open={show2}
          afterOpenChange={(open) => {
            setShow2(open);
          }}
          onCancel={() => {
            setShow2(false);
          }}
          onOk={() => setShow2(false)}
        >
          <Button
            onClick={() => {
              setShow3(true);
            }}
          >
            test3
          </Button>
          <Modal
            open={show3}
            afterOpenChange={(open) => {
              setShow3(open);
            }}
            onCancel={() => {
              setShow3(false);
            }}
            onOk={() => setShow3(false)}
          >
            <Image
              width={200}
              alt="svg image"
              src="https://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg"
            />
            <Divider />
            <Image.PreviewGroup
              preview={{
                onChange: (current, prev) =>
                  console.log(`current index: ${current}, prev index: ${prev}`),
              }}
            >
              <Image
                width={200}
                alt="svg image"
                src="https://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg"
              />
              <Image
                width={200}
                src="https://gw.alipayobjects.com/zos/antfincdn/aPkFc8Sj7n/method-draw-image.svg"
              />
            </Image.PreviewGroup>
          </Modal>
        </Modal>
      </Modal>
    </>
  );
};

export default App;

示例拆解：三层嵌套结构与两种预览形态

示例的交互链路是：点击按钮打开第一层 Modal，其中“test2”按钮打开第二层 Modal，再点“test3”打开第三层 Modal；最内层弹框里放置了两种图片预览形态：

1. 独立的 <Image>：默认开启点击预览，width={200} 控制缩略图宽度，alt 提供无障碍文本。点击后进入全屏预览浮层，支持缩放、旋转、关闭等默认操作。
2. <Image.PreviewGroup> 包裹两张 <Image>：组成一组轮播预览，点击任意一张可在同一浮层内左右切换；示例在 preview.onChange 中打印切换信息：

<Image.PreviewGroup
  preview={{
    onChange: (current, prev) =>
      console.log(`current index: ${current}, prev index: ${prev}`),
  }}
>

onChange 回调的参数是 current（当前索引）与 prev（上一次索引），适合用于埋点或状态同步。

每层 Modal 都遵循受控写法：open 受 state 控制，onCancel / onOk 负责关闭，afterOpenChange 在动画结束后同步状态（可用于清理 DOM）。

图片与预览配置：示例中用到的关键属性

示例用到的属性都定义在 components/image/index.tsx 的 ImageProps 中，该接口继承自底层 @rc-component/image 的 RcImageProps：

属性	说明
src	图片地址，必填
width / height	缩略图尺寸，示例中用 width={200}
alt	图片替代文本
fallback	图片加载失败时的兜底地址，可被 ConfigProvider 的 fallback 覆盖/兜底
preview	预览配置，false 关闭预览，对象形式可配置浮层

其中 fallback 的合并逻辑可在源码中看到：const mergedFallback: RcImageProps['fallback'] = fallback ?? contextFallback;（见 components/image/index.tsx 中 Image 组件的渲染部分），即组件自身 fallback 优先，否则回退到 ConfigProvider 全局配置。

preview 配置对象

preview 为对象时（PreviewConfig 类型），常用字段包括：open / onOpenChange（受控开关）、zIndex、getContainer（浮层挂载节点）、icons（自定义操作图标）、actionsRender（自定义工具栏）、mask（点击蒙层配置）等。在 components/image/hooks/usePreviewConfig.ts 中可以看到它对旧版 API 的归一化处理：

• visible → 归一为 open
• onVisibleChange → 包装为 onOpenChange（内部会转换参数顺序）
• toolbarRender → 归一为 actionsRender
• mask 传 ReactNode 时迁移为 cover，传布尔/对象时保留为蒙层配置

开发环境下使用这些旧属性会触发废弃警告，详见 components/image/hooks/usePreviewConfig.ts 中 devUseWarning('Image') 的告警列表（visible、onVisibleChange、maskClassName、rootClassName、toolbarRender 等）。新代码建议直接使用 open、onOpenChange、classNames.cover、classNames.root、actionsRender。

预览浮层的默认值合并

components/image/hooks/useMergedPreviewConfig.ts 负责把“组件自身的 preview 配置”与“ConfigProvider 传入的 image.preview 上下文配置”合并，并补齐默认值：

• motionName 固定为 fade 类过渡（getTransitionName(${prefixCls}-preview, 'fade')）；
• getContainer 未显式指定时回退到上下文 getPopupContainer；
• closeIcon 未指定时回退到上下文 closeIcon；
• zIndex 由 useZIndex('ImagePreview', previewConfig?.zIndex) 计算（见下一节）；
• 单独使用 <Image> 时（非 Group），默认会带上一个默认 cover 覆盖层。

Image.PreviewGroup 的包装实现在 components/image/PreviewGroup.tsx，它同样走 usePreviewConfig + useMergedPreviewConfig 流程，并按 direction（RTL/LTR）自动交换左右箭头图标，最终渲染底层的 RcImage.PreviewGroup。

核心原理：嵌套 Modal 下的 z-index 计算

示例能在三层 Modal 之上正确显示预览浮层，靠的是统一的 z-index 体系，实现在 components/_util/hooks/useZIndex.ts：

• 容器类组件（Modal、Drawer、Popover 等）：基础值为 token zIndexPopupBase（默认 1000）加容器偏移量 CONTAINER_OFFSET = 100；当存在父级容器（通过 ZIndexContext 传递父 z-index）时不再叠加基础值，而是在父级基础上累加，形成逐层递增；
• 消费类组件（Select 类、Dropdown、DatePicker、Menu、ImagePreview）：在父级基础上叠加消费偏移量，其中 ImagePreview 的偏移为 1。

据此可以推演示例的数值：zIndexPopupBase = 1000，三层 Modal 依次叠加 100 偏移得到 1100 → 1200 → 1300，最内层的 Image 预览浮层再叠加 ImagePreview 的偏移 1，最终为 1301。测试 components/image/tests/index.test.tsx 中 “Image.PreviewGroup preview in a nested modal where z-index Settings should be correct” 用例正是构造了三层 <Modal> 包裹 <Image> 与 <Image.PreviewGroup>，断言两者预览浮层的 zIndex 均为 1301，与上述推算一致。

需要注意：若用户通过 preview={{ zIndex: ... }} 显式指定了 z-index，会直接采用该值并跳过自动计算；同时开发环境下若自动算出的 z-index 超过 zIndexPopupBase + CONTAINER_MAX_OFFSET_WITH_CHILDREN，源码会给出 usage 级别告警，提示可能出现意外的层级覆盖。

测试覆盖：如何验证示例行为

仓库中与该示例直接相关的测试有两处：

1. components/image/tests/demo.test.ts：对全部 demo（含 nested）做快照渲染测试，快照见 components/image/tests/snapshots/demo.test.ts.snap 中 renders components/image/demo/nested.tsx correctly 条目，保证示例代码可稳定渲染；
2. components/image/tests/index.test.tsx：前述嵌套 Modal 下 z-index 的断言用例，保证预览浮层层级在多弹框场景的正确性。

如果你在自己项目中复现“预览被弹框遮挡”的问题，可以参照该测试的方式：打开控制台检查预览浮层节点的 z-index 是否低于最内层 Modal，再确认是否误传了过小的 preview.zIndex。

使用要点小结

• 在 Modal 等容器内使用 <Image> 无需手动处理层级，Ant Design 会通过 useZIndex('ImagePreview') 自动让预览浮层叠加在父容器之上；
• 一组图片请放入 Image.PreviewGroup，用 preview.onChange(current, prev) 监听切换；
• 需要自定义挂载节点时通过 preview.getContainer 指定，未指定时回退到 ConfigProvider 的 getPopupContainer 上下文；
• 避免使用已废弃的 visible / onVisibleChange / toolbarRender / rootClassName / maskClassName，迁移对照见 components/image/hooks/usePreviewConfig.ts 与 components/image/index.tsx 中 DeprecatedPreviewConfig 的类型注释；
• 更多 API 细节可参考官方文档 components/image/index.zh-CN.md。