@panzoom/panzoom用法总结

panzoom用法总结

Panzoom 是一个小型库（压缩后约 3.7kb），用于为元素添加平移和缩放功能。Panzoom 不是使用绝对定位或设置宽度和高度，而是使用 CSS 转换来利用浏览器中的硬件/GPU 加速，这意味着元素可以是任何东西：图像、视频、iframe、画布、文本、任何东西.

Panzoom 包括对触摸手势的支持，甚至支持缩放手势。它非常适合移动和桌面浏览器。它在任何支持的地方默认使用指针事件。

SVG 支持

Panzoom 支持直接平移和缩放 SVG 元素。

在 IE11 中，CSS 动画/过渡不适用于 SVG 元素，至少对于转换样式。它们确实在其他浏览器中工作。

可以使用setTransform选项在 IE11 中手动实现过渡，并集成一个用于 javascript 动画的补间库（例如tween.js）。

安装
使用 npm：

• List item

$ npm install --save @panzoom/panzoom

const Panzoom = require('@panzoom/panzoom')

在匿名模块中使用 AMD 加载器：

define(['@panzoom/panzoom'], function (Panzoom) {
  const elem = document.getElementById('panzoom-element')
  Panzoom(elem)
})

使用脚本标签：

< script  src =" / js / panzoom.js " > </ script >

使用来自 CDN 的脚本标签：

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

用法

const elem = document.getElementById('panzoom-element')
const panzoom = Panzoom(elem, {
  maxScale: 5
})
panzoom.pan(10, 10)
panzoom.zoom(2, { animate: true })

// Panning and pinch zooming are bound automatically (unless disablePan is true).
// There are several available methods for zooming
// that can be bound on button clicks or mousewheel.
// 平移和双指缩放会自动绑定（除非 disablePan 为 true）。
// 有几种可用的缩放方法
// 可以绑定在按钮点击或鼠标滚轮上。
button.addEventListener('click', panzoom.zoomIn)
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)

常问问题
1.transform-origin它是什么以及为什么要添加到 panzoom 元素中？

• transform-origin是从被施加变换的原点。Panzoom 确保默认值设置为它期望计算焦点缩放的值。
• HTML 元素默认为“50% 50%”。
• SVG 元素默认为“0 0”。

2. 我正在使用带有标签的Panzoom，但它不起作用。怎么了？

对象元素可以吞噬事件，使其永远不会到达 Panzoom。要解决此问题，请禁用标记pointer-events: none上的指针事件 ( )并使用包装器调用 Panzoom。

3. 我的链接失效了！如何在 panzoom 元素中启用锚点？

将类options.excludeClass（默认为"panzoom-exclude"）添加到您想要可点击的任何元素。Panzoom 将在处理事件之前检查此类。或者，向exclude选项添加对元素的引用，或event.stopImmediatePropagation()在可点击元素上调用事件处理程序。

关于 Panzoom 的异步性质的说明
在某些情况下，设置一件事然后同步设置另一件事不会按预期工作。

例如，以下通常工作正常。

const panzoom = Panzoom(elem)
panzoom.zoom(2)
panzoom.pan(100, 100)

但是，您可能会发现contain设置选项后事情开始破裂。
这是因为为了让 Panzoom 检索正确的尺寸，需要绘制比例尺。
如果您发现事情看起来不太正确，请尝试以下操作…

panzoom.zoom(2)
setTimeout(() => panzoom.pan(100, 100))

Documentation文档

Panzoom

▸ Panzoom(elem, options?): PanzoomObject

参数

名称	类型
elem	HTMLElement / SVGElement
options?	Omit< PanzoomOptions, “force”>
return
PanzoomObject

PanzoomOptions

包括MiscOptions，PanOptions，和ZoomOptions

MiscOptions其他选项

这些选项可以传递给Panzoom()，以及任何平移或缩放功能。一个例外是force，它只能传递到类似的方法pan()或zoom()，但不Panzoom()还是setOptions()因为它不应该被全局设置。

animate动画

•Optional animate：（boolean默认值：false）

是否动画过渡

canvas

• Optional canvas: boolean (Default: false)
此选项将 Panzoom 元素的父元素视为画布。实际上，Panzoom 将向下处理程序绑定到父元素而不是 Panzoom 元素，以便“画布”上任何位置的指针事件移动其子元素。见问题#472。

注意：将此选项设置为true也会更改cursor应用样式的位置（即父项）。

duration持续时间

•Optional duration：（number默认值：200）

转换持续时间（毫秒）

easing过度

•Optional easing：（string默认值：“缓入缓出”）

用于过渡的 CSS Easing

exclude排除

•Optional exclude：Element[]（默认值：[]）

将元素添加到此数组，这些元素应该从 Panzoom 处理中排除。还检查事件目标的祖先。例如，不应传播点击事件的链接和按钮。

excludeClass

• Optional excludeClass：（string默认值：“panzoom-exclude”）

将此类添加到 Panzoom 元素中要从 Panzoom 处理中排除的任何元素。该元素的子元素也将被排除在外。例如，不应传播点击事件的链接和按钮。

force

•Optional force：boolean

force应该谨慎使用来临时覆盖和忽略诸如 disablePan、disableZoom 和 panOnlyWhenZoomed 之类的选项。此选项不能传递给 Panzoom 构造函数或 setOptions（以避免全局设置此选项）。

// Overrides disablePan and panOnlyWhenZoomed.  覆盖 disablePan 和 panOnlyWhenZoomed 
panzoom.pan(50, 100, { force: true })
// Overrides disableZoom 覆盖 disableZoom 
panzoom.zoom(1, { force: true })

noBind无绑定

• Optional noBind：boolean

跳过绑定默认的 Panzoom 事件侦听器

origin

•Optional origin：string

更改此设置的风险由您自行承担。 的transform-origin是从被施加变换的原点。默认值：'50% 50%'用于 HTML 和’0 0’SVG。设置默认值是因为更改transform-originSVG 元素在 IE 中不起作用。

改变它应该适用于很多事情，但它会破坏焦点缩放，假设默认设置为进行更复杂的计算。

同样，在 IE 中为 SVG 更改此设置根本不起作用。

overflow

•Optional overflow：（string默认值：“隐藏”）

父级的溢出 CSS 值。默认为“隐藏”

setTransform设置变换

• Optional setTransform : ( elem: HTMLElement| SVGElement, __namedParameters: CurrentValues, _options?: PanzoomOptions) =>void

使用适当的前缀设置转换

覆盖变换设置器。这主要是公开的，因此用户可以设置变换的其他部分，而不是缩放和平移。默认在 src/css.ts 中定义。

// This example always sets a rotation 此示例始终设置旋转
// when setting the scale and translation 设置缩放和平移时
const panzoom = Panzoom(elem, {
  setTransform: (elem, { scale, x, y }) => {
    panzoom.setStyle('transform', `rotate(0.5turn) scale(${scale}) translate(${x}px, ${y}px)`)
  }
})

参数

名称	类型
elem	HTMLElement /SVGElement
__namedParameters	CurrentValues
_options?	PanzoomOptions
returns
void

silent沉默的

•Optional silent：boolean

静默所有事件

startScale

• Optional startScale :（number默认值：1）

用于设置开始变换的比例

startX

• Optional startX :（number默认值：0）

用于设置开始变换的 X 值

startY

• Optional startY :（number默认值：0）
Y 用于设置开始变换的值

touchAction触摸动作

• Optional touchAction：（string默认值：“无”）

该值用于在 Panzoom 元素及其父元素上设置触摸动作。这是必需的，因为移动设备上的本机滚动会干扰平移和双指缩放。将此设置为空字符串以重新启用移动设备上的滚动，但请注意滚动和平移不能同时工作。

Methods方法

handleStartEvent处理开始事件

▸ Optional handleStartEvent ( event)：void

在第一个指针事件上，当平移开始时，默认的 Panzoom 行为是 在该事件上调用 event.preventDefault()和event.stopPropagation()。前者几乎肯定是必需品；后者在 Panzoom 元素中启用 Panzoom 元素。

但在某些情况下，默认行为不是所需的行为。设置此选项以覆盖该行为。

// Only call preventDefault(). 只调用 preventDefault() 
Panzoom(elem, {
  handleStartEvent: (event) => {
    event.preventDefault()
  }
})
// Do nothing. 什么都不做。
// This can change dragging behavior on mobile.这可以改变移动设备上的拖动行为。
Panzoom(elem, {
  handleStartEvent: () => {}
})

参数

名称	类型
event	Event
return
void

PanOptions（包括 MiscOptions）

contain

•Optional contain：“inside”|“outside”

在父级内部或外部包含 panzoom 元素。内部： panzoom 元素比其父元素小，不能平移到外部。外部： panzoom 元素比其父元素大，不能平移到内部。换句话说，元素周围不会显示任何空白区域。

注意：密封盘调整不受该disablePan选项的影响。

cursor光标

•Optional cursor：（string默认值：“移动”）

在 panzoom 元素上设置的光标样式

disablePan禁用平移

• Optional disablePan：（boolean默认值：false）

禁用平移功能。注意： disablePan 不影响焦点缩放或包含选项。该元素仍将相应地平移。

disableXAxis

• Optional disableXAxis :（boolean默认值：false）

仅在 Y 轴上平移

disableYAxis

• Optional disableYAxis :（boolean默认值：false）

仅在 X 轴上平移

panOnlyWhenZoomed

• Optional panOnlyWhenZoomed :（boolean默认值：false）
当比例等于起始值时禁用平移

relative相对的

•Optional relative：（boolean默认值：false）

将 x 和 y 值传递给 .pan() 时，将这些值视为相对于它们的当前值

ZoomOptions（包括 MiscOptions）

disableZoom禁用缩放

• Optional disableZoom :（boolean默认值：false）
禁用缩放功能

focal焦点

•Optional focal：Object

缩放到 panzoom 元素上的给定点。该点预计与 panzoom 元素的尺寸相关，与父尺寸无关。

类型声明

名称	类型
x	number
y	number

maxScale最大比例

• Optional maxScale：（number默认值：4）

缩放时的最大比例

minScale最小比例

• Optional minScale :（number默认值：0.125）

缩放时的最小比例

step步长

•Optional step：（number默认值：0.3）

当使用鼠标滚轮缩放、双指缩放或使用 zoomIn/zoomOut 时，该步骤会影响缩放计算

PanzoomObject全景对象

这些方法在初始化 Panzoom 后可用。

eventNames事件名称

•eventNames：Object

此对象公开 Panzoom 使用的事件名称，具体取决于当前浏览器对指针或触摸事件的支持。

Type declaration类型声明

名称	类型
down	string
move	string
up	string

方法

bind绑定

▸bind（）：void

将默认的向下、移动和向上事件侦听器绑定到 Panzoom 元素。这通常不需要调用。在创建新的 Panzoom 对象时默认调用它，但可以跳过该noBind选项。

const panzoom = Panzoom(elem, { noBind: true })
// ...
panzoom.bind()

returns
void

destroy销毁

▸destroy（）：void
删除绑定到 Panzoom 元素的所有事件侦听器
return
void

getOptions 获取选项

▸ getOptions ()：PanzoomOptions

返回当前选项对象的副本

returns
PanzoomOptions

getPan

▸ getPan ()：Object

获取当前的 x/y 平移
returns
Object

名称	类型
x	number
y	number

getScale获取比例

▸ getScale ()：number
获取当前比例
returns
number

pan平移

▸平移( x, y, panOptions?)：CurrentValues

将 Panzoom 元素平移到给定的 x 和 y 坐标

// Translates the element to 50px, 100px 将元素转换为 50px, 100px 
panzoom.pan(50, 100)
// Pans the element right 10px and down 10px from its current position
// 将元素从当前位置向右平移10像素，向下平移 10 像素 
panzoom.pan(10, 10, { relative: true })

参数

名称	类型
x	string /number
y	string /number
panOptions?	PanOptions
returns
CurrentValues

reset重置

▸reset( resetOptions?)：CurrentValues

将平移和缩放重置为 startX、startY 和 startScale。默认情况下动画，忽略全局选项。通过{ animate: false }覆盖。复位忽略disablePan，disableZoom和panOnlyWhenZoomed选项。通过{ force: false }覆盖。

panzoom.reset()
panzoom.reset({ animate: false })

参数

名称	类型
resetOptions?	PanzoomOptions
return
CurrentValues

resetStyle重置样式

▸resetStyle（）：void

重置 Panzoom 元素及其父元素上设置的样式（例如溢出、光标等）

panzoom.resetStyle()

returns
void

setOptions设置选项

▸ setOptions（options?）：void

更改 Panzoom 实例上的任意数量的选项。设置一些选项会产生副作用。例如，更改光标选项也将设置光标样式。

const  panzoom  =  Panzoom ( elem ,  {  cursor : 'move'  } ) 
// ... 
panzoom . setOptions ( {  cursor : 'default'  } )

参数

名称	类型
options?	PanzoomOptions
return
void

setStyle设置样式

▸ setStyle ( name, value):void

在 Panzoom 元素上设置前缀样式的便捷方法

参数

名称	类型
name	string
value	string
return
void

zoom缩放

▸zoom( scale, zoomOptions?)：CurrentValues

将 Panzoom 元素缩放到给定的比例

panzoom.zoom(2.2)
panzoom.zoom(2.2, { animate: true })

参数

名称	类型
scale	number
zoomOptions?	ZoomOptions
return
CurrentValues

zoomIn放大

▸zoomIn( zoomOptions?)：CurrentValues

使用选项中设置的预定增量放大。默认情况下动画，忽略全局选项。通过{ animate: false }覆盖。

panzoom.zoomIn()
panzoom.zoomIn({ animate: false })

参数

名称	类型
zoomOptions?	ZoomOptions
return
CurrentValues

zoomOut缩小

▸zoomOut( zoomOptions?)：CurrentValues

使用选项中设置的预定增量缩小。默认情况下动画，忽略全局选项。通过{ animate: false }覆盖。

panzoom.zoomOut()
panzoom.zoomOut({ animate: false })

参数

名称	类型
zoomOptions?	ZoomOptions
return
CurrentValues

zoomToPoint

▸ zoomToPoint ( scale, point, zoomOptions?):CurrentValues

使用给定的指针/触摸/鼠标事件或构造点将 Panzoom 元素缩放到焦点。clientX/clientY 值的计算方式应pointermove与 Panzoom 元素的父级上的事件相同。

panzoom.zoomToPoint(1.2, pointerEvent)

参数

名称	类型
scale	number
point	Object
point.clientX	number
point.clientY	number
zoomOptions?	ZoomOptions
reurn
CurrentValues

zoomWithWheel(鼠标滚轮缩放)

▸ zoomWithWheel ( event, zoomOptions?):CurrentValues

使用给定的 WheelEvent 将 Panzoom 元素缩放到焦点
这是一个可能无法处理所有用例的便利功能。其他情况应使用zoomToPoint 方法或zoom方法的焦点选项处理解决方案。

注意事项：

• 焦点变焦平移调整不受该disablePan选项的影响。
• 使用滚轮缩放时不应使用 animate，因此始终禁用。

// Bind to mousewheel 绑定到鼠标滚轮
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)
// Bind to shift+mousewheel.  绑定到 shift+ 
elem.parentElement.addEventListener('wheel', function (event) {
  if (!event.shiftKey) return
  // Panzoom will automatically use `deltaX` here instead
  // of `deltaY`. On a mac, the shift modifier usually
  // translates to horizontal scrolling, but Panzoom assumes
  // the desired behavior is zooming.
  // Panzoom 将在这里自动使用 `deltaX` 而不是
  //`deltaY`。在 Mac 上，shift 修饰符通常
  // 转换为水平滚动，但 Panzoom 假设
  // 所需的行为是缩放
  panzoom.zoomWithWheel(event)
})

参数

名称	类型
event	WheelEvent
zoomOptions?	ZoomOptions
return
CurrentValues

CurrentValues(当前值)

isSVG

• Optional isSVG: boolean

scale

•scale：number

X

• x：number

Y

• y：number

Event

以下事件可用作使用本机CustomEvent API的 panzoom 元素上的自定义事件。以与添加任何其他事件相同的方式添加侦听器。

elem.addEventListener('panzoomchange', (event) => {
  console.log(event.detail) // => { x: 0, y: 0, scale: 1 }
})

关于所有事件的注释

作为参数传递给侦听器的事件对象将始终具有detail具有以下属性的对象：
当前x值
当前y值
目前 scale
originalEvent具有触发 panzoom 事件的原始事件的属性（如果适用）。例如，originalEvent对于一个属性panzoomstart事件将是或者是pointerdown，touchstart，或mousedown事件。
Events can be silenced when the silentoption is set to true, either globally or when passed to pan, any zoommethod, or reset.
避免在这些事件处理程序中放置太多逻辑，因为它可能会影响平移或缩放的性能。

“panzoomstart”

当用户在移动设备上开始移动或捏缩放手势时触发。

“panzoomchange”

每当有平移、缩放或重置时触发。请注意，直接调用options.setTransform不会触发此事件。

“panzoomzoom”

每当通过任何 Panzoomzoom方法直接或内部更改缩放时触发。

“panzoompan”

每当锅被pan方法直接或内部更改时触发。

“panzoomend”

当用户在移动设备上完成移动或完成捏缩放手势时触发。

“panzoomreset”

每当调用重置时触发。