
简介
各位大佬不好意思,标题党了一把,来打个小广告,好久前写的一个vue图片预览插件,最近更新了一把,如果各位有需要的可以支持一把
本文档仅对一些新功能做介绍,具体使用方法请参考官方文档
hevue-img-preview是一个基于 vue 编写的 vue 图片预览组件,已对vue2和vue3同时兼容,支持 pc 和手机端,支持单图和多图预览,仅传入一个图片地址,即可实现图片预览效果。手机端支持单指拖拽和双指缩放。页面各组件颜色均可自定义,实现个性化设计,如果能帮上你,希望可以移步 GitHub ,或者码云 给个小星星,如果有任何使用意见或建议,也欢迎回复或者提交 issure
特色:
单图预览
多图预览
单图预览
缩略图
快捷键
自定义旋转
切换图片事件回调
关闭事件回调
PC端
移动端
保存图片
自定义样式
🌐 访问地址
📁 项目仓库
📄 在线文档
在线文档使用vitepress进行了重新编写,说明更详细,结构更清晰,欢迎大家点击在线体验。
📝 更新日志
📦 7.0.0 版本更新内容
本次更新是一次较大的功能与体验升级,主要包括以下内容:
✨ 新增功能:
- ✅ 新增底部预览图,提升多图浏览效率
- ✅ 支持通过 CDN 引入,便于非脚手架项目使用
- ✅ 新增禁止图片右键功能,增强内容保护
- ✅ 控制栏支持图片下载按钮
- ✅ 控制栏支持单个功能按钮的显示/隐藏控制
- ✅ 多图预览下支持底部控制栏左右切换图片
- ✅ 控制栏支持自定义旋转角度操作
- ✅ 快捷键支持提示说明,自动展示键位帮助图标
- ✅ 新增多套预置主题,样式更加丰富
- ✅ 新增多语言支持(当前支持中英文)
- ✅ 新增多种交互过渡动画,默认开启,可配置禁用
🔧 使用体验优化:
- 🛠️ 样式支持更加灵活,配置项更丰富
- 🛠️ 多图切换逻辑优化:已加载图片将缓存,避免重复加载
- 🛠️ Vue 2 / Vue 3 全局引入与局部注册方式统一优化,使用更简洁
📌 版本兼容
7.0 版本对 Vue 2 和 Vue 3 的兼容性进行了全面优化,分别提供了独立构建版本,使项目结构更清晰、维护更便捷。
主要更新包括:
-
✅ 完善支持 Vue 2 与 Vue 3 的全局引入 与局部使用
-
🛠️ 重构配置文件,分别处理 Vue 2 和 Vue 3 的逻辑,逻辑更清晰
-
📦 新增打包版本,适用于非脚手架项目的直接引入场景
⚠️ 注意:打包版本未包含 Vue 本体,请确保在使用前已引入 Vue
🚀 版本优化
✨ 使用优化说明(以 Vue 2 全局引入为例)
本次更新对使用方式进行了优化。以 Vue 2 的全局调用为例,方法仍为this.$hevueImgPreview()
,但移出了上一版本用来接收单个图片地址的参数url
,以及用来开启多图预览的参数multiple
您现在可以直接传入单个图片地址或图片数组,插件会自动判断是单图还是多图预览,无需手动指定:
js
this.$hevueImgPreview('/1.png') // 单图预览
this.$hevueImgPreview(['/1.png']) // 单图预览
this.$hevueImgPreview(['/1.png', '/2.png']) // 多图预览
this.$hevueImgPreview({
imgList: ['/1.png', '/2.png'] // 多图预览
})
🧩 快捷键功能可视化提示
在上一版本中,即便您启用了快捷键功能,用户也无法得知该功能是否启用,更难以了解各个操作所对应的快捷键。
在本次更新中,我们对此进行了改进:
当您启用快捷键支持时,插件将会自动在控制栏中添加一个"帮助"图标,点击即可查看所有可用的快捷键说明,提升用户操作体验和可发现性。

如果您的用户来自国际市场,也无需担心,插件已支持中英双语切换。只需在配置项中设置:
js
locale: 'en'
即可启用英文界面,适配国际化需求。

🚀 性能优化
在旧版本中,多图预览的实现方式是通过创建单个 节点,并在切换图片时不断更新其 src 属性。这种方式的优点是避免了一次性加载全部图片,但也存在明显缺陷 ------ 每次切换都会重新加载图片,即使该图片刚刚已经浏览过。
对于大尺寸图片而言,这不仅增加了加载延迟和带宽消耗,还会显著影响用户体验。
在本次版本更新中,我们对这一机制进行了优化:
每张图片在首次预览后将自动缓存,后续切换同一张图片时将直接从缓存中读取,无需重新加载,从而实现更流畅、更高效的浏览体验。

🎨 交互优化
在本次版本中,插件为多个关键交互场景引入了过渡动画效果,包括弹窗的显示/关闭、图片的切换、快捷键帮助框的展开与收起等。这些动画增强了整体的视觉体验,使交互过程更加自然、流畅。
然而,我们也考虑到部分用户可能更偏好 "无动画"的极简切换体验,尤其是在预览大量高清图时。为了避免额外的性能消耗或追求操作效率,我们提供了关闭全局过渡效果的选项。
您只需在配置项中设置:
js
disableTransition: true
即可关闭所有内置动画,还原为快速、直接的切换行为。
自定义样式及主题
🎨 样式自定义
虽然我们已尽力提供了一套简洁美观的默认样式,但可能仍无法完全契合您的网站风格。为此,插件支持对多处样式进行自定义配置,包括:
- 背景颜色
- 字体颜色
- 边框样式
- 背景滤镜
- 阴影效果等
我们使用了标准的 CSS 变量(Custom Properties) 实现样式控制,因此所有配置项都遵循 CSS 变量命名规范。
✅ 两种自定义方式:
-
配置 CSS 变量(推荐)
提供了多个通用主变量,用于统一控制整体样式(如背景色、文字色等);同时也提供了细粒度变量,可对某个模块单独调整样式。
-
覆盖类名样式(高级用法)
如果现有配置项无法满足您的定制需求,您也可以通过浏览器开发者工具查看 DOM 结构,获取对应元素的类名,自定义 CSS 进行覆盖。
🧊 全新主题:Glass Theme(液态玻璃风格)
iOS 26 引入的液态玻璃视觉效果为我们带来了全新的设计灵感。受此启发,我们也将这一现代感十足的 UI 风格引入到插件中,打造了全新主题 ------ glass-theme。
尽管由于前端技术的限制,效果难以与原生系统媲美,但它依然在视觉层面提供了更具科技感、通透感的展示体验。
考虑到用户的多样化审美,我们并未将其设为默认样式 ,而是将其作为一个可选主题提供。您只需在配置中传入:
js
themeName: 'glass-theme'
即可启用该液态玻璃主题。

本文档中所出现的示例图片均为此主题,gif录制受限于大小限制,效果可能不佳,建议前往官方文档在线体验
未来我们还将推出更多主题样式,以满足不同项目风格和用户偏好,敬请期待。
由于 该主题滤镜效果与过渡动画存在兼容性问题 ,二者无法同时生效。在启用 glass-theme 等带有滤镜样式的主题时:
- 过渡动画会影响滤镜的正常渲染
- 滤镜效果通常会在动画结束后才生效,可能导致显示过程较为突兀
建议在使用此类滤镜主题时,关闭全局过渡效果,以获得更自然的视觉表现:

🎛️ 控制条及控制项变动说明
🎛️ 控制条整体与单个控制项的显示与隐藏
在本版本中,我们增强了对底部控制条的控制能力,您不仅可以控制控制条是否显示 ,还可以灵活配置需要显示的具体功能项及其显示顺序。
我们通过 controlBar
配置项实现该功能,具体支持以下三种用法:
✅ 默认行为:显示所有控制项
无需任何配置,插件将自动显示所有支持的功能按钮,按默认顺序排列。
❌ 隐藏整个控制条
如您希望完全关闭控制条,可传入布尔值 false:
js
controlBar: false
✨ 显示特定控制项,并自定义顺序
如果您只希望显示部分功能按钮(如放大、缩小、快捷键帮助等),可传入一个数组,指定需要显示的控制项名称及顺序:
js
controlBar: ['zoomOut', 'zoomIn', 'help']

📌 注意:传入数组的顺序即为控制项在界面上的显示顺序。
💾 图片下载功能

在本次版本中,控制栏新增了图片下载按钮,用户可通过点击图标便捷地下载当前预览的图片,提升整体使用体验。
不过需要注意的是:部分图片(尤其是来自第三方源或使用了防盗链、防跨域策略的资源)可能会因跨域限制或安全策略导致下载失败。
我们建议在开启该功能前,对目标图片源进行充分测试,确保兼容性。如果您的图片不适合下载,您也可以:
- 通过配置项隐藏下载按钮;
- 启用 disabledImgRightClick: true 禁止图片右键菜单,降低普通用户保存图片的可能性。
在后续版本中,我们也将持续优化下载方式,以提高成功率和跨站兼容性。
🖼️ 缩略图功能

在过去的用户反馈中,缩略图功能是呼声较高的一项,因此我们在本次版本中正式引入了该功能,方便用户在多图预览中快速定位与切换图片,希望这项改进能为您带来更便捷的使用体验。
不过需要特别说明的是:
为优化性能,插件默认采用懒加载 + 缓存机制,仅在用户首次切换到某张图片时加载该图资源,并在本地缓存,提升体验并减少资源消耗。
但当您启用缩略图功能后,所有图片会在插件初始化时一次性加载,以便生成对应的缩略图视图。因此:
⚠️ 如果您需要预览的图片数量众多或图片质量较高,建议谨慎开启缩略图功能。
您可以通过以下方式控制该功能是否启用:
js
thumbnail: true // 启用缩略图
如需关闭,设置为 false 即可。
自定义旋转
在旧版本中,图片旋转功能仅支持固定的 90° 增量旋转,难以满足用户对角度的个性化需求。
为此,我们在本次版本中新增了 自定义角度旋转功能 ,并采用了滑动条式的交互设计。用户可以通过底部的旋转控制条,自由滑动选择任意角度,实现更精细的旋转控制。
这种方式相比传统按钮式旋转更加直观,适用于需要对图片进行非标准角度调整的场景,提升了插件的专业性与实用性。
📌 当前旋转角度将在控制条上实时展示,方便用户快速校准。

结语
虽然插件功能不强,需求也不大,但是也耗费了我不少的精力和时间,如果真的可以帮助到您,希望您可以留下一个star,或者一个评论、一个点赞,都是对我最大的支持与鼓励,祝各位大佬工作顺利、升职加薪!
附上一个同学给我的支持,嘿嘿
