README

示例

Panzoom 是一个小型库 (~3.7kb gzipped)，用于向元素添加平移和缩放功能。Panzoom 不使用绝对定位或设置宽度和高度，而是使用 CSS 变换来利用浏览器中的硬件/GPU 加速，这意味着元素可以是 任何东西：一张图片、一个视频、一个 iframe、一个 canvas、文本，等等。

对于常见支持问题，请参阅 常见问题解答。

浏览器支持

以下是当前支持的浏览器列表：链接。

移动支持

iOS、Android 和 Windows Mobile 支持。

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

SVG 支持

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

在 IE11 中，CSS 动画/过渡在 SVG 元素上不工作，至少对于 transform 样式来说是这样。在其他浏览器中它们是工作的。

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

安装

使用 npm

$ npm install --save @panzoom/panzoom

使用 yarn

$ yarn add @panzoom/panzoom

Panzoom 使用 UMD，可以通过多种方式加载。

使用 ES6 导入

import Panzoom from '@panzoom/panzoom'

使用 commonjs 或 browserify

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

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

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

使用 script 标签

<script src="/js/panzoom.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.
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 和 <object> 标签时遇到了问题。什么问题？

Object 元素会消耗事件，使得事件永远不会到达 Panzoom。要修复此问题，请在 <object> 标签上禁用指针事件 (pointer-events: none) 并使用包装器调用 Panzoom。

我的链接没有工作！我如何在 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))

文档

▸ Panzoom(elem: HTMLElement | SVGElement, options?: Omit<PanzoomOptions, "force">): PanzoomObject

定义于 panzoom.ts:58

参数

返回值: PanzoomObject

PanzoomOptions

包括 MiscOptions, PanOptions, 和 ZoomOptions

MiscOptions

animate

• 可选 animate: boolean (默认: false)

定义于 types.ts:21

是否动画化过渡

canvas

• 可选 canvas: boolean (默认: false)

定义于 types.ts:32

此选项将Panzoom元素的父元素视为画布。实际上，Panzoom将按下处理程序绑定到父元素而不是Panzoom元素，因此“画布”上的任何指针事件都会移动其子元素。参见问题 #472。

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

duration

• 可选 duration: number (默认: 200)

定义于 types.ts:34

过渡的持续时间（毫秒）

easing

• 可选 easing: string (默认: "ease-in-out")

定义于 types.ts:36

用于过渡的CSS Easing

exclude

• 可选 exclude: Element[] (默认: [])

定义于 types.ts:43

将此数组中应排除在Panzoom处理之外的元素添加进来。也会检查事件目标的上层元素。例如，不应传播点击事件的链接和按钮。

excludeClass

• 可选 excludeClass: string (默认: "panzoom-exclude")

定义于 types.ts:50

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

force

• 可选 force: boolean

定义于 types.ts:66

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

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

handleStartEvent

• 可选 handleStartEvent: (event: Event) => void (默认: (e: Event) => void)

定义于 types.ts:91

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

但在某些情况下，默认值可能不是期望的行为。设置此选项以覆盖该行为。

// Only call preventDefault()
Panzoom(elem, {
  handleStartEvent: (event) => {
    event.preventDefault()
  }
})
// Do nothing.
// This can change dragging behavior on mobile.
Panzoom(elem, {
  handleStartEvent: () => {}
})

noBind

• 可选 noBind: boolean

定义于 types.ts:95

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

origin

• 可选 origin: string

在 types.ts:109 中定义

修改此属性存在风险。 transform-origin 是变换应用的起点。默认值：HTML 为 '50% 50%'，SVG 为 '0 0'。默认值设置的原因是更改 SVG 元素的 transform-origin 在 IE 中不起作用。

更改此属性可能适用于许多情况，但会破坏焦点缩放，因为它假设默认值被设置为进行更复杂的计算。

再次提醒，更改 IE 中 SVG 的此属性根本不起作用。

overflow

• 可选 overflow：字符串（默认："hidden"）

在 types.ts:111 中定义

父元素的 overflow CSS 值。默认为 'hidden'

setTransform

• 可选 setTransform：typeof setTransform（默认：setTransform）

在 types.ts:129 中定义

覆盖变换设置器。这主要是为了让用户能够设置除了缩放和平移以外的其他变换部分。默认值在 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)`)
  }
})

silent

• 可选 silent：布尔值

在 types.ts:131 中定义

静音所有事件

startScale

• 可选 startScale：数字（默认：1）

在 types.ts:137 中定义

用于设置初始变换的缩放比例

startX

• 可选 startX：数字（默认：0）

在 types.ts:133 中定义

用于设置初始变换的 X 值

startY

• 可选 startY：数字（默认：0）

在 types.ts:135 中定义

用于设置初始变换的 Y 值

touchAction

• 可选 touchAction：字符串（默认："none"）

在 types.ts:147 中定义

此值用于设置 Panzoom 元素及其父元素的 touch-action。这是必要的，因为移动设备上的原生滚动会干扰平移和捏缩操作。将其设置为空字符串以重新启用移动设备上的滚动，但请注意，滚动和平移不能同时工作。

PanOptions

包括 MiscOptions

contain

• 可选 contain："inside" | "outside"

在 types.ts:166 中定义

将 panzoom 元素包含在父元素内部或外部。内部：panzoom 元素比其父元素小，无法平移到外部。外部：panzoom 元素比其父元素大，无法平移到内部。换句话说，元素周围不会显示空白空间。

注意：包含平调整整没有受 disablePan 选项的影响。

cursor

• 可选 cursor：字符串（默认："move"）

在 types.ts:168 中定义

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

disablePan

• 可选 disablePan：布尔值（默认：false）

在 types.ts:174 中定义

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

disableXAxis

• 可选 disableXAxis：布尔值（默认：false）

定义于 types.ts:176

仅在Y轴上平移

disableYAxis

• 可选 disableYAxis: boolean (默认: false)

定义于 types.ts:178

仅在X轴上平移

panOnlyWhenZoomed

• 可选 panOnlyWhenZoomed: boolean (默认: false)

定义于 types.ts:182

当比例等于起始值时禁用平移

relative

• 可选 relative: boolean (默认: false)

定义于 types.ts:180

当向 .pan() 方法传递 x 和 y 值时，将这些值视为相对于当前值的相对值

ZoomOptions

包括 MiscOptions

disableZoom

• 可选 disableZoom: boolean (默认: false)

定义于 types.ts:187

禁用缩放功能

focal

• 可选 focal: { x: number ; y: number }

定义于 types.ts:194

将缩放元素上的指定点缩放。此点预期是相对于缩放元素尺寸的，与父尺寸无关。

类型声明

maxScale

• 可选 maxScale: number (默认: 4)

定义于 types.ts:198

缩放时的最大比例

minScale

• 可选 minScale: number (默认: 0.125)

定义于 types.ts:196

缩放时的最小比例

step

• 可选 step: number (默认: 0.3)

定义于 types.ts:200

步长影响使用鼠标滚轮、捏合缩放或使用 zoomIn/zoomOut 缩放时的缩放计算

PanzoomObject

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

bind()

• bind: () => void

定义于 types.ts:221

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

destroy()

• destroy: () => void

定义于 types.ts:223

移除绑定到 Panzoom 元素的所有事件监听器

eventNames()

• eventNames: { down: string ; move: string ; up: string }

定义于 types.ts:229

此对象公开了 Panzoom 使用的当前浏览器对 Pointer 或 Touch 事件支持的名称。

带有返回类型的签名

getOptions()

• getOptions: () => PanzoomOptions

定义于 types.ts:235

返回当前选项对象的副本

getPan()

• getPan: () => { x: number ; y: number }

定义在 types.ts:231

获取当前的 x/y 平移量

getScale()

• getScale: () => number

定义在 types.ts:233

获取当前的缩放比例

pan()

• pan: (x: number | string, y: number | string, panOptions?: PanOptions](../modules/types.md#panoptions)) => [CurrentValues

定义在 types.ts:246

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

// Translates the element to 50px, 100px
panzoom.pan(50, 100)
// Pans the element right 10px and down 10px from its current position
panzoom.pan(10, 10, { relative: true })

reset()

• reset: (resetOptions?: PanzoomOptions](../modules/types.md#panzoomoptions)) => [CurrentValues

定义在 types.ts:259

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

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

setOptions()

• setOptions: (options?: PanzoomOptions) => void

定义在 types.ts:261

更改 Panzoom 实例的选项

setStyle()

• setStyle: (name: string, value: string) => void

定义在 types.ts:263

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

zoom()

• zoom: (scale: number, zoomOptions?: ZoomOptions](../modules/types.md#zoomoptions)) => [CurrentValues

定义在 types.ts:272

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

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

zoomIn()

• zoomIn: (zoomOptions?: ZoomOptions](../modules/types.md#zoomoptions)) => [CurrentValues

定义在 types.ts:283

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

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

zoomOut()

• zoomOut: (zoomOptions?: ZoomOptions](../modules/types.md#zoomoptions)) => [CurrentValues

定义在 types.ts:294

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

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

zoomToPoint()

• zoomToPoint: (scale: number, point: { clientX: number ; clientY: number }, zoomOptions?: ZoomOptions](../modules/types.md#zoomoptions)) => [CurrentValues

定义在 types.ts:305

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

panzoom.zoomToPoint(1.2, pointerEvent)

zoomWithWheel()

• zoomWithWheel: (event: WheelEvent, zoomOptions?: ZoomOptions](../modules/types.md#zoomoptions)) => [CurrentValues

定义在 types.ts:334

使用给定的 WheelEvent 将 Panzoom 元素缩放到焦点

这是一个便利函数，可能无法处理所有用例。其他情况应使用 zoomToPoint 方法或 zoom 方法的焦点选项来手动实现解决方案。

注意：焦点缩放平移调整不受 disablePan 选项的影响。

// Bind to mousewheel
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)
// Bind to shift+mousewheel
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.zoomWithWheel(event)
})

CurrentValues

isSVG

• 可选 isSVG: boolean

定义在 types.ts:211

scale

• scale: number

定义在 types.ts:210

x

• x: number

定义在 types.ts:208

y

• y: number

定义在 types.ts:209

事件

以下事件可以作为自定义事件在 panzoom 元素上使用原生的 CustomEvent API。添加监听器的方式与添加其他事件相同。

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

所有事件说明

• 传递给监听器的参数中的事件对象将始终包含一个具有以下属性的 detail 对象
  • 当前的 x 值
  • 当前的 y 值
  • 当前的 scale
  • 如果适用，一个具有触发 panzoom 事件的原始事件的 originalEvent 属性。例如，panzoomstart 事件的 originalEvent 属性将是一个 pointerdown、touchstart 或 mousedown 事件。
• 当 silent 选项设置为 true 时，可以静音事件，无论是全局设置还是传递给 pan、任何 zoom 方法或 reset。
• 避免在这些事件处理程序中放置太多逻辑，因为它可能会影响平移或缩放的性能。

"panzoomstart"

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

"panzoomchange"

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

"panzoomzoom"

每次通过任何 Panzoom zoom 方法（直接或内部）更改缩放时都会触发。

"panzoompan"

每次通过 pan 方法（直接或内部）更改平移时都会触发。

"panzoomend"

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

"panzoomreset"

每次调用重置时都会触发。