Vue3图片（Image）

本图片预览组件主要包括以下功能展示图片时可设置鼠标悬浮时的预览文本图像无法加载时要显示的描述自定义图像高度和宽度设置图像如何适应容器高度和宽度fill | contain | cover | none | scale-down,参考 object-fit传入单张图像或图像数组设置图像缩放比率设置最大最小缩放比例单张图片预览时左上角展示图片名称水平镜像或垂直镜像可顺时针旋转或逆时针旋转还原图片放大缩小鼠标任意拖动鼠标双击图片还原使用触摸板或鼠标滚轮控制图片缩放多张图片预览时除了单张展示的功能以外可点击左右切换按钮预览多张图片使用键盘上下左右按键进行图片切换设置是否可以循环切换图片可自定义设置以下属性图像地址或图像地址数组src类型string | Array{src: string, alt?: string}默认 undefined图像名称name没有传入图片名时自动从图像地址 src 中读取类型string默认 undefined图像宽度width类型string | number | (string | number)[]单位 px默认 100图像高度height类型string | number | (string | number)[]单位 px默认 100是否禁用图像预览disabled类型boolean默认 false是否显示边框bordered类型boolean默认 true图形如何适应容器高度和宽度fit类型contain | fill | cover | none | scale-down默认 contain参考 object-fit预览文本preview类型string | slot默认 预览自定义预览图片时 img 元素的样式previewImageStyle类型CSSProperties默认 {}Space 组件属性配置spaceProps用于配置多张展示图片时的排列方式类型object默认 {}Spin 组件属性配置spinProps用于配置图片加载中样式类型object默认 {}Spin 组件属性配置previewSpinProps用于配置预览图片加载中样式类型object默认 {}每次缩放比率zoomRatio类型number默认 0.1最小缩放比例minZoomScale类型number默认 0.1最大缩放比例maxZoomScale类型number默认 10缩放移动旋转图片后是否可以双击还原resetOnDbclick类型boolean默认 true是否可以拖动图片draggable类型boolean默认 false是否可以循环切换图片loop类型boolean默认 false相册模式即从一张展示图片点开相册album类型boolean默认 false图片下载配置downloadOptions透传给内置 downloadFile 工具函数的第三个参数 options默认 auto 策略同源 anchor / 跨域 iframe类型{ target?: _self | _blank, strategy?: auto | anchor | iframe }默认值 undefined自定义下载方法customDownload提供时优先于内置 downloadFile用于解决跨域图床下载受限等内置策略无法满足的场景类型(url: string, fileName?: string) void | Promisevoid默认 undefined效果如下图预览时样式正常展示时样式图片加载时样式鼠标悬浮时样式在线预览①创建图片预览组件Image.vue其中引入使用了以下组件和工具函数Vue3加载中SpinVue3间距Space加法 add下载文件 downloadFile获取依赖注入 useInjectscript setup langts import { computed, ref, watchEffect, nextTick } from vue import type { CSSProperties } from vue import Space from components/space import Spin from components/spin import { add, downloadFile, useInject } from components/utils export interface Image { src: string // 图像地址 name?: string // 图像名称 } export interface Props { src?: string | Image[] // 图像地址或图像地址数组 name?: string // 图像名称没有传入图片名时自动从图像地址 src 中读取 width?: string | number | (string | number)[] // 图像宽度单位 px height?: string | number | (string | number)[] // 图像高度单位 px disabled?: boolean // 是否禁用图像预览 bordered?: boolean // 是否显示边框 fit?: contain | fill | cover | none | scale-down // 图片在容器内的的适应类型 preview?: string // 预览文本 string | slot previewImageStyle?: CSSProperties // 自定义预览图片时 img 元素的样式 spaceProps?: object // Space 组件属性配置用于配置多张展示图片时的排列方式 spinProps?: object // Spin 组件属性配置用于配置图片加载中样式 previewSpinProps?: object // Spin 组件属性配置用于配置预览图片加载中样式 zoomRatio?: number // 每次缩放比率 minZoomScale?: number // 最小缩放比例 maxZoomScale?: number // 最大缩放比例 resetOnDbclick?: boolean // 缩放移动旋转图片后是否可以双击还原 draggable?: boolean // 是否可以拖动图片 loop?: boolean // 是否可以循环切换图片 album?: boolean // 是否相册模式即从一张展示图片点开相册 downloadOptions?: { target?: _self | _blank // 打开方式 strategy?: auto | anchor | iframe // 下载策略 } // 图片下载配置透传给内置 downloadFile 的第三个参数 options默认 auto 策略同源 anchor / 跨域 iframe customDownload?: (url: string, fileName?: string) void | Promisevoid // 自定义下载方法提供时优先于内置 downloadFile用于解决跨域图床下载受限等内置策略无法满足的场景 } const props withDefaults(definePropsProps(), { src: undefined, name: undefined, width: 100, height: 100, disabled: false, bordered: true, fit: contain, preview: 预览, previewImageStyle: () ({}), spaceProps: () ({}), spinProps: () ({}), previewSpinProps: () ({}), zoomRatio: 0.1, minZoomScale: 0.1, maxZoomScale: 10, resetOnDbclick: true, draggable: false, loop: false, album: false, downloadOptions: undefined, customDownload: undefined }) const images refImage[]([]) // 图片数组 const previewRef refHTMLElement | null(null) // 预览 DOM 引用 const previewIndex refnumber(0) // 当前预览的图片索引 const showPreview refboolean(false) // 是否显示预览 const imagesRef refHTMLImageElement[]([]) // 图片 DOM 引用 const imagesCompleted refboolean[]([]) // 图片是否加载完成 const previewImagesRef refHTMLImageElement[]([]) // 预览图片 DOM 引用 const previewCompleted refboolean[]([]) // 预览图片是否加载完成 const rotate refnumber(0) // 预览图片旋转角度 const scale refnumber(1) // 缩放比例 const swapX refnumber(1) // 水平镜像数值符号 const swapY refnumber(1) // 垂直镜像数值符号 const sourceX refnumber(0) // 拖动开始时位置 const sourceY refnumber(0) // 拖动开始时位置 const dragX refnumber(0) // 拖动横向距离 const dragY refnumber(0) // 拖动纵向距离 const sourceDragX refnumber(0) // 鼠标按下时图片的X轴偏移量 const sourceDragY refnumber(0) // 鼠标按下时图片的Y轴偏移量 const top refnumber(0) // 图片上边缘距浏览器窗口上边界的距离 const bottom refnumber(0) // 图片下边缘距浏览器窗口上边界的距离 const right refnumber(0) // 图片右边缘距浏览器窗口左边界的距离 const left refnumber(0) // 图片左边缘距浏览器窗口左边界的距离 const viewportWidth refnumber(0) // 视口宽度 const viewportHeight refnumber(0) // 视口高度 const { colorPalettes } useInject(Image) // 主题色注入 const imageAmount computed(() { return images.value.length }) const dragTransitionDuration computed(() { return props.draggable ? 100ms : 200ms }) watchEffect(() { images.value getImages() }) function getImages(): Image[] { if (Array.isArray(props.src)) { return props.src } else { return [ { src: props.src || , name: props.name } ] } } // 图片加载完成 function onImageLoaded(index: number): void { imagesCompleted.value[index] true } // 预览图片加载完成例如相册模式可在预览中切换到未加载完成的图片 function onPreviewLoaded(index: number): void { previewCompleted.value[index] true } // 从地址中提取路径末段作为原始文件名 function getRawNameFromUrl(src: string): string { // 以当前页面地址为 base 解析兼容相对路径解析失败时降级为手工切分 let pathname try { pathname new URL(src, location.href).pathname } catch { pathname src.split(?)[0].split(#)[0] } const segments pathname.split(/) return segments[segments.length - 1] || } // 从图像地址 src 中获取图像名称 // 优先使用显式传入的 name否则从 src 中提取 // 用 URL.pathname 天然剥离查询参数?与哈希#再取末段并做 URL 解码 function getImageName(image: Image): string | undefined { if (image) { if (image.name) { return image.name } const rawName getRawNameFromUrl(image.src) try { return decodeURIComponent(rawName) } catch { // 路径段含非法百分号编码时 decodeURIComponent 会抛异常此时原样返回 return rawName } } } function getImageSize(size: string | number | (string | number)[], index: number): string { if (Array.isArray(size)) { if (typeof size[index] number) { return ${size[index]}px } return size[index] } else { if (typeof size number) { return ${size}px } return size } } // 使用键盘切换图片 function onKeyboard(e: KeyboardEvent): void { if (showPreview.value imageAmount.value 1) { if (e.key ArrowLeft || e.key ArrowUp) { onSwitchLeft() } if (e.key ArrowRight || e.key ArrowDown) { onSwitchRight() } } } // 预览 async function onPreview(index: number): Promisevoid { scale.value 1 rotate.value 0 dragX.value 0 dragY.value 0 showPreview.value true previewIndex.value index await nextTick() previewRef.value?.focus() } defineExpose({ preview: onPreview }) // 关闭 function onClose(): void { showPreview.value false } // 下载 function onDownload(): void { const image images.value[previewIndex.value] // 提供自定义下载方法时优先使用绕开内置下载方法 if (props.customDownload) { props.customDownload(image.src, image.name) return } // 未自定义时走内置 downloadFile透传下载配置 downloadFile(image.src, image.name, props.downloadOptions) } // 放大 function onZoomin(): void { if (scale.value props.zoomRatio props.maxZoomScale) { scale.value props.maxZoomScale } else { scale.value add(scale.value, props.zoomRatio) } } // 缩小 function onZoomout(): void { if (scale.value - props.zoomRatio props.minZoomScale) { scale.value props.minZoomScale } else { scale.value add(scale.value, -props.zoomRatio) } } // 重置图片为初始状态 function onResetOrigin(): void { scale.value 1 swapX.value 1 swapY.value 1 rotate.value 0 dragX.value 0 dragY.value 0 } // 顺时针旋转 function onClockwiseRotate(): void { rotate.value 90 } // 逆时针旋转 function onAnticlockwiseRotate(): void { rotate.value - 90 } // 水平镜像 function onHorizontalMirror(): void { swapX.value * -1 } // 垂直镜像 function onVerticalMirror(): void { swapY.value * -1 } // 鼠标滚轮缩放 function onWheel(e: WheelEvent) { // e.preventDefault() // 禁止浏览器捕获滑动事件 const scrollZoom e.deltaY * props.zoomRatio * 0.1 // 滚轮的纵向滚动量 if (scale.value props.minZoomScale scrollZoom 0) { return } if (scale.value props.maxZoomScale scrollZoom 0) { return } if (scale.value - scrollZoom props.minZoomScale) { scale.value props.minZoomScale } else if (scale.value - scrollZoom props.maxZoomScale) { scale.value props.maxZoomScale } else { scale.value add(scale.value, -scrollZoom) } } function handlePointerDown(e: PointerEvent) { // event.preventDefault() // 消除拖动元素时的阴影 if (!e.target) return const el e.target // 当前点击的元素 const imageRect (el as Element).getBoundingClientRect() top.value imageRect.top // 图片上边缘距浏览器窗口上边界的距离 bottom.value imageRect.bottom // 图片下边缘距浏览器窗口上边界的距离 right.value imageRect.right // 图片右边缘距浏览器窗口左边界的距离 left.value imageRect.left // 图片左边缘距浏览器窗口左边界的距离 viewportWidth.value window.innerWidth // 视口宽度 viewportHeight.value window.innerHeight // 视口高度 sourceX.value e.clientX // 指针按下时相对于视口左边缘的X坐标 sourceY.value e.clientY // 指针按下时相对于视口上边缘的Y坐标 sourceDragX.value dragX.value // 指针按下时图片的X轴偏移量 sourceDragY.value dragY.value // 指针按下时图片的Y轴偏移量 // 捕获指针确保即使移出元素也能继续跟踪 ;(el as HTMLElement).setPointerCapture(e.pointerId) document.addEventListener(pointermove, handlePointerMove) document.addEventListener(pointerup, handlePointerUp) document.addEventListener(pointercancel, handlePointerUp) handlePointerMove(e) } function handlePointerMove(e: PointerEvent) { // e.clientX 返回事件被触发时指针相对于浏览器可视窗口的水平坐标 dragX.value sourceDragX.value e.clientX - sourceX.value dragY.value sourceDragY.value e.clientY - sourceY.value } function handlePointerUp() { if (props.draggable) { if (dragX.value sourceDragX.value viewportWidth.value - right.value) { // 溢出视口右边缘 dragX.value sourceDragX.value viewportWidth.value - right.value } if (dragX.value sourceDragX.value - left.value) { // 溢出视口左边缘 dragX.value sourceDragX.value - left.value } if (dragY.value sourceDragY.value viewportHeight.value - bottom.value) { // 溢出视口下边缘 dragY.value sourceDragY.value viewportHeight.value - bottom.value } if (dragY.value sourceDragY.value - top.value) { // 溢出视口上边缘 dragY.value sourceDragY.value - top.value } } else { dragX.value 0 dragY.value 0 } document.removeEventListener(pointermove, handlePointerMove) document.removeEventListener(pointerup, handlePointerUp) document.removeEventListener(pointercancel, handlePointerUp) } // 切换到上一张 function onSwitchLeft(): void { if (props.loop) { previewIndex.value (previewIndex.value - 1 imageAmount.value) % imageAmount.value } else { if (previewIndex.value 0) { previewIndex.value-- } } onResetOrigin() } // 切换到下一张 function onSwitchRight(): void { if (props.loop) { previewIndex.value (previewIndex.value 1) % imageAmount.value } else { if (previewIndex.value imageAmount.value - 1) { previewIndex.value } } onResetOrigin() } /script template div classimage-wrap :style--image-primary-color: ${colorPalettes[5]}; Space gapsmall v-bindspaceProps div v-for(image, index) in images :keyindex v-show!album || (album index 0) classimage-container :class{ image-bordered: bordered, image-hover-mask: !disabled (imagesCompleted[index] || imagesRef[index]?.naturalWidth) } :stylewidth: ${getImageSize(props.width, index)}; height: ${getImageSize(props.height, index)}; Spin :spinning!(imagesCompleted[index] || imagesRef[index]?.naturalWidth) colorvar(--image-primary-color) indicatordynamic-circle sizesmall v-bindspinProps img refimagesRef classimage-item :styleobject-fit: ${fit}; loadonImageLoaded(index) :srcimage.src :altgetImageName(image) / /Spin div v-if!disabled classimage-mask clickonPreview(index) div classimage-mask-info svg classeye-svg focusablefalse >script setup langts import Image from ./Image.vue import { ref } from vue import type { ImageItem } from vue-amazing-ui const images refImageItem[]([ { src: https://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/1.jpg, name: image-1.jpg }, { src: https://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/2.jpg, name: image-2.jpg }, { src: https://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/3.jpg, name: image-3.jpg }, { src: https://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/4.jpg, name: image-4.jpg }, { src: https://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/5.jpg, name: image-5.jpg } ]) /** * 自定义下载示例用 XHR Blob 下载跨域图床图片 * 内置 downloadFile 的 iframe 策略受图床 X-Frame-Options 限制改用 XHR 取二进制后通过 Blob 触发下载不受该限制 */ function customDownload(url: string, fileName?: string) { // 以二进制流方式请求图片需要图床开启 CORS 才能跨域读取 const xhr new XMLHttpRequest() xhr.open(GET, url, true) xhr.responseType blob xhr.onload () { if (xhr.status 200) { // 将二进制流转为本地 Blob URL再通过 a 标签的 download 属性强制下载blob 同源download 始终生效 const blobUrl URL.createObjectURL(xhr.response) const a document.createElement(a) a.href blobUrl a.download fileName || url.split(?)[0].split(/).pop() || download document.body.appendChild(a) a.click() document.body.removeChild(a) URL.revokeObjectURL(blobUrl) // 释放 Blob URL避免内存泄漏 } } xhr.send() } /script template div h1{{ $route.name }} {{ $route.meta.title }}/h1 Alert classmt10 mb10 typewarning message关于示例图片的下载功能 show-icon template #description p 示例图片虽以 codecdn.jsdelivr.net/code 为入口但下载时会 301 重定向到 coderaw.githubusercontent.com/code导致默认的「下载」按钮失效原因如下/p p classmb10 mt10 内置 codedownloadFile/code 对跨域地址走 codeiframe/code 策略而 coderaw.githubusercontent.com/code 设置了 codeX-Frame-Options: deny/code浏览器拒绝在 iframe 内加载控制台报 codeRefused to display ... in a frame/code即便不重定向codecdn.jsdelivr.net/code 作为普通 CDN 也不支持 iframe 策略依赖的 coderesponse-content-disposition/code 参数。/p p classmt10 下方的「自定义下载」小节演示了可用的 codeXHR Blob/code 方案以二进制流读取图片需图床开启 CORScode raw.githubusercontent.com/code 返回 codeAccess-Control-Allow-Origin: */code后转 Blob URL再用 codea/code 标签 codedownload/code 属性强制下载不受上述限制。/p /template /Alert h2 classmt30 mb10基本使用/h2 Image srchttps://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/1.jpg / h2 classmt30 mb10多张图片预览/h2 p classmb10 可循环切换图片并支持键盘 (codeleft/code / coderight/code / codeup/code / codedown/code) 按键切换/p Image :srcimages loop / h2 classmt30 mb10禁用预览/h2 Image srchttps://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/1.jpg disabled / h2 classmt30 mb10自定义样式/h2 p classmb10自定义宽高同时图片覆盖容器预览文本设为 codepreview/code/p Image :srcimages :width[100, 200, 100, 200, 100] :space-props{ width: 416 } fitcover loop template #preview p classpreview-txtpreview/p /template /Image h2 classmt30 mb10自定义预览图片样式/h2 Image :srcimages :preview-image-style{ background: #fff, padding: 12px, borderRadius: 8px } loop / h2 classmt30 mb10自定义排列方式 加载中样式/h2 Image :srcimages :space-props{ width: 332, gap: 16 } :spin-props{ tip: loading, indicator: spin-line, color: #fadb14 } loop / h2 classmt30 mb10无边框/h2 Image :srcimages :borderedfalse fitcover loop / h2 classmt30 mb10相册模式/h2 Image :srcimages album loop / h2 classmt30 mb10自定义预览配置/h2 p classmb10更改缩放比率和最大最小缩放比例/p Image :zoom-ratio0.2 :min-zoom-scale0.5 :max-zoom-scale2 srchttps://cdn.jsdelivr.net/gh/themusecatcher/resources0.1.2/1.jpg / h2 classmt30 mb10下载配置/h2 p classmb10 通过 codedownloadOptions/code 配置内置下载策略codeanchor/code / codeiframe/code与打开方式 code _self/code / code_blank/code。 /p p classmb10 下方示例强制 codeanchor/code 策略并设 codetarget_blank/code跨域下 codedownload/code 属性失效点击后在新窗口打开图片。 /p Image album :srcimages :download-options{ strategy: anchor, target: _blank } loop / h2 classmt30 mb10自定义下载/h2 p classmb10 跨域图床如设置 codeX-Frame-Options/code 拒绝 codeiframe/code 的 CDN下载受限时内置 codedownloadFile/code 可能无法满足可通过 codedownloadOptions/code 调整内置下载策略或通过 codecustomDownload/code 提供完全自定义的下载方法。 /p p classmb10 下方示例演示了用 XHR Blob 绕过codeX-Frame-Options/code 限制下载跨域图床图片 /p Image album :srcimages :custom-downloadcustomDownload loop / /div /template style langless scoped .preview-txt { display: inline-block; font-size: 16px; } /style