10 行代码快速给网页加上图片浏览器：Viewer.js 图像查看器指南

10 行代码快速给网页加上图片浏览器：Viewer.js 图像查看器指南

【免费下载链接】viewerjsJavaScript image viewer.项目地址: https://gitcode.com/gh_mirrors/vi/viewerjs

想让网页里的商品图放大、旋转、滑动翻页？手写要处理滚轮、触摸手势和动画，代码量不小。Viewer.js 是 JavaScript 图像查看器，把图片浏览这些交互都做好了。

🚀 一条命令安装，最小代码跑起来

npm install viewerjs

import Viewer from 'viewerjs'; import 'viewerjs/dist/viewer.css'; const viewer = new Viewer(document.querySelector('.gallery'));

跑起来后，点击 .gallery 里任意一张图片会弹出查看器：双击切换大小，滚轮缩放，方向键翻页。

🖼️ 核心能力：图片浏览的常见操作都覆盖

看大图：滚轮、双指、按钮都能放大

放大是最常用的交互，滚轮、触摸双指、工具栏按钮三种方式都支持，缩放后还有小气泡提示当前百分比。

• 放大缩小都支持，范围可配置
• 双击切换原始尺寸与初始显示尺寸
• 移动端双指缩放、滑动切图都可用

换角度：旋转、翻转、拖拽移动

放大之后还能旋转、翻转、拖动平移，方便看清细节。

• 90° 步进旋转，rotateTo 可指定任意角度
• 水平、垂直两个方向翻转
• 拖拽平移，范围可限定在图片内

翻图与自动播放

多张图片时可以逐张切换，也可以开播放模式自动轮播。

• 方向键或工具栏按钮切前一张、后一张
• 默认循环，看完回到第一张
• 空格键播放/暂停，interval 控制间隔

🛠️ 常用配置项：按需求开关功能

默认配置是所有功能打开的状态，实际接入时把不用的关掉即可。这几个是平时最常动的：

• inline：内嵌到页面而非弹窗
• toolbar：设 false 整体隐藏，传对象可去掉单个按钮
• zoomable/rotatable/movable：分别开关缩放、旋转、移动
• maxZoomRatio：限制最大放大倍数

new Viewer(img, { inline: true, toolbar: { rotateLeft: false, rotateRight: false }, maxZoomRatio: 5, });

思路是按需开启：只做预览的话，把旋转、翻转关掉，留下缩放和移动就够了。

实战技巧：三个容易踩的坑

下面三条能少踩不少坑：

• 限制缩放范围：minZoomRatio 和 maxZoomRatio 兜底，防止缩到看不见或放大成马赛克
• 缩略图展示、原图查看：页面放压缩小图，url 配置指向原图，打开时才加载高清图
• 单图场景关掉循环、导航栏和播放按钮，界面更干净

这些场景里用它比较合适

电商商品详情页上，用户能放大看清材质和标签；摄影作品集里，翻页、自动播放、旋转换角度看大图；管理后台用内联模式嵌在列表页里，预览不用切页面；手机 H5 上，触摸切图和双指缩放开箱即用。

源码与文档入口

示例目录里放了几种用法：docs/examples/ 有自定义标题、自定义工具栏、移动范围限制等页面；src/js/ 是源码，defaults.js 是默认配置，methods.js 是全部方法；test/specs/ 下 100 多条测试用例，覆盖选项、方法与事件，能当用法文档看。

建议先从示例目录里挑一个页面在浏览器打开，再对照默认配置改几个选项，就能接到自己的页面上了。

【免费下载链接】viewerjsJavaScript image viewer.项目地址: https://gitcode.com/gh_mirrors/vi/viewerjs