超好用的vue图片预览插件更新啦,hevue-img-preview 7.0.0版本正式发布,支持vue2/vue3/移动/pc,增加缩略图、下载、自定义样式等

简介

各位大佬不好意思,标题党了一把,来打个小广告,好久前写的一个vue图片预览插件,最近更新了一把,如果各位有需要的可以支持一把

本文档仅对一些新功能做介绍,具体使用方法请参考官方文档

首先还是对插件的一个简单介绍,

hevue-img-preview是一个基于 vue 编写的 vue 图片预览组件,已对vue2和vue3同时兼容,支持 pc 和手机端,支持单图和多图预览,仅传入一个图片地址,即可实现图片预览效果。手机端支持单指拖拽和双指缩放。页面各组件颜色均可自定义,实现个性化设计,如果能帮上你,希望可以移步 GitHub ,或者码云 给个小星星,如果有任何使用意见或建议,也欢迎回复或者提交 issure

特色:

单图预览 多图预览 单图预览 缩略图 快捷键 自定义旋转 切换图片事件回调 关闭事件回调 PC端 移动端 保存图片 自定义样式


🌐 访问地址

📁 项目仓库

github.com/heyongsheng...

gitee.com/ihope_top/h...

📄 在线文档

在线文档使用vitepress进行了重新编写,说明更详细,结构更清晰,欢迎大家点击在线体验。

img-preview-doc.it1996.com

heyongsheng.github.io/en


📝 更新日志

📦 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 变量命名规范。

✅ 两种自定义方式:

  1. 配置 CSS 变量(推荐)

    提供了多个通用主变量,用于统一控制整体样式(如背景色、文字色等);同时也提供了细粒度变量,可对某个模块单独调整样式。

  2. 覆盖类名样式(高级用法)

    如果现有配置项无法满足您的定制需求,您也可以通过浏览器开发者工具查看 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,或者一个评论、一个点赞,都是对我最大的支持与鼓励,祝各位大佬工作顺利、升职加薪!

附上一个同学给我的支持,嘿嘿

相关推荐
摸鱼仙人~1 分钟前
React Ref 指南:原理、实现与实践
前端·javascript·react.js
teeeeeeemo2 分钟前
回调函数 vs Promise vs async/await区别
开发语言·前端·javascript·笔记
贵沫末21 分钟前
React——基础
前端·react.js·前端框架
aklry33 分钟前
uniapp三步完成一维码的生成
前端·vue.js
Rubin9340 分钟前
判断元素在可视区域?用于滚动加载,数据埋点等
前端
爱学习的茄子40 分钟前
AI驱动的单词学习应用:从图片识别到语音合成的完整实现
前端·深度学习·react.js
用户38022585982441 分钟前
使用three.js实现3D地球
前端·three.js
程序无bug43 分钟前
Spring 面向切面编程AOP 详细讲解
java·前端
zhanshuo43 分钟前
鸿蒙UI开发全解:JS与Java双引擎实战指南
前端·javascript·harmonyos
JohnYan43 分钟前
模板+数据的文档生成技术方案设计和实现
javascript·后端·架构