@dash14/svg-pan-zoom

中文文档

4.1.0发布于 2026/10/30BSD-2-ClauseTypeScriptES Module零依赖构建来源已验证近 30 天下载 8.7万

JavaScript 库用于从鼠标上平整并缩放 SVG 图像, 触摸并程序化 .

文档目录24 节

支助
错误和问题
已解决的臭虫和已执行的特性
捐款/申请
演示文稿
如何使用
嵌入远程文件
使用自定义视图
倾听关于儿童SVG元素的泛/视频事件
自定义事件支持
保持内容可见/ Limit pan
公共 API
如何测试
常见问题和问题
SVG 高度已断开
隐藏 SVG 时调用库方法丢出错误
初始化方面的业绩问题
平整/分区期间的绩效问题
如何限制缩放/扩展
如何添加动画
错误用于 object 编号 : embed 或动态加载的 SVG
支持的浏览器
有关工作
许可证

这间图书馆是从 https://github.com/bumbu/svg-pan-zoom 互联网档案馆的存檔,存档日期2013-12-22 目标用进去 v- 网络图。。。 .

现将原文修改如下:

用多触摸来添加支持平板并缩放 .
导出类型定义 .
不访问 window 财务报告和审定财务报表 document 当导出模块时.
指定 {passive: false} 明确警告事件的听众.
只有ES舱:无 <script> 环球,AMD或CommonJS构建.

现公布于npm @dash14/svg-pan-zoom数字 :

npm install @dash14/svg-pan-zoom

svg-pan-zoom 库

HTML中SVGs的简单泛/zoom解决方案. 它增加了鼠标卷轴,双击和平板的活动听众,并且可以选择提供:

JavaScript API 控制平板和缩放行为
潘和祖姆事件处理器
屏幕上缩放控制

它可以进行交叉浏览,并支持HTML的内置SVG和SVG object 或者说 embed 要素.

支助

错误和问题

此分叉不带问题; 报告问题 v-网络图的问题包含一个可复制的例子,库版本,以及您的浏览器和OS.

已解决的臭虫和已执行的特性

如果解出一个错误或执行一个可能对他人有用的特性,那么欢迎您创建拉出请求.

捐款/申请

最佳贡献方式是创建拉出请求. 为了创建牵引请求:

叉此寄存器
克隆寄存器叉( 在前一步创建) 本地( 在您的机器上)
确保本地安装节点和 pnpm
在控制台中 :
- cd 输入项目文件夹
- 运行 pnpm install
- 运行 pnpm start 将监听源文件更改( in) src 文件夹),并将自动构建分发文件
- 运行 pnpm run build 将构建分发文件
- 运行 pnpm run format 将格式化源文件
- 运行 pnpm test 将输入检查 dist/svg-pan-zoom.d.ts 用无头铬进行测试一次性安装铬 pnpm exec playwright install --only-shell chromium
使用 pnpm start 或者说 pnpm run build
更改完成后, 格式化为 pnpm run format 测试一下 pnpm test
只执行有意义的修改,并指定重建的分发文件(dist 和他们一起。 CI 失败时 dist 和源头不同
将更改推入叉中
创建拉动请求

演示文稿

实例演示从克隆运行: 开始 pnpm run server 并开放http://localhost:301/demo/.

如何使用

导入软件包,然后调用init方法:

import svgPanZoom from '@dash14/svg-pan-zoom';

var panZoomTiger = svgPanZoom('#demo-tiger');
// or
var svgElement = document.querySelector('#demo-tiger')
var panZoomTiger = svgPanZoom(svgElement)

函数的第一个参数应当是 SVG 元素的 CSS 选择器或 DOM 元素 .

如果您想要推翻默认, 您可以选择指定一个或多个参数 :

svgPanZoom('#demo-tiger', {
  viewportSelector: '.svg-pan-zoom_viewport'
, panEnabled: true
, controlIconsEnabled: false
, zoomEnabled: true
, dblClickZoomEnabled: true
, mouseWheelZoomEnabled: true
, preventMouseEventsDefault: true
, zoomScaleSensitivity: 0.2
, minZoom: 0.5
, maxZoom: 10
, fit: true
, contain: false
, center: true
, refreshRate: 'auto'
, beforeZoom: function(){}
, onZoom: function(){}
, beforePan: function(){}
, onPan: function(){}
, onUpdatedCTM: function(){}
, customEventsHandler: {}
, eventsListenerElement: null
});

如果指定了任何参数,它们必须具有下列值类型:

'viewportSelector'可以是查询Selector字符串或SVGElement.
“扩展”必须是真实的或虚假的。默认是真实的.
控制器必须真实或虚假默认是虚假的.
“可实现”必须是真实的或虚假的。默认是真实的.
"dblClickZoomEnabled"必须是真实的或虚假的. 默认是真实的.
"MouseWheelZoomEnabled"必须是真实的或虚假的. 默认是真实的.
预防MouseEvents Defaults"必须是真实的或虚假的. 默认是真实的.
"Zoom ScaleSensition" 必须是平分。默认为0.2.
"明祖"必为"斯". 默认为0.5.
"马克斯祖姆"一定是一个斯卡尔. 默认为10.
"适合"必须是真实的或虚假的. 默认是真实的.
'被"必须是真实的或虚假的. 默认是虚假的.
"中心"必须是真实或虚假的. 默认是真实的.
"新鲜"必须是数字或"自动"
'在Zoom之前'必须是在缩放变化前被调用的回调函数.
“ 在Zoom” 必须是缩放变化时需要调用的调用函数 .
'Pan前'必须是泛变前需要调用的回调函数.
当泛变换时,“ on Pan”必须是调用函数.
习惯事件 Handler 必须是一个对象 init 财务报告和审定财务报表 destroy 参数作为函数.
"事件倾听者lement"必须是SVGElement或无效.

beforeZoom 将使用两个浮动属性:旧Zoom和新Zoom. 若为 beforeZoom 将返回 false 然后放大会停止.

onZoom 调用后调用一个代表新缩放比例的浮点属性.

beforePan 将调用两个属性:

oldPan
newPan

这些对象中每一个都有两个属性(x和y),代表当前平坦(在X和Y轴上).

若为 beforePan 将返回 false 或对象 {x: true, y: true} 然后,将停止喘息. 如果您想要防止只用一轴平板, 那么返回一个类型对象 {x: true, y: false}。。。 . 您可以通过返回提供替代值来改变 X 和 Y 轴上的平板值 {x: 10, y: 20}。。。 .

小心点! 如果您通过返回自定义值来改变平面 {x: 10, y: 20} 它只会更新当前泛步骤。如果用鼠标/触摸来进行平整,您必须考虑到下一个平整步骤(在您更改之后)将以不考虑被改变的数值(因为不存在)的数值来进行.

onPan 回调将调用一个属性: newPan。。。 .

小心点! 调用缩放或泛 API 方法 beforeZoom, (中文(简体) ), onZoom, (中文(简体) ), beforePan 财务报告和审定财务报表 onPan 召回可能导致无限循环.

onUpdatedCTM 等CTM更新后再打电话这与泛和放大事件同时发生.

panEnabled 财务报告和审定财务报表 zoomEnabled 仅与用户交互相关。如果其中任何选项被禁用 - 您仍然可以通过 API 缩放和平板 .

fit 优先于 contain。所以如果你设置 fit: true 接下来 contain价值并不重要.

嵌入远程文件

如果您正在嵌入这样的远程文件

<embed type="image/svg+xml" src="/path/to/my/file.svg" />
<object type="image/svg+xml" data="/path/to/my/file.svg">Your browser does not support SVG</object>

或者你正在制作 SVG 之后的页面加载然后,你将不得不呼叫 svgPanZoom 库在你的 SVG 装入后.

一个办法就是听元素的 load ,在元素完成加载前添加:

import svgPanZoom from '@dash14/svg-pan-zoom';

var embed = document.createElement('embed');
embed.type = 'image/svg+xml';
embed.src = '/path/to/my/file.svg';
embed.addEventListener('load', function(){
  svgPanZoom(embed);
});
document.body.appendChild(embed);

对于在页面的 HTML 中写入的元素,请聆听窗口的 load 相反,它是在元素装入后出现的.

使用自定义视图

如果您在 SVG 有较多的图层, 您可能想要使用自定义的视图泛区只有一个.

默认情况下:

SVGGElement 类型只有一个顶级图形元素(<g>(中文(简体) )
冲锋枪没有 transform 属性
没有其他的 SVGGELATION 有类名 svg-pan-zoom_viewport

然后将顶级图形元素用作取景口.

指定哪一层(SVGGElement)应为 泛分解 设置 svg-pan-zoom_viewport 分类名称到该元素 : <g class="svg-pan-zoom_viewport"></g>。。。 .

没有设置任何转换属性。这会使图书馆的行为不端. 如果你需要的话转换视图端口属性更好地创建嵌入组元素并设定变换改为:

<g class="svg-pan-zoom_viewport">
  <g transform="matrix(1,0,0,1,0,0);"></g>
</g>

您可以通过修改指定自己的视图选择器 viewportSelector 配置值 :

svgPanZoom('#demo-tiger', {
  viewportSelector: '.svg-pan-zoom_viewport'
});
// or
var viewportGroupElement = document.getElementById('demo-tiger').querySelector('.svg-pan-zoom_viewport');
svgPanZoom('#demo-tiger', {
  viewportSelector: viewportGroupElement
});

一个取景口 viewportSelector 发现保持其类属性不变。 Svg-pan-zoom 选择或创建的视图 svg-pan-zoom_viewport 类,这样,在同一 SVG 上的新实例就可以用默认选择器再次找到它。如果您在 SVG 上创建了新实例, 该实例已经有一个自定义 viewportSelector,通过同样的 viewportSelector 再来一次.

倾听关于儿童SVG元素的泛/视频事件

如果您想从儿童 SVG 元素中听到用户交互事件, 请使用 eventsListenerElement 选项。实例见: 演示/层.html。。。 .

自定义事件支持

您可能想要添加自定义事件支持( 例如双拍或抓取) .

可以通过设置 customEventsHandler 配置选项. customEventsHandler 应为具有以下属性的对象:

haltEventListeners: 字符串阵列
init: 函数
destroy: 函数

haltEventListeners 指定哪些默认事件听众应被禁用(以避免冲突,因为默认情况下 svg-pan-zoom 支持使用触摸事件进行平整).

init 是 svg-pan-zoom 初始化时调用的函数。对象传递到此函数. 通过的对象具有以下属性:

svgElement - SVGSVGEINGELEP(英语:SVGSVGEING) (英语)
instance - svg-pan-zoom 公共API实例

destroy 是需要 svg-pan-zoom 销毁的函数

如何与它一起使用的例子锤子.js数字 :

var options = {
  zoomEnabled: true
, controlIconsEnabled: true
, customEventsHandler: {
    // Halt all touch events
    haltEventListeners: ['touchstart', 'touchend', 'touchmove', 'touchleave', 'touchcancel']

    // Init custom events handler
  , init: function(options) {
      // Init Hammer
      this.hammer = Hammer(options.svgElement)

      // Handle double tap
      this.hammer.on('doubletap', function(ev){
        options.instance.zoomIn()
      })
    }

    // Destroy custom events handler
  , destroy: function(){
      this.hammer.destroy()
    }
  }
}

svgPanZoom('#mobile-svg', options);

您可以找到一个实例, 添加对 Hammer.js pan 的支持, 抓取和双塔p in 演示/移动.html

保持内容可见/ Limit pan

您可能想要通过不允许在 SVG 边界上覆盖来保持 SVG 内容可见 .

为此,你可以阻止或改变来自 beforePan 调用。详情请看演示/限制-pan.html 实例.

公共 API

当你打电话 svgPanZoom 它以下列方法返回对象:

启用 Pan
禁用页
已启用
平板电脑
泛边
获取潘
在Pan之前设置
设置
启用Zoom
禁用 Zoom 软件
已启用
启用控制Icons
禁用控制接口
已启用
启用 DblClick 佐姆
禁用 DblClick 佐姆
是 DblClickZoom 启用
启用 MouseWheelZoom 程序
禁用 MouseWheelZoom 软件
是 MouseWheelZoom 启用
设置Zoom 比例敏感性
设置明津
设置MaxZoom
在Zoom之前设置
设置
缩放
缩放
缩放点
缩放
缩放
缩放
已更新的计算机
获得祖姆
重设Zoom
重置Pan 时
重设
合适的
包含
中间
更新BBox
调整大小
获取大小
销毁

在程序上,将泛法称为矢量法作为第一个参数:

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

// Pan to rendered point x = 50, y = 50
panZoomTiger.pan({x: 50, y: 50})

// Pan by x = 50, y = 50 of rendered pixels
panZoomTiger.panBy({x: 50, y: 50})

到程序缩放时, 您可以使用缩放方法指定您想要的缩放值 :

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

// Set zoom level to 2
panZoomTiger.zoom(2)

// Zoom by 130%
panZoomTiger.zoomBy(1.3)

// Set zoom level to 2 at point
panZoomTiger.zoomAtPoint(2, {x: 50, y: 50})

// Zoom by 130% at given point
panZoomTiger.zoomAtPointBy(1.3, {x: 50, y: 50})

缩放相对初始的 SVG 内部缩放级别. 如果您的 SVG 在开头( 选项) fit: true),从而缩放出入出以适应可用的空间——无论如何初始尺度会是1.

或者可以使用缩放或缩放方法:

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

panZoomTiger.zoomIn()
panZoomTiger.zoomOut()
panZoomTiger.resetZoom()

如果您想要更快或更慢地缩放, 您可以使用设定的 Zoom 缩放敏感度方法来覆盖默认缩放增量 .

要在方案上启用/缩小:

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

panZoomTiger.enablePan();
panZoomTiger.disablePan();

panZoomTiger.enableZoom();
panZoomTiger.disableZoom();

适应和居中(你可以尝试 contain 改为 fit:

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

panZoomTiger.fit();
panZoomTiger.center();

如果您想要在容器大小调整后装配并居中, 则 SVG :

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

panZoomTiger.resize(); // update SVG cached size and controls positions
panZoomTiger.fit();
panZoomTiger.center();

如果您更新了 SVG( Viewport) 内容, 它的边框( 包含所有元素的虚拟框) 将会改变, 您必须调用 updateBBox数字 :

var panZoomTiger = svgPanZoom('#demo-tiger');
panZoomTiger.fit();

// Update SVG rectangle width
document.getElementById('demo-tiger').querySelector('rect').setAttribute('width', 200)

// fit does not work right anymore as viewport bounding box changed
panZoomTiger.fit();

panZoomTiger.updateBBox(); // Update viewport bounding box
panZoomTiger.fit(); // fit works as expected

如果您需要更多有关 SVG 的数据, 您可以拨打 getSizes。它将返回包含以下内容的对象:

width - SVG 缓存宽度
height - SVG缓存高度
realZoom - 说吧 (单位:千美元) 财务报告和审定财务报表 d. 国家 在视图端口上应用的变换矩阵属性
viewBox - 含有缓存大小的取景口拳击盒对象
- width
- height
- x (单位:千美元)
- y - \ n

销毁 SvgPanZoom 实例 :

// Get instance
var panZoomTiger = svgPanZoom('#demo-tiger');

panZoomTiger.destroy();
delete panZoomTiger;

如何测试

在承诺之前, 您应该通过运行格式化您的代码 pnpm run format。。。 .

测试与 dist/,所以要用 pnpm run build 先说然后运行 pnpm test,它用无头铬来运行; 安装一次 pnpm exec playwright install --only-shell chromium。。。 .

要在浏览器窗口中观看测试, 请运行 pnpm run test:headed它需要完整的铬: pnpm exec playwright install chromium。。。 .

常见问题和问题

SVG 高度已断开

因为图书馆删除 viewBox 来自 SVG 元素的属性 - 您可能体验到您的 SVG 高度变化( 通常为 150px) 。为了修复你必须增加高度 SVG 或者说 object编号 :embed。。。 .

隐藏 SVG 时调用库方法丢出错误

这个库不支持与SVG合作,因为有些浏览器隐藏时会从DOM中分离出儿童文件来隐藏这些文件. 见 bubu/svg-pan-zoom # 279 (英语) 更多细节.

初始化方面的业绩问题

如果只在库初始化时表现不佳,那么考虑将SVG的所有子元素包入一个 <g> 早点说这样,图书馆就不必创建并让所有儿童进入图书馆(这是问题的根源). 见 burbu/ svg-pan-zoom # 146 注释。。。 .

平整/分区期间的绩效问题

最常见的是大SVG文件引起的. 在那些情况下,是浏览器无法快速地处理这些SVG. 见 bubu/svg-pan-zoom # 277 更多细节.

如何限制缩放/扩展

因为放大有 minZoom 财务报告和审定财务报表 maxZoom 缩放配置选项 .

因为平整和定制的缩放体验看看有限范围示例。。。 .

如何添加动画

目前动画有两种制作方式:通过CSS或程序-看 burbu/svg-pan-zoom# 101 更多细节.

错误用于 `object`编号 :`embed` 或动态加载的 SVG

您必须确保 SVG 在初始化库前在 DOM 中装入并可用 .

检查动态负载演示。。。 .

支持的浏览器

目前版本有克罗梅,Edge,Firefox和Safari等.

这个图书馆使用了 SVGPan 软件库作为起点。 SVGPan 用于与 SVG "script" 元素,而 svg-pan-zoom 则打算与 HTML "script" 元素。。。 .

Wrapper 图书馆( 免费添加- 拉出请求欢迎 !)

许可证

SVGPan 库的代码根据以下BSD许可证获得许可:

Copyright 2009-2010 Andrea Leofreddi <[email protected]>. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of
     conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list
     of conditions and the following disclaimer in the documentation and/or other materials
     provided with the distribution.

THIS SOFTWARE IS PROVIDED BY Andrea Leofreddi "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Andrea Leofreddi OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

* The views and conclusions contained in the software and documentation are those of the
authors and should not be interpreted as representing official policies, either expressed
or implied, of Andrea Leofreddi.

SVGPan的更新和更改产生的代码根据相同的BSD许可证获得许可,该代码的作者持有的每次更改产生的代码的版权.

版本与发布记录

@dash14/svg-pan-zoom 共发布 11 个版本，首次发布于 2021/10/18；过去 12 个月发布了 5 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`4.1.0`latest	2026/10/30	12 天前
`4.0.1`	2026/10/23	19 天前
`4.0.0`	2026/10/22	19 天前
`3.6.10`	2026/10/20	21 天前
`3.6.10-beta.0`next	2026/10/19	23 天前
`3.6.9`	2022/08/11	4 年前

关于 @dash14/svg-pan-zoom 的常见问题