本文详细介绍PhotoSwipe.js插件的使用方法,涵盖文件引入、HTML结构搭建、JS初始化及高级配置。通过示例讲解如何设置图片路径、启用自动播放、自定义缩放与滑动交互,并深入解析插件属性与API接口调用,帮助开发者快速实现响应式图片相册功能。
PhotoSwipe.js插件简介与获取
访问PhotoSwipe.js官方网站http://photoswipe.com/,即可下载该组件及相关示例代码。
该组件主要用于图片及相册的展示功能,具有较高的实用价值。
环境搭建与文件引入
一、使用此组件需引入两个JavaScript文件: 1 <script type="text/javascript" src="simple-inheritance.min.js"> 2 <script type="text/javascript" src="code-photoswipe-1.0.11.min.js"> <!--当前最新版的应该是1.0.11 -->
HTML结构配置
二、页面HTML结构可参考如下形式:
<div id="Gallery">
<div class="gallery-row">
<div class="gallery-item"><a href="images/full/01.jpg"><img src="images/thumb/01.jpg" alt="Image 01" /></a></div>
<div class="gallery-item"><a href="images/full/02.jpg"><img src="images/thumb/02.jpg" alt="Image 02" /></a></div>
<div class="gallery-item"><a href="images/full/03.jpg"><img src="images/thumb/03.jpg" alt="Image 03" /></a></div>
</div>
<div class="gallery-row">
<div class="gallery-item"><a href="images/full/04.jpg"><img src="images/thumb/04.jpg" alt="Image 04" /></a></div>
<div class="gallery-item"><a href="images/full/05.jpg"><img src="images/thumb/05.jpg" alt="Image 05" /></a></div>
<div class="gallery-item"><a href="images/full/06.jpg"><img src="images/thumb/06.jpg" alt="Image 06" /></a></div>
</div>
</div>
在上述HTML代码中,除基础结构外,核心要素为id="Gallery"和<a href="图片路径"></a>(后续将详细说明)。其余class仅用于美化初始页面布局,实际交互效果由插件JS自动完成,无需额外编写效果布局代码。
准备好所需的JS文件和页面结构后,即可开始使用插件。
插件初始化方式
三、插件声明支持两种实现方式:
1、采用浏览器默认的addEventListener()方法:
document.addEventListener("DOMContentLoaded",function(){
Code.photoSwipe('a','#Gallery');
//此处就涉及到上述页面结构中的 id="Gallery"和<a href="..."></a>,其中id="Gallery"是容器
//<a href="图片路径"></a>,此处href中一定是当前所指向的图片的路径
},false);
2、使用jQuery方式:
$(document).ready(function(){
$("#Gallery a").photoSwipe();
});
交互效果与功能演示
四、按上述配置后,页面初始效果大致如下:

点击任意图片后,页面切换为如下视图(此即期望的最终效果):

可清晰看到页面上方<img />标签的alt属性内容,下方设有四个按钮,分别对应:关闭相册返回初始视图(参考上上图)、自动播放、上一张图片、下一张图片。
至此,相册效果已实现。支持鼠标左右滑动切换图片,在移动设备上亦可通过手指滑动操作。
高级属性配置详解
该插件提供丰富的配置属性:
allowUserZoom: 允许用户双击放大/移动方式查看图片. 默认值 = true autoStartSlideshow: 当PhotoSwipe激活后,自动播放幻灯片. 默认值 = false allowRotationOnUserZoom: 只有 iOS 支持 - 允许用户在缩放/平移模式下 用手势旋转图像. 默认值 = false backButtonHideEnabled: 按返回键隐藏相册幻灯片. 主要是 Android 和 Blackberry使用. 支持 BB6, Android v2.1, iOS 4 以及更新版本. 默认值 = true captionAndToolbarAutoHideDelay: 标题栏和工具栏自动隐藏的延迟时间. 默认值为 = 5000(毫秒). 如果设为 0 则不会自动隐藏(tap/单击切换显隐) captionAndToolbarFlipPosition: 标题栏和工具栏切换位置(让 caption显示在底部而 toolbar显示在顶部). 默认值 = false captionAndToolbarHide: 隐藏 标题栏和工具栏. 默认值 = false captionAndToolbarOpacity: 标题栏和工具栏 的透明度(0-1). 默认值 = 0.8 captionAndToolbarShowEmptyCaptions: 即使当前图片的标题是空,也显示标题栏. 默认值 = true cacheMode: 缓存模式,Code.PhotoSwipe.Cache.Mode.normal (默认,正常) 或者 Code.PhotoSwipe.Cache.Mode.aggressive(激进,积极). 决定 PhotoSwipe 如何管理图片缓存 cache. Aggressive 模式将会积极地地设置非 "当前,上一张,下一张"的图片为空的类型. 对于老版本iOS 浏览器下的大图片内存溢出将会很有用. 大多数情况下,normal模式就可以了。 doubleTapSpeed: 双击的最大间隔. 默认值 = 300(毫秒) doubleTapZoomLevel: 当用户双击的时候,放大的倍数, 默认的 "zoom-in"(拉近) 级别. 默认值 = 2.5 enableDrag: 允许拖动上一张/下一张图片到当前界面. 默认值 = true enableKeyboard: 允许键盘操作(左右箭头切换,Esc退出,Enter自动播放,空格键 显/隐标题栏/退出). 默认 = true enableMouseWheel: 允许鼠标滚轮操作. 默认 = true fadeInSpeed: 淡入效果元素的速度(持续时间),毫秒. 默认 = 250 fadeOutSpeed: 淡出效果元素的速度(持续时间),毫秒. 默认 = 250 imageScaleMethod: 图片缩放方法(模式). 可选值: "fit", "fitNoUpscale" 和 "zoom". 模式"fit" 保证图像适应屏幕. "fitNoUpscale" 和 "fit"类似但是不会放大图片. "zoom"将图片全屏, 但有可能图片缩放不是等比例的. 默认 = "fit" invertMouseWheel: 反转鼠标滚轮。默认情况下,鼠标向下滚动将切换到下一张,向上切换到上一张 . 默认 = false jQueryMobile: 指示 PhotoSwipe 是否集成进了 jQuery Mobile 项目. 默认情况下, PhotoSwipe will try and work this out for you jQueryMobileDialogHash: jQuery Mobile的window,dialog页面 所使用的hash标签。 默认值 = "&ui-state=dialog" loop: 相册是否自动循环. 默认 = true margin: 两张图之间的间隔,单位是像素. 默认 = 20 maxUserZoom: 最大放大倍数. 默认 = 5.0 (设置为0将被忽略) minUserZoom: 图像最小的缩小倍数. 默认 = 0.5 (设置为0将会忽略) mouseWheelSpeed: 响应鼠标滚轮的灵敏度. 默认 = 500(毫秒) nextPreviousSlideSpeed: 当点击上一张,下一张按钮后,延迟多少毫秒执行切换. 默认 = 0 (立即切换) preventHide: 阻止用户关闭 PhotoSwipe. 同时也会隐藏 工具栏上的"close"关闭按钮. 在独享页面使用 (示例是源码中的 examples/08-exclusive-mode.html). 默认 = false preventSlideshow: 阻止自动播放模式. 同时也会隐藏工具栏里的播放按钮. 默认 = false slideshowDelay: 自动播放模式下,多长时间播放下一张. Default = 3000(毫秒) slideSpeed: 图片滑进视图的时间. 默认 = 250(毫秒) swipeThreshold: 手指滑动多少像素才触发一个 swipe 手势事件. 默认 = 50 swipeTimeThreshold: 定义触发swipe(滑动)手势的最大毫秒数,太慢了则不会触发滑动,只会拖动当前照片的位置. 默认 = 250 slideTimingFunction: 滑动时的 Easing function . 默认 = "ease-out" zIndex: 初始的zIndex值. 默认 = 1000 enableUIWebViewRepositionTimeout: 检查设备的方向是否改变。默认 = false uiWebViewResetPositionDelay: 定时检查设备的方向是否改变的时间 默认 = 500(毫秒) preventDefaultTouchEvents: 阻止默认的touch事件,比如页面滚动。 默认 = true target: 必须是一个合法的DOM元素(如DIV)。默认是window(全页面)。而如果是某个低级别的DOM,则在DOM内显示,可能非全屏。
若需跳过首页直接展示第二张图片,可按如下方式配置:
$(document).ready(function(){
// Set up PhotoSwipe, setting "preventHide: true"
var thumbEls = Code.photoSwipe('a', '#Gallery', { preventHide: true });
Code.PhotoSwipe.Current.show(0);
});
API接口与监听器应用
此外,该插件还提供多种监听函数:
document.addEventListener('DOMContentLoaded',function(){
//onBeforeShow 在gallery将要展示之前调用该方法
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeShow,function(e){
console.log("onBeforeShow");
});
// onshow 在gallery展示的时候调用
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onShow,function(e){
console.log("onShow");
});
// onBeforeHide 在gallery隐藏之前
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeHide, function(e){
console.log('onBeforeHide');
});
// onHide 在Gallery隐藏的时候
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onHide, function(e){
console.log('onHide');
});
// onShowNext 在展示下一个的时候
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onShowNext, function(e){
console.log('onShowNext');
});
// onShowPrevious 在展示上一个的时候
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onShowPrevious, function(e){
console.log('onShowPrevious');
});
// onDisplayImage 在图片展示
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onDisplayImage, function(e){
console.log('onDisplayImage');
});
// onResetPosition 当Gallery的大小和位置发生变化时或者设备的方向或者窗口大小改变时,出发该方法
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onResetPosition, function(e){
console.log('onResetPosition');
});
// onSlideshowStart 当gallery开始滑动展示的时候(此方法可能是我理解有误,实验过程中一直没有触发过
的),原文是:When the gallery has started the slideshow
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onSlideshowStart, function(e){
console.log('onSlideshowStart');
});
// onSlideshowStop 当Gallery活动结束的时候
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onSlideshowStop, function(e){
console.log('onSlideshowStop');
});
// onBeforeCaptionAndToolbarShow 在顶部状态栏和底部的工具栏展示之前触发
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeCaptionAndToolbarShow, function(e){
console.log('onBeforeCaptionAndToolbarShow');
});
// onBeforeCaptionAndToolbarHide 在顶部状态栏和底部的工具栏隐藏之前触发
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeCaptionAndToolbarHide, function(e){
console.log('onBeforeCaptionAndToolbarHide');
});
// onViewportClick 在gallery中点击屏幕的时候触发,此时一般会触发onBeforeCaptionAndToolbarShow
或者onBeforeCaptionAndToolbarHide 方法
Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onViewportClick, function(e){
console.log('onViewportClick');
});
},false);
由于PhotoSwipe官网未明确提供API调用文档,且作者自述JS水平有限,故对部分API接口理解不深。但在查阅示例时发现变量Code.PhotoSwipe或Code.PhotoSwipe.Current频繁出现,因此在控制台进行实验。输入Code.PhotoSwipe后,显示如下内容:

虽无法完全解析内部结构,但可见Current元素。继续在控制台输入Code.PhotoSwipe.Current,得到如下结果:

从中可获取更多信息,例如currentIndex表示当前图片在列表中的索引位置。由此可知,Code.PhotoSwipe.Current.currentIndex代表当前图片索引,该信息对在不同页面展示不同内容至关重要。
以上为本文全部内容,希望能为读者学习提供帮助,欢迎继续支持本站。