image-viewer-js 开源图片查看插件完整教程

摘要

前端项目中原生图片预览功能简陋，全屏放大、拖拽、缩放、多图轮播等需求很难原生实现，引入重型看图组件又会增加项目体积。image-viewer-js 是同作者配套零依赖纯 JS 图片预览插件，轻量化、无第三方库捆绑，支持单图放大、多图集轮播、鼠标滚轮缩放、拖拽平移、键盘快捷键、遮罩锁定等全套看图能力，静态页面、Vue/React SPA、后台管理系统均可快速接入，搭配 title2tip-js 可实现图片悬浮提示 + 全屏预览完整图文交互方案。 关键词：image-viewer-js；图片预览；JS 看图插件；零依赖前端组件；图片放大轮播；轻量图片查看器

前言

日常开发中商品页面、相册、文档、博客都需要图片预览功能：点击小图全屏放大、多图左右切换、滚轮缩放、拖拽移动。市面上图片预览组件大多依赖 jQuery、Vue 全家桶，打包体积臃肿，小型静态页面、轻量化 H5 引入成本过高；原生window.open打开图片体验粗糙，不支持缩放轮播。 image-viewer-js 与 title2tip-js 出自同一开发者 JackieZheng，设计思路统一：纯原生 JS、零依赖、极简 API、开箱即用，两者可以配套使用，图片悬浮提示 + 全屏预览一站式解决图文交互需求。

一、项目基础信息

项目开源地址：https://github.com/JackieZheng/image-viewer-js 开源协议：MIT 协议，免费商用、无版权限制核心定位：轻量无依赖网页图片查看器，单图 / 多图集预览通用解决方案配套工具：可搭配title2tip-js实现图片悬浮文字提示 + 点击全屏预览组合效果

核心功能特性

零外部依赖，不绑定任何框架，原生 HTML 直接使用
单图独立预览、批量图集轮播两种模式
鼠标滚轮放大缩小、拖拽平移大图
键盘快捷键支持：左右切换、ESC 关闭、加减缩放
深色半透明遮罩，禁止底层页面滚动
自适应窗口大小，大图自动居中适配屏幕
兼容动态渲染 DOM，SPA 路由刷新后可重新绑定
自定义遮罩颜色、动画过渡、缩放阈值、点击关闭规则
低体积压缩产物，不会大幅增加项目打包大小

二、两种安装引入方式

1. NPM 工程化引入（Vue/React/Vite/Webpack）

bash

运行

复制代码

npm install @jackiezhengchina/image-viewer

项目内直接导入使用：

javascript

运行

复制代码

import ImageViewer from '@jackiezhengchina/image-viewer'

2. CDN 静态页面引入

国内网络优先使用国内镜像 CDN，境外 jsdelivr 可能访问失败，不推荐原文 cdn 地址。静态页面引入示例：

html

预览

复制代码

jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@jackiezhengchina/image-viewer@1.0.2/dist/image-viewer.min.js"></script>

unpkg:

<script src="https://unpkg.com/@jackiezhengchina/image-viewer@1.0.2/dist/image-viewer.min.js"></script>

三、基础使用示例

方式 1：单图片自动绑定（最简单）

给图片增加指定属性，页面加载自动绑定点击预览，无需手动写 JS：

html

预览

复制代码

<img data-view src="demo1.jpg" alt="产品图片">

页面底部初始化：

html

预览

复制代码

<script>
ImageViewer.init();
</script>

方式 2：多图集轮播预览

一组图片添加相同分组属性，点击后左右切换图集：

html

预览

复制代码

<img data-view="gallery1" src="pic1.jpg" alt="图1">
<img data-view="gallery1" src="pic2.jpg" alt="图2">
<img data-view="gallery1" src="pic3.jpg" alt="图3">
<script>
ImageViewer.init();
</script>

方式 3：JS 手动调用预览（动态图片 / 按钮触发）

异步加载图片、列表动态渲染场景，可手动打开预览：

javascript

运行

复制代码

// 单图直接打开
ImageViewer.open('https://xxx/demo.jpg')

// 图集数组批量打开
ImageViewer.open([
  'pic1.jpg',
  'pic2.jpg',
  'pic3.jpg'
])

四、全局自定义配置

可统一修改遮罩、动画、缩放、交互规则：

javascript

运行

复制代码

ImageViewer.config = {
  maskBg: 'rgba(0,0,0,0.85)', // 遮罩背景色
  animate: true,              // 开启打开关闭过渡动画
  scrollLock: true,           // 预览时锁定页面滚动
  wheelStep: 0.1,             // 滚轮每次缩放比例
  minScale: 0.3,              // 最小缩放倍数
  maxScale: 5,                // 最大缩放倍数
  closeOnMask: true           // 点击遮罩关闭预览
}

五、内置 API 大全

表格

API 方法	作用说明
ImageViewer.init()	自动扫描页面带 data-view 属性图片，绑定点击事件
Image.refresh()	SPA 路由切换 / 动态生成图片后重新扫描绑定
Image.open(src / srcArray)	手动唤起单图 / 图集预览窗口
Image.close()	强制关闭当前预览弹窗
Image.config	全局配置对象

六、SPA 框架适配方案

Vue 项目

路由切换后动态图片不会自动绑定，路由后置钩子执行刷新：

javascript

运行

复制代码

import ImageViewer from '@jackiezheng/image-viewer'
router.afterEach(()=>{
  ImageViewer.refresh()
})

React 项目

页面 DOM 更新后执行刷新：

javascript

运行

复制代码

useEffect(()=>{
  ImageViewer.refresh()
},[页面路径/列表数据])

七、配套组合：搭配 title2tip-js 使用

两个插件同作者、设计风格统一，图片同时实现悬浮提示 + 点击全屏预览：

html

预览

复制代码

<img 
  data-title-tip="2025新款商品实拍图，支持高清放大查看细节"
  data-view="goods"
  src="goods.jpg"
>
<script src="本地/国内CDN引入两个插件"></script>
<script>
Title2Tip.config.autoConvert = true
Title2Tip.refresh()
ImageViewer.init()
</script>

悬浮展示文字提示，点击图片直接进入全屏缩放预览，电商、相册页面交互体验大幅提升。

八、浏览器兼容与项目优势

兼容现代浏览器 Chrome/Firefox/Safari/Edge，不支持 IE11
核心优势

完全零依赖，无任何第三方库捆绑
极简 API，新手几分钟上手
支持静态页面与前后端分离项目
图集轮播、滚轮缩放、拖拽平移全套看图功能
可与 title2tip-js 配套形成完整图文交互组件
MIT 开源协议，商用无限制

九、适用业务场景

电商商品详情、商品相册大图预览
博客、资讯网站插图放大查看
后台管理系统表单附件、报表图片
相册、图库类 H5 页面
轻量化静态官网、文档站点
搭配 title2tip-js 实现图片悬浮说明 + 预览

十、总结

image-viewer-js 补齐了轻量化前端项目的图片预览短板，和 title2tip-js 形成配套图文交互工具链。两者均采用零依赖、极简设计，不增加项目打包负担，无需复杂配置即可实现专业级悬浮提示 + 全屏看图交互。如果你的项目需要轻量化图片预览功能，不想引入重型 UI 库的看图组件，这款开源插件是性价比极高的选择。

开源地址：https://github.com/JackieZheng/image-viewer-js # 前端图片插件 #图片预览 #零依赖 JS 组件 #Tooltip 配套工具 #开源前端工具