企业官网建设流程全解析

• 前端
• UI组件
• 设计系统

ImagePreview（图片预览）是 vue-devui 组件库中面向"数据展示"场景的轻量级组件，它允许开发者通过v-d-image-preview指令对容器内的一张或多张图片进行全屏预览，并提供缩放、旋转、前后切换、拖拽等交互能力。读完本文，你将掌握该组件的四种配置参数（custom、disableDefault、zIndex、backDropZIndex）的正确用法，理解指令内部如何自动注入open/close方法、如何动态调整预览层级，并能从源码层面看懂整个预览窗口的渲染与关闭流程。

组件定位与使用场景

ImagePreview 的核心能力是"根据用户传入的图片进行预览展示，或对容器内图片进行预览"。在 vue-devui 中它属于「数据展示」类目（见 overview 功能清单），功能状态标记为完成度 100%。

它的典型使用场景包括：

• 图片列表（如相册、附件列表）点击某张图片后弹出大图预览；
• 详情页中内嵌的多张图片需要一键全屏查看；
• 需要自定义触发时机（如点击按钮而非图片本身）的预览场景。

与常规的"组件+props"写法不同，ImagePreview 以自定义指令为主体：把指令挂到任意容器元素上，指令会自动监听容器内<img>的点击事件并拉起预览窗口。这一设计让它在不侵入业务 DOM 结构的前提下即可生效。

基本用法：用 v-d-image-preview 指令预览容器内图片

在组件库完成安装后，v-d-image-preview指令即全局可用（安装逻辑见 image-preview/index.ts，通过app.directive('d-image-preview', ImagePreviewDirective)注册）。基本用法如下：

<template> <div v-d-image-preview class="devui-image-preview-demo"> <img v-for="src in imageList" :src="src" :key="src" /> </div> </template> <script> import { defineComponent, ref } from 'vue' export default defineComponent({ setup() { const _imageList = [ 'https://devui.design/components/assets/image1.png', 'https://devui.design/components/assets/image3.png' ] const imageList = ref(_imageList) return { imageList } } }) </script>

要点说明：

• 指令挂在容器 div上，而非单张<img>上；
• 预览时会收集容器内所有<img>的src作为可切换的图片列表，点击的那张作为预览起始图；
• 预览窗口内支持左右切换，底部工具栏会显示当前序号，格式为当前序号:总数（见 image-preview.tsx）。

从指令源码（image-preview-directive.ts）可以看到底层实现：mounted钩子中调用handleImgByEl(el)为容器绑定click事件；事件处理函数handleImg会先判断e.target的nodeName是否为img，再通过getImgByEl(el)收集全部图片地址：

function getImgByEl(el: HTMLElement): Array<string> { const urlList = [...el.querySelectorAll('img')].map((ele: HTMLImageElement) => ele.getAttribute('src') as string); return urlList; }

也就是说，只有点击到<img>元素时才会触发预览，点击容器其他区域不会误触发。对应的单元测试（image-preview.spec.ts）中验证了点击img后预览窗口（.devui-image-preview__main-image）会出现在 DOM 中，点击关闭按钮后移除。

自定义开启预览窗口：custom 与 disableDefault

有些业务场景下，预览不应由点击图片触发，而是由业务按钮（如"查看大图"、"预览"）统一打开。此时使用custom参数并配合disableDefault: true：

<template> <div v-d-image-preview="{ custom: image.custom, disableDefault: true }" class="devui-image-preview-demo" > <img v-for="src in imageList" :src="src" :key="src" /> </div> <d-button @click="open" class="btn">自定义</d-button> </template> <script> import { defineComponent, ref, reactive } from 'vue' export default defineComponent({ setup() { const _imageList = [ 'https://devui.design/components/assets/image1.png', 'https://devui.design/components/assets/image3.png' ] const imageList = ref(_imageList) const image = reactive({ custom: {}, imageList: _imageList }) function open() { image.custom.open() } return { imageList, image, open } } }) </script>

这段示例揭示了两个关键行为：

1. 指令会自动注入open/close方法到custom对象上。在指令的mounted钩子中，只要binding.value.custom是对象，就会执行：

custom.open = () => { const urlList = getImgByEl(el); mountedPreviewImages({ url: urlList?.[0], previewUrlList: urlList, zIndex: el?.zIndex, backDropZIndex: el?.backDropZIndex, }); }; custom.close = () => unmountedPreviewImages();

注意：custom.open默认以容器内第一张图片（urlList[0]）作为起始预览图。如果业务需要从指定图片开始预览，建议配合后续参数设计或通过调整容器内图片顺序实现。

2. disableDefault: true会关闭默认的点击触发。指令源码中，当disableDefault为真时直接return，不再执行handleImgByEl(el)绑定点击事件；而当值为false时则恢复绑定。这一动态切换逻辑在指令的updated钩子中通过对比disableDefault与oldValue.disableDefault实现：

if (disableDefault !== oldDisableDefault) { if (disableDefault) { removeHandle(el); } else { handleImgByEl(el); } }

对应的测试用例（image-preview.spec.ts）分别验证了：disableDefault: true时点击图片不会弹出预览窗口；传入custom后通过按钮触发custom.open()可以正常弹出预览。

设置 zIndex：控制预览窗口与背景的层级

预览窗口由两层结构组成：预览层（图片与工具栏）和背景遮罩层。默认情况下，预览层的z-index为 1050，背景层的z-index为 1040，即背景恰好比预览层低一层。通过zIndex与backDropZIndex可以分别控制这两者的层级：

<template> <div class="devui-image-preview-flex"> <d-radio-group direction="row" v-model="zIndex"> <d-radio v-for="item in zIndexList" :key="item" :value="item"> {{ item }} </d-radio> </d-radio-group> <span class="text">zIndex: {{ zIndex }}</span> </div> <div class="devui-image-preview-flex"> <d-radio-group direction="row" v-model="backDropZIndex"> <d-radio v-for="item in backDropZIndexList" :key="item" :value="item"> {{ item }} </d-radio> </d-radio-group> <span class="text">backDropZIndex: {{ backDropZIndex }}</span> </div> <div v-d-image-preview="{ zIndex: Number(zIndex), backDropZIndex: Number(backDropZIndex) }" class="devui-image-preview-demo" > <img v-for="src in imageList" :src="src" :key="src" /> </div> </template> <script> import { defineComponent, ref } from 'vue' export default defineComponent({ setup() { const imageList = ref([ 'https://devui.design/components/assets/image1.png', 'https://devui.design/components/assets/image3.png' ]) const zIndexList = ref(['1000', '1050', '1100']) const backDropZIndexList = ref(['900', '1040', '1000']) const zIndex = ref('1050') const backDropZIndex = ref('1040') return { imageList, zIndexList, backDropZIndexList, zIndex, backDropZIndex } } }) </script>

示例中通过两组单选（d-radio-group）动态切换zIndex与backDropZIndex。当zIndex小于backDropZIndex时，预览图片会显示在背景遮罩下方，页面视觉上表现为图片"沉底"、背景盖在其上。日常使用中建议保持zIndex比backDropZIndex大，且二者都大于页面上其他元素的层级。

源码层面的对应关系如下：

• 指令的updated钩子会把zIndex、backDropZIndex暂存到元素的自定义属性上（image-preview-directive.ts），供后续custom.open或点击触发时读取；
• 预览组件渲染时按需内联样式：const imageStyle = props.zIndex ? { zIndex: props.zIndex } : {};与const bgStyle = props.backDropZIndex ? { zIndex: props.backDropZIndex } : {};（image-preview.tsx）；
• SCSS 中预览层与背景层的基础 z-index 来自主题变量$devui-z-index-full-page-overlay（背景为calc($devui-z-index-full-page-overlay - 1)），见 image-preview.scss。

键盘操作：预览窗口打开后，按下Esc键会关闭预览；←（ArrowLeft）切换到上一张、→（ArrowRight）切换到下一张。该逻辑在组件的onKeyDown中通过监听全局keydown事件实现（image-preview.tsx），并在onMounted时注册、onUnmounted时移除监听，避免内存泄漏。

ImagePreview 参数说明

v-d-image-preview指令接受一个对象作为绑定值，包含以下四个可选参数：

与指令绑定值的类型定义对应（image-preview-types.ts）：

export interface BindingTypes { value: { custom?: Record<string, unknown>; disableDefault?: boolean; zIndex?: number; backDropZIndex?: number; }; [key: string]: unknown; }

补充两点使用提示：

• zIndex与backDropZIndex在模板中传字符串时需自行Number()转换（如示例中的Number(zIndex)），因为类型定义要求Number；
• 当指令不传任何绑定值（如<div v-d-image-preview>）时，默认行为等同"基本用法"：绑定点击、使用内置默认层级。

源码透视：预览窗口的打开与关闭流程

理解了指令层的用法后，再看预览窗口是如何被创建与销毁的。整个流程围绕ImagePreviewService展开（image-preview-service.ts），其核心是"动态创建独立 Vue 应用实例并挂载到 body"：

static open(props: ImagePreviewProps): void { this.$body = document.body; this.$div = document.createElement('div'); this.$overflow = this.$body.style.overflow; this.$body.appendChild(this.$div); createComponent(props).mount(this.$div); this.$body.style.setProperty('overflow', 'hidden', 'important'); } static close(): void { this.$body?.style.setProperty('overflow', this.$overflow); this.$overflow = null; this.$div && this.$body?.removeChild(this.$div); this.$body = null; this.$div = null; }

可以看到服务层做了两件关键事情：

1. createApp(imagePreview, props).mount($div)：每次打开预览都通过 Vue 的createApp创建一个全新的应用实例，挂载到动态创建的<div>上，再追加到document.body。这也解释了为什么指令、custom.open、服务调用可以随时弹出独立的预览窗口而不受宿主组件作用域限制；
2. 滚动穿透处理：打开时把body的overflow强制设为hidden（并暂存原值），关闭时恢复原值，避免预览打开期间底层页面仍可滚动。

而指令层的unmounted钩子与custom.close都会调用ImagePreviewService.close()完成清理，保证指令所在容器被销毁时预览窗口不会残留。

预览窗口内部结构

预览组件（image-preview.tsx）在挂载时执行三项初始化：

• initIndex()：根据传入的url在previewUrlList中定位起始图片下标；
• initTransform()：为预览图片创建Transform实例（拖拽与缩放能力）；
• initKeyboard()：注册全局键盘监听。

界面主要由三部分组成：居中的预览主图、右上角关闭按钮与左右两侧切换箭头、底部工具栏。工具栏提供完整操作集合：

缩放与拖拽的具体实现位于 transform.ts：滚轮缩放经过 100ms 节流处理，缩放范围被限制在MIN_SCALE = 0.2与MAX_SCALE = 2.5之间；鼠标按下可拖拽图片，拖拽时通过translate(x, y) scale(zoom) rotate(turn)组合变换实时更新样式；同时禁用页面默认的dragstart，避免拖图与页面拖拽行为冲突。

如何直接调用服务（进阶）

除了指令方式，组件库还把ImagePreviewService挂到了全局属性上（app.config.globalProperties.$imagePreviewService，见 image-preview/index.ts）。因此也可以在业务代码中通过this.$imagePreviewService.open({ url, previewUrlList, zIndex, backDropZIndex })命令式地打开预览窗口，而不依赖任何 DOM 容器。其中url（当前预览图，必填）与previewUrlList（可切换图片列表，必填）的类型定义见 image-preview-types.ts。

小结

本文以 vue-devui 的 ImagePreview 组件为对象，梳理了从"基本指令用法"到"自定义触发"、"层级控制"再到"源码实现原理"的完整链路。核心要点回顾：

1. v-d-image-preview指令作用于容器，自动收集容器内全部<img>的src，点击即预览；
2. 需要自定义触发时，传入custom对象并配合disableDefault: true，由指令注入的custom.open()打开预览；
3. zIndex与backDropZIndex分别控制预览层与背景层层级，默认 1050 / 1040，注意保持zIndex大于backDropZIndex；
4. 预览窗口由ImagePreviewService动态挂载到body，支持 Esc 关闭、方向键切换、滚轮缩放、拖拽与旋转；
5. 全局挂载的$imagePreviewService提供了不依赖 DOM 的命令式调用途径。

相关源码文件索引：指令实现、服务层、预览组件、变换控制、类型定义、单元测试。

• 前端
• UI组件
• 设计系统