jQuery.pan: Un plugin para jQuery, gratuito y Open Source, para hacer zoom y pan de imágenes

27/12/2018
Artículo original

Imagen ornamentalHace unos días os hablaba de un plugin sencillo para jQuery que había creado que permite añadir un tooltip basado en CSS a las imágenes y otros objetos, que va siguiendo el puntero del ratón para facilitar dar información sobre éstos. Otro añadido que hice al blog al mismo tiempo fue un sistema para realizar zooms a las imágenes y que puedes comprobar en cualquiera de los artículos que tengan alguna imagen un poco más grande del espacio disponible. Esta funcionalidad se la otorga un plugin de jQuery llamado jQuery.pan.

Originalmente, la versión 1.0 de este plugin la creó el programador turco Samir Hazir, pero llevaba mucho tiempo abandonado. Como era de lo mejor que había encontrado por ahí para hacer esto, y hacía exactamente lo que yo quería pero todavía no se adaptaba del todo, yo lo he retomado y he creado la versión 2.0 del mismo.

Entre sus características están:

  •  Añade capacidades de zoom y de "pan" (o sea, moverse por una imagen grande para poder verla) a cualquier imagen de una página o a cualquier elemento que contenga una imagen.
  • Puede hacer zoom de cualquier imagen que sea más grande que su tamaño actual, o bien usando un atributo data-big para indicar cuál es la imagen grande que queremos mostrar al hacer el zoom.
  • El efecto de pan es automático, de modo que solo con mover el cursor se desplaza la imagen, tal y como se ve en la animación un poco más abajo.
  • Se puede aumentar o disminuir su tamaño usando un par de botones a tal efecto, o bien moviendo la rueda del ratón.
  • Tiene soporte para dispositivos móviles, de modo que puedes hacer "pan" arrastrando la imagen grande con un dedo.
  • Soporta IE8 o posterior y, por supuesto, todos los navegadores modernos.
  • Funciona con cualquier versión de jQuery, incluyendo versiones antiguas 1.x

Puedes verlo en funcionamiento en este mini-video:

Puedes probarlo pulsando en esta imagen:

Esta foto es bastante grande. Hecha por mi, por cierto :-)

Desde el repositorio de Github puedes ver su código fuente y también descargarte la versión "Release", lista para ser utilizada en producción, minimizada y optimizada. También puedes añadirla como una dependencia a tu proyecto usando npm, en concreto con:

npm i jquery.pan

lo cual lo añadirá a las dependencias de tu proyecto.

Para utilizarla debes incluir en tu página jQuery, obviamente el plugin, y también la CSS de apoyo que necesita, que es extremadamente pequeña (400 bytes gzippeada por el servidor, lo habitual). Esta carpeta CSS contiene también 4 pequeñas imágenes que se usan para la interfaz. En definitiva algo así:

<link rel="stylesheet" href="css/jquery.pan.css" />
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="jquery.pan.js"></script>

<script type="text/javascript">
    $(function(){
        $(".pan").pan();
    })
</script>

Fíjate en que, en este caso, lo que hace el fragmento final de script (que puede ir en cualquier sitio) es, tras haberse cargado la página, localiza todos los elementos marcados con la clase .pan y les aplica el plugin llamando al método pan(). Obviamente se podría aplicar a todas las imágenes usando $('img).pan(), o mediante cualquier selector jQuery que te interesase.

En el caso de imágenes, si no se indica lo contrario (ver más adelante), se usará la misma imagen mostrada para hacer el zoom. Es decir, si la imagen no tiene su tamaño real sino uno menor porque no cabe en el espacio disponible o porque se ha cambiado éste por el motivo que sea, el componente la mostrará a su tamaño real, haciendo zoom efectivamente.

Si le añades un atributo data-big, la ruta que indiques en este atributo es la que se usará para la imagen a mostrar. Por ejemplo, si tienes dos versiones de una misma imagen, una pequeña (un thumbnail o vista previa) y otra grande que es la que quieres que se vea con el zoom, solo tienes que poner algo así:

<img data-big="img/grande.jpg" src="img/pequeña.jpg" >

De este modo la etiqueta de imagen mostrará la foto pequeña, pero al pulsarla se mostrará la foto grande.

No solo funciona con imágenes directamente. Si tienes algún otro elemento que a su vez contenga una vista previa de alguna imagen o que te interese que lance el visor para mostrar una imagen puedes decorarlo con el atributo data-big y funcionará también. Por ejemplo, si quieres que al pulsar un determinado enlace o botón se muestre una imagen con el componente puedes hacer esto:

<a class="pan" data-big="img/grande.jpg" href="#">Pulsa para ver imagen grande</a>

Importante: si no se indica el atributo data-big  y se hace zoom sobre elementos de imagen, es decir, se usa su imagen indicada en el src para hacer el zoom, solo se aplicará el zoom a aquellas imágenes que sean más grandes de lo que se está viendo en la página. Es decir, si tenemos una imagen de tamaño 200x200 pixeles (o sea, pequeña) que cabe perfectamente en la página actual, aunque le intentemos aplicar el zoom con .pan() no funcionará. Esto es así por diseño ya que es absurdo hacer zoom de algo que no lo necesita.

Al aplicar el pan() a un conjunto de elementos de jQuery, se devuelve como resultado el conjunto exacto de elementos que a los que se le haya aplicado el plugin. Es decir, si por ejemplo una imagen es pequeña y no necesita zoom, no se devolverá en el conjunto de resultados. Esto nos sirve para hacer algo con ellas justo a continuación. Por ejemplo, cambiarles el título para añadirle una indicación sobre el zoom y que se vean con el componente YACSSTooltip que presenté el otro día, así:

$(function(){
    $(".main img").pan().each(function() {
        $(this).attr('title', 'PULSA PARA AUMENTAR');
    }).addTooltip();
})

Este fragmento busca todas las imágenes dentro de los elementos con la clase .main, les aplica el plugin de zoom&pan, y a las que finalmente sí se lo haya aplicado, les cambia el título para que ponga "PULSA PARA AUMENTAR". Finalmente usa el plugin YACSSTooltip del otro día para que se vea ese mensaje claramente al pasarles por encima.

¡Espero que te sea útil!