fix(image-viewer): fix z-index (#6107)

liweijie0812 · tdesign-bot · web-flow · commit 3db1009b006e · 2025-10-30T19:59:44.000+08:00
* fix(image-viewer):  fix z-index

* chore: remove debug code

* 更新 image-viewer.md

* 更新 image-viewer.tsx

* 更新 image-viewer.tsx

* 更新 image-viewer.md

* chore: stash changelog [ci skip]

---------

Co-authored-by: tdesign-bot &lt;tdesign@tencent.com&gt;
diff --git a/packages/components/image-viewer/_example-ts/album.vue b/packages/components/image-viewer/_example-ts/album.vue
@@ -1,6 +1,6 @@
 <template>
   <div :style="{ width: '240px', height: '240px' }" class="tdesign-demo-image-viewer__base">
-    <t-image-viewer v-model:visible="visible" :images="images" :title="title">
+    <t-image-viewer v-model:visible="visible" :images="images" :title="title" :z-index="10000">
       <template #trigger>
         <div class="tdesign-demo-image-viewer__ui-image">
           <img alt="test" :src="img1" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example-ts/albumIcons.vue b/packages/components/image-viewer/_example-ts/albumIcons.vue
@@ -5,6 +5,7 @@
       :title="title"
       :images="images"
       :index="index"
+      :z-index="10000"
       @index-change="onIndexChange"
     >
       <template #trigger>
diff --git a/packages/components/image-viewer/_example-ts/base.vue b/packages/components/image-viewer/_example-ts/base.vue
@@ -1,6 +1,6 @@
 <template>
   <div class="tdesign-demo-image-viewer__base">
-    <t-image-viewer :images="[img]"></t-image-viewer>
+    <t-image-viewer :images="[img]" :z-index="10000"></t-image-viewer>
   </div>
 </template>
 <script lang="ts" setup>
diff --git a/packages/components/image-viewer/_example-ts/block.vue b/packages/components/image-viewer/_example-ts/block.vue
@@ -1,7 +1,7 @@
 <template>
   <div>
     <div class="tdesign-demo-image-viewer__ui-image tdesign-demo-image-viewer__base">
-      <t-image-viewer v-model:visible="visible1" :images="images">
+      <t-image-viewer v-model:visible="visible1" :images="images" :z-index="10000">
         <template #trigger>
           <div class="tdesign-demo-image-viewer__ui-image">
             <img alt="test" :src="img" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example-ts/button.vue b/packages/components/image-viewer/_example-ts/button.vue
@@ -4,6 +4,7 @@
       v-model:visible="visible"
       :trigger="trigger"
       :images="['https://tdesign.gtimg.com/demo/demo-image-1.png']"
+      :z-index="10000"
     >
     </t-image-viewer>
   </div>
diff --git a/packages/components/image-viewer/_example-ts/error.vue b/packages/components/image-viewer/_example-ts/error.vue
@@ -10,7 +10,14 @@
           <div>图片无法显示</div>
         </div>
       </div>
-      <t-image-viewer v-else :visible="visible[index]" :images="images" :default-index="index" @close="onClose(index)">
+      <t-image-viewer
+        v-else
+        :visible="visible[index]"
+        :images="images"
+        :default-index="index"
+        :z-index="10000"
+        @close="onClose(index)"
+      >
         <template #trigger>
           <div class="tdesign-demo-image-viewer__ui-image tdesign-demo-image-viewer__base">
             <img alt="test" :src="image" class="tdesign-demo-image-viewer__ui-image--img" @error="onError(index)" />
diff --git a/packages/components/image-viewer/_example-ts/modeless.vue b/packages/components/image-viewer/_example-ts/modeless.vue
@@ -1,6 +1,6 @@
 <template>
   <div class="tdesign-demo-image-viewer__base">
-    <t-image-viewer draggable mode="modeless" :images="[img]"> </t-image-viewer>
+    <t-image-viewer draggable mode="modeless" :images="[img]" :z-index="10000"> </t-image-viewer>
   </div>
 </template>
 
diff --git a/packages/components/image-viewer/_example-ts/multiple.vue b/packages/components/image-viewer/_example-ts/multiple.vue
@@ -1,6 +1,6 @@
 <template>
   <div>
-    <t-image-viewer v-for="(img, index) in images" :key="img" :default-index="index" :images="images">
+    <t-image-viewer v-for="(img, index) in images" :key="img" :default-index="index" :images="images" :z-index="10000">
       <template #trigger="{ open }">
         <div class="tdesign-demo-image-viewer__ui-image tdesign-demo-image-viewer__base">
           <img alt="test" :src="img" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example-ts/svg.vue b/packages/components/image-viewer/_example-ts/svg.vue
@@ -1,7 +1,7 @@
 <template>
   <div>
     <div class="tdesign-demo-image-viewer__base">
-      <t-image-viewer :images="[img]">
+      <t-image-viewer :images="[img]" :z-index="10000">
         <template #trigger="{ open }">
           <div class="tdesign-demo-image-viewer__ui-image">
             <img alt="test" :src="img" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example/album.vue b/packages/components/image-viewer/_example/album.vue
@@ -1,6 +1,6 @@
 <template>
   <div :style="{ width: '240px', height: '240px' }" class="tdesign-demo-image-viewer__base">
-    <t-image-viewer v-model:visible="visible" :images="images" :title="title">
+    <t-image-viewer v-model:visible="visible" :images="images" :title="title" :z-index="10000">
       <template #trigger>
         <div class="tdesign-demo-image-viewer__ui-image">
           <img alt="test" :src="img1" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example/albumIcons.vue b/packages/components/image-viewer/_example/albumIcons.vue
@@ -5,6 +5,7 @@
       :title="title"
       :images="images"
       :index="index"
+      :z-index="10000"
       @index-change="onIndexChange"
     >
       <template #trigger>
diff --git a/packages/components/image-viewer/_example/base.vue b/packages/components/image-viewer/_example/base.vue
@@ -1,6 +1,6 @@
 <template>
   <div class="tdesign-demo-image-viewer__base">
-    <t-image-viewer :images="[img]"></t-image-viewer>
+    <t-image-viewer :images="[img]" :z-index="10000"></t-image-viewer>
   </div>
 </template>
 <script setup>
diff --git a/packages/components/image-viewer/_example/block.vue b/packages/components/image-viewer/_example/block.vue
@@ -1,7 +1,7 @@
 <template>
   <div>
     <div class="tdesign-demo-image-viewer__ui-image tdesign-demo-image-viewer__base">
-      <t-image-viewer v-model:visible="visible1" :images="images">
+      <t-image-viewer v-model:visible="visible1" :images="images" :z-index="10000">
         <template #trigger>
           <div class="tdesign-demo-image-viewer__ui-image">
             <img alt="test" :src="img" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example/button.vue b/packages/components/image-viewer/_example/button.vue
@@ -4,6 +4,7 @@
       v-model:visible="visible"
       :trigger="trigger"
       :images="['https://tdesign.gtimg.com/demo/demo-image-1.png']"
+      :z-index="10000"
     >
     </t-image-viewer>
   </div>
diff --git a/packages/components/image-viewer/_example/error.vue b/packages/components/image-viewer/_example/error.vue
@@ -10,7 +10,14 @@
           <div>图片无法显示</div>
         </div>
       </div>
-      <t-image-viewer v-else :visible="visible[index]" :images="images" :default-index="index" @close="onClose(index)">
+      <t-image-viewer
+        v-else
+        :visible="visible[index]"
+        :images="images"
+        :default-index="index"
+        :z-index="10000"
+        @close="onClose(index)"
+      >
         <template #trigger>
           <div class="tdesign-demo-image-viewer__ui-image tdesign-demo-image-viewer__base">
             <img alt="test" :src="image" class="tdesign-demo-image-viewer__ui-image--img" @error="onError(index)" />
diff --git a/packages/components/image-viewer/_example/modeless.vue b/packages/components/image-viewer/_example/modeless.vue
@@ -1,6 +1,6 @@
 <template>
   <div class="tdesign-demo-image-viewer__base">
-    <t-image-viewer draggable mode="modeless" :images="[img]"> </t-image-viewer>
+    <t-image-viewer draggable mode="modeless" :images="[img]" :z-index="10000"> </t-image-viewer>
   </div>
 </template>
 
diff --git a/packages/components/image-viewer/_example/multiple.vue b/packages/components/image-viewer/_example/multiple.vue
@@ -1,6 +1,6 @@
 <template>
   <div>
-    <t-image-viewer v-for="(img, index) in images" :key="img" :default-index="index" :images="images">
+    <t-image-viewer v-for="(img, index) in images" :key="img" :default-index="index" :images="images" :z-index="10000">
       <template #trigger="{ open }">
         <div class="tdesign-demo-image-viewer__ui-image tdesign-demo-image-viewer__base">
           <img alt="test" :src="img" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/_example/svg.vue b/packages/components/image-viewer/_example/svg.vue
@@ -1,7 +1,7 @@
 <template>
   <div>
     <div class="tdesign-demo-image-viewer__base">
-      <t-image-viewer :images="[img]">
+      <t-image-viewer :images="[img]" :z-index="10000">
         <template #trigger="{ open }">
           <div class="tdesign-demo-image-viewer__ui-image">
             <img alt="test" :src="img.mainImage" class="tdesign-demo-image-viewer__ui-image--img" />
diff --git a/packages/components/image-viewer/base/ImageViewerModal.tsx b/packages/components/image-viewer/base/ImageViewerModal.tsx
@@ -72,6 +72,7 @@ export default defineComponent({
         footer={() => (
           <div class={`${classPrefix.value}-image-viewer-mini__footer`}>
             <TImageViewerUtils
+              zIndex={props.zIndex}
               onZoomIn={props.onZoomIn}
               onZoomOut={props.onZoomOut}
               scale={props.scale}
diff --git a/packages/components/image-viewer/base/ImageViewerUtils.tsx b/packages/components/image-viewer/base/ImageViewerUtils.tsx
@@ -10,6 +10,7 @@ import { largeNumberToFixed } from '@tdesign/common-js/input-number/large-number
 export default defineComponent({
   name: 'TImageViewerUtils',
   props: {
+    zIndex: Number,
     scale: Number,
     onRotate: Function as PropType<() => void>,
     onZoomIn: Function as PropType<() => void>,
@@ -41,6 +42,7 @@ export default defineComponent({
             placement="top"
             showArrow
             theme="default"
+            zIndex={props.zIndex}
           >
             <TImageViewerIcon onClick={props.onMirror} icon={() => <MirrorIcon size="medium" />} />
           </TToolTip>
@@ -51,6 +53,7 @@ export default defineComponent({
             placement="top"
             showArrow
             theme="default"
+            zIndex={props.zIndex}
           >
             <TImageViewerIcon onClick={props.onRotate} icon={() => <RotationIcon size="medium" />} />
           </TToolTip>
@@ -69,6 +72,7 @@ export default defineComponent({
             placement="top"
             showArrow
             theme="default"
+            zIndex={props.zIndex}
           >
             <div class={`${classPrefix.value}-image-viewer__modal-icon`}>
               <TImageViewerIcon icon={() => <ImageIcon size="medium" />} onClick={props.onReset} />
diff --git a/packages/components/image-viewer/image-viewer.md b/packages/components/image-viewer/image-viewer.md
@@ -24,7 +24,7 @@ trigger | String / Slot / Function | - | 触发图片预览的元素，可能是
 viewerScale | Object | - | 限制预览器缩放的最小宽度和最小高度，仅 `mode=modeless` 时有效。TS 类型：`ImageViewerScale` `interface ImageViewerScale { minWidth: number; minHeight: number }`。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/image-viewer/type.ts) | N
 visible | Boolean | false | 隐藏/显示预览。支持语法糖 `v-model` 或 `v-model:visible` | N
 defaultVisible | Boolean | false | 隐藏/显示预览。非受控属性 | N
-zIndex | Number | - | 层级，默认为 2000 | N
+zIndex | Number | - | 层级，默认为 2600 | N
 onClose | Function |  | TS 类型：`(context: { trigger: 'close-btn' \| 'overlay' \| 'esc'; e: MouseEvent \| KeyboardEvent }) => void`<br/>关闭时触发，事件参数包含触发关闭的来源：关闭按钮、遮罩层、ESC 键 | N
 onDownload | Function |  | TS 类型：`(url: string \| File) => void`<br/>自定义预览图片下载操作，url为图片链接 | N
 onIndexChange | Function |  | TS 类型：`(index: number, context: { trigger: 'prev' \| 'next' \| 'current' }) => void`<br/>预览图片切换时触发，`context.prev` 切换到上一张图片，`context.next` 切换到下一张图片 | N
diff --git a/packages/components/image-viewer/image-viewer.tsx b/packages/components/image-viewer/image-viewer.tsx
@@ -314,6 +314,7 @@ export default defineComponent({
                   )}
                   {renderCloseBtn()}
                   <TImageViewerUtils
+                    zIndex={zIndexValue.value + 1}
                     onZoomIn={onZoomIn}
                     onZoomOut={onZoomOut}
                     onMirror={onMirror}
diff --git a/packages/tdesign-vue-next/.changelog/pr-6107.md b/packages/tdesign-vue-next/.changelog/pr-6107.md
@@ -0,0 +1,7 @@
+---
+pr_number: 6107
+contributor: liweijie0812
+---
+
+- fix(ImageViewer): 修复 `zIndex` 过大导致工具栏的 tooltip 会被遮挡的问题 @liweijie0812 ([#6107](https://github.com/Tencent/tdesign-vue-next/pull/6107))
+- docs(ImageViewer): 优化示例页面操作栏被主题生成器遮挡的问题 @liweijie0812 ([#6107](https://github.com/Tencent/tdesign-vue-next/pull/6107))

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`:title="title"`
`6`	`6`	`:images="images"`
`7`	`7`	`:index="index"`
	`8`	`+ :z-index="10000"`
`8`	`9`	`@index-change="onIndexChange"`
`9`	`10`	`>`
`10`	`11`	`<template #trigger>`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`	`v-model:visible="visible"`
`5`	`5`	`:trigger="trigger"`
`6`	`6`	`:images="['https://tdesign.gtimg.com/demo/demo-image-1.png']"`
	`7`	`+ :z-index="10000"`
`7`	`8`	`>`
`8`	`9`	`</t-image-viewer>`
`9`	`10`	`</div>`