插件 jQuery.panzoom 中文API文档
插件 jQuery.panzoom 中文API文档
源码 & 下载
- Github地址:https://github.com/timmywil/panzoom
- 源码下载: -
- 效果演示: -
插件特点
一个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模块的爱。
使用脚本标签:
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.1.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,
// 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.<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 {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.<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表示根据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 changeoptions.contain
{Boolean}: Override the global contain optionoptions.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。