ImageViewer 图片查看器 - 使用说明文档

📖 简介

ImageViewer 是一个轻量级的纯 JavaScript 图片查看器库，无需任何第三方依赖。提供了丰富的交互功能，包括缩放、拖拽、键盘快捷键等，适用于各种 Web 项目。
特点：

🚀 零依赖，纯原生 JavaScript
📦 体积小巧，代码简洁
🎨 界面美观，交互流畅
📱 响应式设计，支持移动端
⚡ 性能优秀，内存占用低

🎯 功能特性

核心功能

功能	描述
遮罩层显示	黑色半透明背景（90%透明度）
图片居中	自动将图片居中显示在视口中
尺寸自适应	默认大小不超过视口的 90%
滚轮缩放	向上滚动放大，向下滚动缩小
拖拽移动	缩放后可用鼠标拖拽查看
ESC关闭	按 ESC 键快速关闭
点击关闭	点击遮罩层或关闭按钮关闭
防止背景滚动	打开时禁止背景页面滚动
响应式设计	自动适配不同屏幕尺寸

键盘快捷键

按键	功能
`ESC`	关闭图片查看器

鼠标操作

操作	功能
滚轮向上	放大图片
滚轮向下	缩小图片
点击拖拽	移动图片（仅在缩放后可用）
点击遮罩	关闭查看器
点击关闭按钮	关闭查看器

📥 安装

方式1：直接引入

下载 image-viewer.js 文件，然后在 HTML 中引入：

<script src="path/to/image-viewer.js"></script>

方式2：ES6 模块

import ImageViewer from './image-viewer.js';

方式3：NPM（如果发布到 npm）

npm install your-image-viewer

const ImageViewer = require('your-image-viewer');// 或import ImageViewer from 'your-image-viewer';

🚀 快速开始

基础用法

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>图片查看器示例</title>
</head>
<body>
  <img src="photo.jpg" id="myImage" style="cursor: pointer;">

  <script src="image-viewer.js"></script>
  <script>
    // 创建查看器实例
    const viewer = new ImageViewer();

    // 绑定图片点击事件
    document.getElementById('myImage').addEventListener('click', function() {
      viewer.open(this.src);
    });
  </script>
</body>
</html>

便捷方法（推荐）

使用 bindImages 静态方法快速为多张图片添加查看功能：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>图片查看器 - 便捷方法</title>
</head>
<body>
  <!-- 为图片添加 data-viewer 属性 -->
  <img src="photo1.jpg" data-viewer alt="图片1">
  <img src="photo2.jpg" data-viewer alt="图片2">
  <img src="photo3.jpg" data-viewer alt="图片3">

  <script src="image-viewer.js"></script>
  <script>
    // 一行代码搞定！
    ImageViewer.bindImages('img[data-viewer]');
  </script>
</body>
</html>

🔧 配置选项

构造函数参数

const viewer = new ImageViewer({
  maxZoom: 5,        // 最大缩放倍数，默认 5
  minZoom: 0.5,      // 最小缩放倍数，默认 0.5
  zoomStep: 0.1      // 每次滚轮缩放的步长，默认 0.1
});

配置示例

// 允许更大的缩放范围
const viewer = new ImageViewer({
  maxZoom: 10,
  minZoom: 0.2,
  zoomStep: 0.2
});
// 更精细的缩放控制
const viewer2 = new ImageViewer({
  maxZoom: 3,
  minZoom: 0.8,
  zoomStep: 0.05
});

📚 API 文档

实例方法

`viewer.open(src)`

打开图片查看器并显示指定图片。
参数：

src (string) - 图片的 URL 地址

示例：

const viewer = new ImageViewer();
viewer.open('https://example.com/photo.jpg');

`viewer.close()`

关闭图片查看器。
示例：

viewer.close();

`viewer.destroy()`

销毁查看器实例，移除所有事件监听器和 DOM 元素。
示例：

viewer.destroy();

静态方法

`ImageViewer.bindImages(selector)`

批量为图片添加点击查看功能。
参数：

selector (string) - CSS 选择器，默认为 'img[data-viewer]'

返回值：

ImageViewer - 返回创建的查看器实例

示例：

// 使用默认选择器const viewer = ImageViewer.bindImages();// 自定义选择器const viewer2 = ImageViewer.bindImages('.gallery img');// 为特定类名的图片添加查看功能const viewer3 = ImageViewer.bindImages('.viewable');

💡 使用场景示例

场景1：相册画廊

<div class="gallery">
  <img src="photo1.jpg" data-viewer>
  <img src="photo2.jpg" data-viewer>
  <img src="photo3.jpg" data-viewer>
  <img src="photo4.jpg" data-viewer>
</div>

<style>
  .gallery {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
    gap: 20px;
    padding: 20px;
  }
  .gallery img {
    width: 100%;
    height: 200px;
    object-fit: cover;
    cursor: pointer;
    border-radius: 8px;
    transition: transform 0.3s;
  }
  .gallery img:hover {
    transform: scale(1.05);
  }
</style>

<script>
  ImageViewer.bindImages('img[data-viewer]');
</script>

场景2：产品详情页

<div class="product">
  <img src="product-main.jpg" class="product-image" alt="产品主图">
  <div class="thumbnails">
    <img src="product-thumb1.jpg" class="thumb" data-full="product-1.jpg">
    <img src="product-thumb2.jpg" class="thumb" data-full="product-2.jpg">
    <img src="product-thumb3.jpg" class="thumb" data-full="product-3.jpg">
  </div>
</div>

<script>
  const viewer = new ImageViewer();
  
  // 主图点击查看
  document.querySelector('.product-image').addEventListener('click', function() {
    viewer.open(this.src);
  });
  
  // 缩略图点击查看大图
  document.querySelectorAll('.thumb').forEach(thumb => {
    thumb.addEventListener('click', function() {
      const fullSrc = this.getAttribute('data-full');
      viewer.open(fullSrc);
    });
  });
</script>

场景3：文章内图片

<article class="blog-post">
  <h1>文章标题</h1>
  <p>这是一段文字...</p>
  <img src="article-image1.jpg" class="content-image" alt="配图1">
  <p>更多内容...</p>
  <img src="article-image2.jpg" class="content-image" alt="配图2">
</article>

<script>
  ImageViewer.bindImages('.content-image');
</script>

场景4：动态加载图片

const viewer = new ImageViewer();

// Ajax 获取图片数据
fetch('/api/images')
  .then(response => response.json())
  .then(images => {
    const container = document.getElementById('image-container');
    
    images.forEach(image => {
      const img = document.createElement('img');
      img.src = image.thumbnail;
      img.dataset.full = image.fullSize;
      img.style.cursor = 'pointer';
      
      img.addEventListener('click', function() {
        viewer.open(this.dataset.full);
      });
      
      container.appendChild(img);
    });
  });

场景5：多个独立查看器

// 为不同区域创建独立的查看器实例
const galleryViewer = new ImageViewer({
  maxZoom: 8,
  zoomStep: 0.2
});

const productViewer = new ImageViewer({
  maxZoom: 3,
  zoomStep: 0.1
});

// 画廊图片
document.querySelectorAll('.gallery img').forEach(img => {
  img.addEventListener('click', () => galleryViewer.open(img.src));
});

// 产品图片
document.querySelectorAll('.product img').forEach(img => {
  img.addEventListener('click', () => productViewer.open(img.src));
});

🎨 自定义样式

虽然 ImageViewer 使用内联样式，但你仍然可以通过 CSS 覆盖默认样式：

/* 自定义遮罩层背景 */
.image-viewer-overlay {
  background: rgba(0, 0, 0, 0.95) !important;
}

/* 自定义关闭按钮样式 */
.image-viewer-close {
  background: rgba(255, 0, 0, 0.8) !important;
  font-size: 30px !important;
  width: 40px !important;
  height: 40px !important;
}

.image-viewer-close:hover {
  background: rgba(255, 0, 0, 1) !important;
}

/* 自定义图片边框 */
.image-viewer-image {
  border: 3px solid white !important;
  box-shadow: 0 0 30px rgba(0, 0, 0, 0.5) !important;
}

⚠️ 注意事项

1. 跨域图片

如果图片来自其他域名，请确保服务器配置了正确的 CORS 头：

Access-Control-Allow-Origin: *

2. 图片加载失败

建议添加错误处理：

const img = document.querySelector('#myImage');
img.addEventListener('error', function() {
  console.error('图片加载失败');
});

3. 移动端优化

在移动端使用时，建议添加 viewport 元标签：

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

4. 内存管理

如果页面有大量图片或长时间运行，建议在不需要时销毁查看器：

const viewer = new ImageViewer();// 使用完毕后viewer.destroy();

5. 性能建议

使用适当大小的图片，避免加载过大的原图
考虑使用缩略图 + 大图的方案
大量图片时使用懒加载技术

🔍 故障排除

问题1：图片不能拖拽

原因： 只有当图片缩放大于 1 时才能拖拽。
解决： 先使用滚轮放大图片，然后再尝试拖拽。

问题2：关闭按钮不显示

原因： 可能被其他元素遮挡或 z-index 不够高。
解决： 检查页面其他元素的 z-index 值，确保不超过 9999。

问题3：背景仍然可以滚动

原因： 可能有其他 JavaScript 代码干扰了 overflow 属性。
解决： 检查其他代码，或手动设置：

viewer.open(src);document.body.style.overflow = 'hidden';

问题4：滚轮缩放不流畅

原因： zoomStep 值设置过大。
解决： 调小 zoomStep 值：

const viewer = new ImageViewer({  zoomStep: 0.05  // 更精细的缩放});

🌐 浏览器兼容性

浏览器	版本	支持情况
Chrome	60+	✅ 完全支持
Firefox	55+	✅ 完全支持
Safari	11+	✅ 完全支持
Edge	79+	✅ 完全支持
IE	11	⚠️ 需要 polyfill

IE11 支持： 需要添加以下 polyfill：

Promise
Object.assign
Array.from

📄 许可证

MIT License