阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 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。

      目录
      目录