插件 jQuery.panzoom 中文API文档

🌙
手机阅读
本文目录结构

插件 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模块的爱。

使用脚本标签:

<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 {宾语}
  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.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。

常问问题

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

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

$('.panzoom-elements').panzoom({
    contain: 'invert',
    minScale: 1
  });
  1. 如果链接在Panzoom元素中,如何使链接工作?例

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

$('.panzoom a').on('mousedown touchstart', function( e ) {
  e.stopImmediatePropagation();
});
  1. 什么是transform-origin为什么以及为什么它被添加到panzoom元素中?
  • transform-origin是从被施加变换的原点。Panzoom确保将默认值设置为预期计算焦点和包含的值。
  • HTML元素默认为“50%50%”。
  • SVG元素默认为'0 0’。
  1. 如何防止缩放超出图像的原始大小?

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

$('#large-image').panzoom({
    maxScale: elem.naturalWidth / elem.clientWidth
});
  1. 我正在使用带标签的Panzoom 。它放大但不平移。例

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

    AXIHE / 精选资源

    浏览全部教程

    面试题

    学习网站

    前端培训
    自己甄别

    前端书籍

    关于朱安邦

    我叫 朱安邦,阿西河的站长,在杭州。

    以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

    业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

    关注我: Github / 知乎

    于2021年离开前端领域,目前重心放在研究区块链上面了

    我叫朱安邦,阿西河的站长

    目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

    2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

    于2021年离开前端领域,目前从事区块链方面工作了