Panzoom 开源项目教程

2026-01-18 10:38:52作者：傅爽业Veleda

项目介绍

Panzoom 是一个用于在网页上实现平移和缩放功能的 JavaScript 库。它可以帮助开发者轻松地在任何 HTML 元素上添加平移和缩放交互，适用于图片查看器、地图应用、图表等多种场景。Panzoom 的设计理念是轻量级和易用性，使得开发者可以快速集成并实现所需功能。

项目快速启动

安装

你可以通过 npm 或直接在 HTML 文件中引入 Panzoom 库来使用它。

通过 npm 安装

npm install @panzoom/panzoom

通过 CDN 引入

<script src="https://unpkg.com/@panzoom/panzoom@latest/dist/panzoom.min.js"></script>

基本使用

以下是一个简单的示例，展示如何在 HTML 元素上实现平移和缩放功能。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Panzoom 示例</title>
  <style>
    #panzoom-element {
      width: 600px;
      height: 400px;
      border: 1px solid black;
      overflow: hidden;
    }
    #panzoom-element img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  </style>
</head>
<body>
  <div id="panzoom-element">
    <img src="path/to/your/image.jpg" alt="Panzoom Image">
  </div>

  <script src="https://unpkg.com/@panzoom/panzoom@latest/dist/panzoom.min.js"></script>
  <script>
    const elem = document.getElementById('panzoom-element');
    const panzoom = Panzoom(elem, {
      maxScale: 5,
      minScale: 0.5
    });
    elem.addEventListener('wheel', panzoom.zoomWithWheel);
  </script>
</body>
</html>

应用案例和最佳实践

图片查看器

Panzoom 非常适合用于创建图片查看器，用户可以通过鼠标或触摸手势对图片进行平移和缩放。以下是一个简单的图片查看器示例：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>图片查看器</title>
  <style>
    #image-viewer {
      width: 800px;
      height: 600px;
      border: 1px solid #ccc;
      overflow: hidden;
      position: relative;
    }
    #image-viewer img {
      width: 100%;
      height: 100%;
      object-fit: contain;
    }
  </style>
</head>
<body>
  <div id="image-viewer">
    <img src="path/to/your/image.jpg" alt="Image">
  </div>

  <script src="https://unpkg.com/@panzoom/panzoom@latest/dist/panzoom.min.js"></script>
  <script>
    const viewer = document.getElementById('image-viewer');
    const panzoom = Panzoom(viewer, {
      maxScale: 10,
      minScale: 0.1
    });
    viewer.addEventListener('wheel', panzoom.zoomWithWheel);
  </script>
</body>
</html>

地图应用

Panzoom 也可以用于地图应用，用户可以通过平移和缩放来浏览地图。以下是一个简单的地图应用示例：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>地图应用</title>
  <style>