插件 jQuery.panzoom 中文API文档

源码 & 下载

插件特点

一个jQuery插件，用于使用CSS3平移和缩放元素。

Panzoom是一个渐进式插件，可为元素创建平移和缩放功能。

Panzoom不是在图像标签上设置宽度和高度，而是使用CSS变换和矩阵函数来利用浏览器中的硬件/ GPU加速，

这意味着元素可以是任何东西：图像，视频，iframe，画布，文字，无论如何。

包含在此repo中的jquery.panzoom.min.js(12.5kb / 4.6kb gzip)使用uglifyjs进行压缩。

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

依赖

jquery.panzoom更喜欢jQuery 3.0.0+，但适用于jQuery 1.9.0+和jQuery 2.0.0+。jquery.panzoom支持IE9 +。

移动支持

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

支持iOS和Android。

支持指针(IE 10+)，触摸和鼠标事件。

SVG支持

Panzoom支持在支持SVG的浏览器中直接平移和缩放SVG元素。

在IE9-11和Edge 13-14 +中，CSS动画/过渡不适用于SVG元素，至少对于变换样式。它们可以在其他浏览器中使用。

可以通过覆盖setTransform()方法并为javascript动画(例如tween.js)集成补间库，在这些浏览器中手动实现转换。

兼容性说明： Firefox存在已知问题并使用该focal选项。Firefox无法正确维护SVG父元素的维度，这会抛弃偏移量。如果使用focalSVG选项，则解决方法是使用Panzoom.prototype.parentOffset(示例)手动在Panzoom实例上设置正确的偏移量。

加载Panzoom

Panzoom可以包含在身体末尾的脚本中，但是Panzoom支持AMD用于javascript模块的爱。

使用脚本标签：

使用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,

// Pan only on the X or Y axes

disableXAxis: false,

disableYAxis: false,

// Set whether you'd like to pan on left (1), middle (2), or right click (3)

which: 1,

// The increment at which to zoom

// Should be a number greater than 0

increment: 0.3,

// When no scale is passed, this option tells

// the `zoom` method to increment

// the scale *linearly* based on the increment option.

// This often ends up looking like very little happened at larger zoom levels.

// The default is to multiply/divide the scale based on the increment.

linearZoom: false,

// Pan only when the scale is greater than minScale

panOnlyWhenZoomed: false,

// min and max zoom scales

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 its 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("zoom"); });` )

$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 {Boolean}：使重置事件(以及更改事件静音，因为相同的选项传递给setMatrix)

$elem.panzoom("reset");

$elem.panzoom("reset", false);

$elem.panzoom("reset", {

animate: false,

contain: false

});

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

resetZoom( [options] )

参数

options {Object | Boolean}：如果传递了布尔值，则为重置设置动画(默认值：true)。如果传递了选项对象，则将其传递给zoom。

$elem.panzoom("resetZoom");

$elem.panzoom("resetZoom", false);

$elem.panzoom("resetZoom", {

animate: false,

silent: true

});

将比例重置为其原始值(将矩阵中的两个比例值重置为其原始值)。

resetPan( [options] )

参数

options {Object | Boolean}：如果传递了布尔值，则为重置设置动画(默认值：true)。如果传递了选项对象，则将其传递给pan。

$elem.panzoom("resetPan");

$elem.panzoom("resetPan", false);

$elem.panzoom("resetPan", {

animate: false,

silent: true

});

将平移重置为其原始值。

pan( x, y[, options] )

参数

x {Number}：要设置的翻译X值

y {Number}：要设置的翻译Y值

options {Object}：这些选项也传递给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.

e.g. `$elem.panzoom("pan", 10, -10, { relative: true });`

`// => Moves the element 10 pixels right and 10 pixels up from its current position`

zoom( [scale[, opts]] )

参数

scale {Number | Boolean}：缩放的精确比例或指示过渡缩小的布尔值

opts {Object}：此选项对象可以覆盖所有全局选项。例如，覆盖默认增量。

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.

Should either be a jQuery event or an object containing clientX/clientY to specify the point's position relative to the parent.

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

where a/d are the horizontal/vertical scale values and b/c are the skew values

(5 and 6 of matrix array are the tx/ty transform values).

Normally, the scale is set to both the a and d values of the matrix.

This option allows you to specify a different d value for the zoom.

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表示根据options中指定的增量执行缩小。如果为false(或省略)，则将执行放大。

resetDimensions()

// Indicate to Panzoom that the dimensions of the parent and/or the element have changed.

$elem.panzoom("resetDimensions");

Panzoom缓存Panzoom元素及其父级的尺寸，以满足快速移动事件的需要。每当这些尺寸发生变化时，都需要打电话resetDimensions()。但是，从3.1.0版开始，不再需要这样做。

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。否则，使用适当前缀的转换样式属性。

setTransform()

在Panzoom元素上设置字符串变换值(如果使用$ set选项，则设置$ set)。

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

getMatrix( [transform] )

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

$elem.panzoom("getMatrix");

// => [1, 0, 0, 1, 0, 0]

setMatrix( matrix[, options] )

参数

matrix {Array}：要设置的矩阵

options {宾语}

options.animate {Boolean}: If true, a transition will be set to animate the transform change

options.contain {Boolean}: Override the global contain option

options.range {Boolean}: If true, $zoomRange’s value will be updated.

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.rmatrix

输入：RegExp

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

活动

“panzoomstart”

收到的论据

e (jQuery.Event)：jQuery事件对象

panzoom (Panzoom)：Panzoom实例

event (jQuery.Event)：起始的mousedown或touchstart事件

touches (TouchList)：触摸列表(如果存在)

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

“panzoomchange”

收到的论据

e (jQuery.Event)：jQuery事件对象

panzoom (Panzoom)：Panzoom实例

transform (数组)：在更改期间将变换矩阵设置为值数组

无论何时通过setMatrix()(无论是内部还是外部)改变矩阵，都会触发。

尽量不要在这个事件中投入太多，因为它可能会减慢拖动速度。

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

“panzoomzoom”

收到的论据

e (jQuery.Event)：jQuery事件对象

panzoom (Panzoom)：Panzoom实例

scale (数字)：插件设置的缩放比例

opts (对象)：传递给zoom的相同选项

每当此插件更改缩放时触发。

注意：直接调用缩放时，可以使此事件静音。

“panzoompan”

收到的论据

e (jQuery.Event)：jQuery事件对象

panzoom (Panzoom)：Panzoom实例

x (数字)：在矩阵上设置的结果translateX值(考虑相对选项)

y (Number)：在矩阵上设置的结果translateY值

每次通过此插件更改平移时触发。

尽量不要在这个事件中投入太多，因为它可能会减慢拖动速度。

“panzoomend”

收到的论据

e (jQuery.Event)：jQuery事件对象

panzoom (Panzoom)：Panzoom实例

matrix (数组)：最终的变换矩阵

changed (布尔值)：在Panzoom事件期间矩阵是否更改

当用户完成移动或在移动设备上完成缩放缩放手势时会触发此事件。来自结束Panzoom事务的原始click或touch事件的所有属性都将被传递，包括事件

target(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 (数组)：原始矩阵

调用重置时触发。

测试

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

对于bdd样式的断言，测试用mocha和chai编写。

有关详细信息，请参阅CONTRIBUTING.md。

常问问题

我如何制作它以便我永远不会看到Panzoom元素背后的背景？例

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

$('.panzoom-elements').panzoom({

contain: 'invert',

minScale: 1

});如果链接在Panzoom元素中，如何使链接工作？例

停止事件传播mousedown和touchstart事件，以便允许Panzoom元素中的Panzoom元素。要修复链接，请绑定一个事件处理程序，以防止事件到达Panzoom处理程序：

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

e.stopImmediatePropagation();

});什么是transform-origin为什么以及为什么它被添加到panzoom元素中？

transform-origin是从被施加变换的原点。Panzoom确保将默认值设置为预期计算焦点和包含的值。

HTML元素默认为“50％50％”。

SVG元素默认为'0 0'。

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

该maxScale选项可以使用图像的设置naturalWidth被分为clientWidth：

$('#large-image').panzoom({

maxScale: elem.naturalWidth / elem.clientWidth

});我正在使用带标签的Panzoom 。它放大但不平移。例

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