jQuery Panzoom是一款非常实用的HTML DOM元素平移和缩放jQueryCSS3插件。Panzoom利用CSS transforms 和 matrix函数来为浏览器进行硬件(GPU)加速,它可以支持任何元素的平移和缩放:图片、视频、iframe、canvas或文本等等。

IE8及以下的浏览器不支持这个插件。

Mobile support

Panzoom支持移动手机的触摸姿势,也支持使用手指来缩放元素大小。它完全可以同时在桌面设备和移动手机上同时使用。它可以支持iOS 和Android设备,同时支持Pointer(IE11+)、touchmouse事件。

SVG support

Panzoom可以在支持SVG的浏览器中直接对SVG元素进行平移和缩放。注意SVG元素上不会有动画效果,但是可以通过外部插件来手动覆盖setTransform()方法,并整合一个补间动画库(如tween.js)来实现。

使用方法

使用该元素平移和缩放插件需要引入jQuery和jquery.panzoom.js文件。

<script src="js/jquery.min.js"></script>
<script src="js/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] )

    Arguments:

    • options {Object|Boolean}:如果传入一个布尔值,动画被重置(默认值为true)。如果传入一个对象,会将它传入到setMatrix方法中。
    • options.silent {Boolean}:Silence the reset event (as well as the change event as the same options are passed to setMatrix)
    $elem.panzoom("reset");
    $elem.panzoom("reset", false);
    $elem.panzoom("reset", {
      animate: false,
      contain: false
    });
    

    重置 transform matrix 到它的原点值。所有的平移和缩放都被重置。

  • resetZoom( [options] )

    Arguments:

    • options {Object|Boolean}:如果传入一个布尔值,动画被重置(默认值为true)。如果传入的是一个对象,它将用于缩放。
      $elem.panzoom("resetZoom");
      $elem.panzoom("resetZoom", false);
      $elem.panzoom("resetZoom", {
        animate: false,
        silent: true
      });  
      

    重置scale到它的原始值。(resets both scale values in the matrix to their original values)

  • resetPan( [options] )

    Arguments:

    • options {Object|Boolean}:如果传入一个布尔值,动画被重置(默认值为true)。如果传入的是一个对象,它将用于平移。
      $elem.panzoom("resetPan");
      $elem.panzoom("resetPan", false);
      $elem.panzoom("resetPan", {
        animate: false,
        silent: true
      });
      

    重置平移值到原始值。

  • pan( x, y[, options] )

    Arguments:

    1. x {Number}: translation X的值。
    2. y {Number}: translation Y的值。
    3. options {Object}:These options are also passed along to setMatrix.
  • disable():快速禁用Panzoom元素。
    $elem.panzoom("disable");
    
  • enable():重新启用Panzoom元素。
    $elem.panzoom("enable");
    
  • isDisabled():当前的Panzoom实例不可用时返回一个布尔值。
    $elem.panzoom("isDisabled");
    // => true
    
  • isPanning():当前的元素是平移元素是返回一个布尔值。
  • destroy():销毁Panzoom实例。
    $elem.panzoom("destroy");
    
  • instance():从集合(set)中检索Panzoom实例。如果set中有多个元素,你会得到一个数组对象。如果只有一个元素,你会得到Panzoom实例。

更多的关于该插件的内容前参考:https://github.com/timmywil/jquery.panzoom