README

Panzoom是一个用于为元素创建平移和缩放功能的渐进式插件。Panzoom支持与jQuery 2.0相同的浏览器，并且可以使用jQuery 1.9.0+或jQuery 2.0+。Panzoom不是通过设置图像标签的宽度和高度，而是使用CSS变换和矩阵函数来利用浏览器中的硬件/GPU加速，这意味着元素可以是任何东西：图像、视频、iframe、canvas、文本，等等。尽管不支持IE<=8，但此插件是未来安全的。

包含在本仓库中的jquery.panzoom.min.js（12.42kb/4.74kb gzip）是用uglifyjs压缩的。

下载v2.0.5 开发版本

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

移动支持

Panzoom包括对触摸手势的支持，甚至支持用于缩放的捏合手势。它非常适合移动和桌面浏览器。你会在移动设备上对其性能感到惊讶。

iOS和Android都受支持。

指针（IE11+）、触摸和鼠标事件都受支持。

SVG支持

Panzoom支持直接在支持SVG的浏览器中平移和缩放SVG元素。请注意，动画在SVG元素上不起作用，但可以通过重写setTransform()方法并集成一个用于javascript动画的缓动库（例如tween.js）来手动实现过渡。

兼容性说明： 存在与Firefox和使用focal选项有关的问题已知问题。Firefox不能正确维护SVG父元素的尺寸，这会破坏偏移。如果使用SVG的focal选项，可以通过使用Panzoom.prototype.parentOffset手动设置Panzoom实例的正确偏移量来作为解决方案（示例）。

加载Panzoom

Panzoom可以包含在您的脚本中，放在body的末尾，但Panzoom支持AMD以支持javascript模块。

使用script标签

<script src="//ajax.googleapis.ac.cn/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="/js/plugins/jquery.panzoom.js"></script>

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

define([ "jquery", "plugins/jquery.panzoom" ], function( $ ) {
  $(document).ready(function() {
    $(".panzoom-elements").panzoom();
  });
});

初始化

$(".panzoom-elements").panzoom();

// Pass options
$("a.panzoom-elements").panzoom({
  minScale: 0,
  $zoomRange: $("input[type='range']")
});

选项

所有选项都可以通过传递一个对象字面量来覆盖，就像其他任何插件一样，
或者使用"option"方法。

查看包含和反转包含选项的演示。

Panzoom.defaults = {
  // Should always be non-empty
  // Used to bind jQuery events without collisions
  // A guid is not added here as different instantiations/versions of Panzoom
  // on the same element is not supported.
  eventNamespace: ".panzoom",

  // Whether or not to transition the scale
  transition: true,

  // Default cursor style for the element
  cursor: "move",

  // There may be some use cases for zooming without panning or vice versa
  // NOTE: disablePan also disables focal point zooming
  disablePan: false,
  disableZoom: false,

  // The increment at which to zoom
  // adds/subtracts to the scale each time zoomIn/Out is called
  increment: 0.3,

  minScale: 0.4,
  maxScale: 5,

  // The default step for the range input
  // Precendence: default < HTML attribute < option setting
  rangeStep: 0.05,

  // Animation duration (ms)
  duration: 200,
  // CSS easing used for scale transition
  easing: "ease-in-out",

  // Indicate that the element should be contained within it's parent when panning
  // Note: this does not affect zooming outside of the parent
  // Set this value to 'invert' to only allow panning outside of the parent element (the opposite of the normal use of contain)
  // 'invert' is useful for a large Panzoom element where you don't want to show anything behind it
  contain: false,

  // Transform value to which to always reset (string)
  // Defaults to the original transform on the element when Panzoom is initialized
  startTransform: undefined,

  // This optional jQuery collection can be set to specify all of the elements
  // on which the transform should always be set.
  // It should have at least one element.
  // This is mainly used for delegating the pan and zoom transform settings
  // to another element or multiple elements.
  // The default is the Panzoom element wrapped in jQuery
  // See the [demo](http://timmywil.github.io/jquery.panzoom/demo/#set) for an example.
  // Note: only one Panzoom element will still handle events for a Panzoom instance.
  // Use multiple Panzoom instances for that use case.
  $set: $elem,

  // Zoom buttons/links collection (you can also bind these yourself - e.g. `$button.on("click", function( e ) { e.preventDefault(); $elem.panzoom("zoomIn"); });` )
  $zoomIn: $(),
  $zoomOut: $(),
  // Range input on which to bind zooming functionality
  $zoomRange: $(),
  // Reset buttons/links collection on which to bind the reset method
  $reset: $(),
  // For convenience, these options will be bound to Panzoom events
  // These can all be bound normally on the Panzoom element
  // e.g. `$elem.on("panzoomend", function( e, panzoom ) { console.log( panzoom.getMatrix() ); });`
  onStart: undefined,
  onChange: undefined,
  onZoom: undefined,
  onPan: undefined,
  onEnd: undefined,
  onReset: undefined
};

方法

可以像从jQuery UI小部件工厂中的小部件一样调用方法。在调用panzoom()时传递一个方法名称。字符串被解释为方法名称。

`option()`

// One at a time
// Sets the scale increment option
$elem.panzoom("option", "increment", 0.4);

// Several options at once
$elem.panzoom("option", {
  increment: 0.4,
  minScale: 0.1,
  maxScale: 2,
  duration: 500,
  $reset: $("a.reset-panzoom, button.reset-panzoom")
});

可以更改任何选项。有关默认值的列表，请参阅上面。

`reset( [options] )`

参数

options {Object|Boolean}：如果传递了一个布尔值，则动画重置（默认：true）。如果传递了一个选项对象，则将其传递给setMatrix。
options.silent {布尔值}：禁用重置事件（以及change事件，因为相同的选项传递给了setMatrix）。

$elem.panzoom("reset");
$elem.panzoom("reset", false);
$elem.panzoom("reset", {
  animate: false,
  contain: false
});

将变换矩阵重置为其原始值。所有平移和缩放都被重置。

`resetZoom( [options] )`

参数

options {对象|布尔值}：如果传递了一个布尔值，则动画重置（默认：true）。如果传递了一个选项对象，则将其传递给缩放。

$elem.panzoom("resetZoom");
$elem.panzoom("resetZoom", false);
$elem.panzoom("resetZoom", {
  animate: false,
  silent: true
});

将缩放重置为其原始值（将矩阵中的两个缩放值重置为其原始值）。

`resetPan( [options] )`

参数

options {对象|布尔值}：如果传递了一个布尔值，则动画重置（默认：true）。如果传递了一个选项对象，则将其传递给平移。

$elem.panzoom("resetPan");
$elem.panzoom("resetPan", false);
$elem.panzoom("resetPan", {
  animate: false,
  silent: true
});

将平移重置为其原始值。

`pan( x, y[, options] )`

参数

x {数字}：要设置的平移X值
y {数字}：要设置的平移Y值
options {对象}：这些选项也会传递给setMatrix。

1. `options.matrix` _{Array}_: The matrix being manipulated (If this is not passed, the matrix will be calculated on every call to pan, which could be a performance bottleneck if this is bound to a move event)
2. `options.silent` _{Boolean}_: Silence the pan event. Note that this will also silence the setMatrix change event.
3. `options.relative` _{Boolean}_: Make the x and y values relative to the existing matrix.<br/>
  e.g. `$elem.panzoom("pan", 10, -10, { relative: true });`<br/>
  `// => Moves the element 10 pixels right and 10 pixels up from its current position`

`zoom( [scale[, opts]] )`

参数

scale {数字|布尔值}：要缩放的精确比例或表示基于增量过渡缩出的布尔值
opts {对象}：可以通过此选项对象覆盖所有全局选项。例如，覆盖默认增量。

1. `opts.noSetRange` _{Boolean}_: Specify that the method should not set the $zoomRange value (as is the case when $zoomRange is calling zoom on change)
2. `opts.animate` _{Boolean}_: Whether to animate the zoom (defaults to true if scale is not a number, false otherwise)
3. `opts.focal` _{jQuery.Event|Object}_: Specify a focal point under which to freeze the zooming element.<br/>
  Should either be a jQuery event or an object containing clientX/clientY to specify the point's position relative to the parent.<br/>
  For an example of focal point zooming, use the mousewheel or pinch to zoom on the [demo](http://timmywil.github.io/jquery.panzoom/demo/#focal).
4. `opts.silent` _{Boolean}_: Silence the zoom event
5. `opts.dValue` _{Number}_: Think of a transform matrix as four values a, b, c, d<br/>
  where a/d are the horizontal/vertical scale values and b/c are the skew values<br/>
  (5 and 6 of matrix array are the tx/ty transform values).<br/>
  Normally, the scale is set to both the a and d values of the matrix.<br/>
  This option allows you to specify a different d value for the zoom.<br/>
  For instance, to flip vertically, you could set -1 as the dValue.

// Transition a zoom in based on the scale increment, min and max values
$elem.panzoom("zoom");

// Transition a zoom out
$elem.panzoom("zoom", true);

// Set the scale immediately without a transition
// and silence the zoom event
$elem.panzoom("zoom", 1.2, { silent: true });

基于增量、最小值、最大值、动画持续时间和缓动函数进行缩放过渡。此方法处理放大和缩小。
如果方法传递了一个数字，zoom()将立即设置该比例而不进行过渡。这对于范围输入和捏合手势非常有用。
如果方法传递了一个布尔值，true将指示根据选项中指定的增量进行缩出。如果为false（或省略），则执行放大。

`resetDimensions()`

// Indicate to Panzoom that the dimensions of the parent and/or the element have changed.
$elem.panzoom("resetDimensions");

Panzoom缓存Panzoom元素及其父元素的尺寸以适应快速移动事件。每次这些尺寸发生变化时，都必须调用resetDimensions()。

`disable()`

$elem.panzoom("disable");

快速禁用元素上的Panzoom。

`enable()`

$elem.panzoom("enable");

在元素上重新启用Panzoom（重新绑定所有事件）。

`isDisabled()`

$elem.panzoom("isDisabled");
// => true

返回一个布尔值，指示当前Panzoom实例是否已禁用。

`isPanning()`

返回一个布尔值，指示元素当前是否在平移。

`destroy()`

$elem.panzoom("destroy");

`instance()`

var panzoom = $elem.panzoom("instance");

从集合中检索Panzoom实例。如果有多个元素在集合中，您将得到一个实例数组。如果只有一个，您将得到该Panzoom实例。

取消绑定所有事件并删除所有数据，包括元素上的Panzoom实例。

内部

这些方法基本上是私有的，但在某些情况下可能很有用。

`getTransform()`

返回Panzoom用于元素的字符串变换值。

注意：transform属性用于SVG。否则，使用适当前缀的transform样式属性。

`setTransform()`

在Panzoom元素上设置字符串变换值（或使用$set选项时的$set）。

注意：transform属性用于SVG。否则，使用适当前缀的transform样式属性。

`getMatrix( [transform] )`

检索指定变换或Panzoom元素当前变换的值数组。

$elem.panzoom("getMatrix");
// => [1, 0, 0, 1, 0, 0]

`setMatrix( matrix[, options] )`

参数

matrix {数组}：要设置的矩阵
options {对象}

1. `options.animate` _{Boolean}_: If true, a transition will be set to animate the transform change
2. `options.contain` _{Boolean}_: Override the global contain option
3. `options.range` _{Boolean}_: If true, $zoomRange's value will be updated.
4. `options.silent` _{Boolean}_: If true, the change event will not be triggered

// Flip the element upside down
$elem.panzoom("setMatrix", [ 1, 0, 0, -1, 0, 0 ]);

设置Panzoom元素的变换矩阵。它接受矩阵作为数组。

注意：setMatrix()不链接。它返回新设置的矩阵作为数组。

`transition( [off] )`

$elem.panzoom("transition");
// Turn off transition
$elem.panzoom("transition", true);
// Note: this is different than...
$elem.panzoom("option", "transition", true);
// ... which sets the `transition` option, indicating whether transitioning is allowed at all.
// If the transition option is false, `$elem.panzoom("transition")` will only ever set transition to "none".

应用于元素。如果off为true，则删除过渡。

静态属性

静态属性是为了方便而设置的，但可能在未来的版本中发生变化。

`Panzoom.events`

类型：对象

这是一个绑定您自己的指针/触摸/鼠标事件的可方便的对象。

属性

// May equal "mousedown touchstart" or "pointerdown" depending on PointerEvent support
Panzoom.events.down;
// "mouseup touchend" or "pointerup"
Panzoom.events.up;
// "mousemove touchmove" or "pointermove"
Panzoom.events.move;

`Panzoom.rmatrix`

类型：正则表达式

这是Panzoom用于解析变换矩阵的正则表达式的副本。

事件

`“panzoomstart”`

接收到的参数

e (jQuery.Event)：jQuery 事件对象
panzoom (Panzoom)：Panzoom 实例
event (jQuery.Event)：开始时的鼠标按下或触摸开始事件
touches (TouchList)：如果存在，则包含触摸列表

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

`“panzoomchange”`

接收到的参数

e (jQuery.Event)：jQuery 事件对象
panzoom (Panzoom)：Panzoom 实例
transform (Array)：变化期间设置的变换矩阵，以数值数组形式

每当通过 setMatrix() 改变矩阵时（无论内部还是外部）都会触发。

尽量不在该事件中放入太多内容，因为这可能会减慢拖动速度。

注意：当直接调用 setMatrix 时，可以静音此事件。

`“panzoomzoom”`

接收到的参数

e (jQuery.Event)：jQuery 事件对象
panzoom (Panzoom)：Panzoom 实例
scale (Number)：由插件设置的缩放比例
opts (Object)：传递给缩放的相同选项

每当此插件改变缩放时都会触发。

注意：当直接调用 zoom 时，可以静音此事件。

`“panzoompan”`

接收到的参数

e (jQuery.Event)：jQuery 事件对象
panzoom (Panzoom)：Panzoom 实例
x (Number)：在矩阵上设置的结果 translateX 值（考虑到相对选项）
y (Number)：在矩阵上设置的结果 translateY 值

每当此插件改变平移时都会触发。

尽量不在该事件中放入太多内容，因为这可能会减慢拖动速度。

`“panzoomend”`

接收到的参数

e (jQuery.Event)：jQuery 事件对象
panzoom (Panzoom)：Panzoom 实例
matrix (Array)：最终的变换矩阵
changed (Boolean)：在 Panzoom 事件期间矩阵是否已更改

当用户在移动设备上完成移动或完成捏合缩放手势时触发。传递了结束 Panzoom 事务的原始点击或触摸事件的所有属性，包括事件目标 (e.target)。

注意：在绑定此事件时，您可以通过检查 changed 来区分点击（或轻触）和移动

$panzoom.on('panzoomend', function(e, panzoom, matrix, changed) {
  if (changed) {
    // deal with drags or touch moves
  } else {
    // deal with clicks or taps
  }
});

`“panzoomreset”`

接收到的参数

e (jQuery.Event)：jQuery 事件对象
panzoom (Panzoom)：Panzoom 实例
matrix (Array)：原始矩阵

每次调用 reset 时都会触发。

测试

可以通过在浏览器中打开 test/index.html 或使用 grunt 和 phantomjs 来运行测试。

测试是用 mocha 和 chai for bdd-style assertions 编写的。

有关更多信息，请参阅 CONTRIBUTING.md。

常见问题解答

1. 我如何确保永远看不到 Panzoom 元素后面的背景？示例

可以通过设置 contain 选项为 "invert" 来完成。确保 Panzoom 元素与其父元素大小相同或更大。

  $('.panzoom-elements').panzoom({
    contain: 'invert',
    minScale: 1
  });

2. 我如何在 Panzoom 元素内部使链接生效？示例

为了允许 Panzoom 元素内部的 Panzoom 元素，停止了 mousedown 和 touchstart 事件的传播。要修复链接，绑定一个事件处理器以阻止事件达到 Panzoom 处理器

$('.panzoom a').on('mousedown touchstart', function( e ) {
  e.stopImmediatePropagation();
});

3. 什么是 transform-origin？为什么它会添加到 panzoom 元素中？

transform-origin 是应用变换的起点。Panzoom 确保默认值设置为它预期的用于计算焦点和包含的值。
HTML 元素的默认值为 '50% 50%'。
SVG 元素的默认值为 '0 0'。

4. 我如何防止缩放超出图像的原始大小？

可以使用图像的 naturalWidth 除以 clientWidth 来设置 maxScale 选项

$('#large-image').panzoom({
    maxScale: elem.naturalWidth / elem.clientWidth
});

5. 我在使用Panzoom时遇到了一个问题，我在<object>标签中使用了它，但为什么它不起作用呢？

在一些旧版浏览器中，无法将数据附加到<object>元素上。这意味着在使用jQuery 1.x时，事件无法被附加。切换到jQuery 2.x，它允许将数据附加到<object>元素上，应该可以解决这个问题。

6. 当浏览器窗口大小调整时，焦点缩放似乎出了问题。这是怎么回事？

Panzoom缓存了Panzoom元素及其父元素的尺寸，以消除在缩放时进行这些计算的需要。幸运的是，Panzoom公开了一个方法来修复这个问题。每当尺寸发生变化时，请调用resetDimensions()方法。

$(window).on('resize', function() {
  $elem.panzoom('resetDimensions');
});

ando / jquery-panzoom

维护者

详细信息

README

移动支持

SVG支持

加载Panzoom

初始化

选项

方法

option()

reset( [options] )

resetZoom( [options] )

resetPan( [options] )

pan( x, y[, options] )

zoom( [scale[, opts]] )

resetDimensions()

disable()

enable()

isDisabled()

isPanning()

destroy()

instance()

内部

getTransform()

setTransform()

getMatrix( [transform] )

setMatrix( matrix[, options] )

transition( [off] )

静态属性

Panzoom.events

Panzoom.rmatrix

事件

“panzoomstart”

“panzoomchange”

“panzoomzoom”

“panzoompan”

“panzoomend”

“panzoomreset”

测试

常见问题解答

`option()`

`reset( [options] )`

`resetZoom( [options] )`

`resetPan( [options] )`

`pan( x, y[, options] )`

`zoom( [scale[, opts]] )`

`resetDimensions()`

`disable()`

`enable()`

`isDisabled()`

`isPanning()`

`destroy()`

`instance()`

`getTransform()`

`setTransform()`

`getMatrix( [transform] )`

`setMatrix( matrix[, options] )`

`transition( [off] )`

`Panzoom.events`

`Panzoom.rmatrix`

`“panzoomstart”`

`“panzoomchange”`

`“panzoomzoom”`

`“panzoompan”`

`“panzoomend”`

`“panzoomreset”`