PhotoSwipe 是專為行動觸控裝置打造的相冊/畫廊,相容 iPhone、iPad、BlackBerry 6+ 以及各大桌面瀏覽器。底層純粹以 HTML/CSS/JavaScript 實作,是免費開源的方案。
為誰而做:想讓手機版網站的相冊體驗貼近原生 App 感受的設計師與開發者。它提供的是一套使用者熟悉、操作直覺的互動模型。
官網 photoswipe.com · GitHub codecomputerlove/PhotoSwipe
相容性方面,它同時提供三種版本:不依賴 jQuery 的獨立版、jQuery 版,以及 jQuery Mobile 版。針對 webkit 做了大量優化,桌面端也有相應處理。
<!-- klass 需先於 photoswipe 載入,可加 defer 提升載入速度 --> <script type="text/javascript" src="klass.min.js"></script> <!-- 重要:非 jQuery 版本在 IE 下會出錯;若用 jQuery 版則需先引入 jQuery --> <script type="text/javascript" src="code.photoswipe-3.0.5.min.js"></script>
原生版:
document.addEventListener('DOMContentLoaded', function () {
// 第二個參數是可選設定,第三個是多實例時的 ID
var myPhotoSwipe = Code.PhotoSwipe.attach(
window.document.querySelectorAll('#Gallery a'),
{ enableMouseWheel: false, enableKeyboard: false }
);
}, false);attach() 回傳的就是 PhotoSwipe 實例,後續可呼叫 show(0)、hide() 等方法。
jQuery 版(對應的 js 檔也要換):
$(document).ready(function () {
var myPhotoSwipe = $("#Gallery a").photoSwipe({
enableMouseWheel: false,
enableKeyboard: false
});
});<!-- ul li 用來排縮圖;<a> 內的 <img> 即縮圖,若不需要可將 src 留空 -->
<ul id="Gallery">
<li><a href="images/full/01.jpg"><img src="images/thumb/01.jpg" alt="Image 01" /></a></li>
<li><a href="images/full/02.jpg"><img src="images/thumb/02.jpg" alt="Image 02" /></a></li>
<li><a href="images/full/03.jpg"><img src="images/thumb/03.jpg" alt="Image 03" /></a></li>
<li><a href="images/full/04.jpg"><img src="images/thumb/04.jpg" alt="Image 04" /></a></li>
<li><a href="images/full/05.jpg"><img src="images/thumb/05.jpg" alt="Image 05" /></a></li>
<li><a href="images/full/06.jpg"><img src="images/thumb/06.jpg" alt="Image 06" /></a></li>
</ul>1. allowUserZoom:允許雙擊放大/拖曳檢視,預設 true。
2. autoStartSlideshow:啟動後自動播放,預設 false。
3. allowRotationOnUserZoom:僅 iOS,允許縮放模式下用手勢旋轉,預設 false。
4. backButtonHideEnabled:按返回鍵關閉,主要供 Android 與 Blackberry 使用,支援 BB6/Android 2.1/iOS 4 以上,預設 true。
5. captionAndToolbarAutoHideDelay:標題與工具列自動隱藏延遲,預設 5000ms;設 0 則不自動隱藏。
6. captionAndToolbarFlipPosition:標題與工具列位置對調,預設 false。
7. captionAndToolbarHide:隱藏兩者,預設 false。
8. captionAndToolbarOpacity:透明度 0–1,預設 0.8。
9. captionAndToolbarShowEmptyCaptions:標題為空仍顯示標題欄,預設 true。
10. cacheMode:normal 或 aggressive。激進模式會主動清空非「當前/前/後」的圖片,對舊版 iOS 的大圖記憶體溢出很有幫助;一般情境 normal 已足夠。
11. doubleTapSpeed:雙擊最大間隔,預設 300ms。
12. doubleTapZoomLevel:雙擊放大倍率,預設 2.5。
13. enableDrag:允許拖曳切換,預設 true。
14. enableKeyboard:鍵盤操作(左右鍵、Esc、Enter、空白鍵),預設 true。
15. enableMouseWheel:滑鼠滾輪操作,預設 true。
16. fadeInSpeed:淡入時間,預設 250ms。
17. fadeOutSpeed:淡出時間,預設 250ms。
18. imageScaleMethod:fit(預設,填滿螢幕)、fitNoUpscale(不放大)或 zoom(全螢幕,可能非等比例)。
19. invertMouseWheel:反轉滾輪方向,預設 false。
20. jQueryMobile:是否整合 jQuery Mobile,預設自動判斷。
21. jQueryMobileDialogHash:預設 "&ui-state=dialog"。
22. loop:循環播放,預設 true。
23. margin:圖間距 px,預設 20。
24. maxUserZoom:最大放大倍率,預設 5.0,設 0 忽略。
25. minUserZoom:最小縮小倍率,預設 0.5,設 0 忽略。
26. mouseWheelSpeed:滾輪靈敏度,預設 500ms。
27. nextPreviousSlideSpeed:上下張切換延遲,預設 0。
28. preventHide:禁止關閉並隱藏關閉鈕,預設 false。
29. preventSlideshow:禁止自動播放,預設 false。
30. slideshowDelay:自動播放間隔,預設 3000ms。
31. slideSpeed:圖片滑入時間,預設 250ms。
32. swipeThreshold:觸發 swipe 的最小像素,預設 50。
33. swipeTimeThreshold:觸發 swipe 的最大毫秒數,預設 250。
34. slideTimingFunction:滑動 easing,預設 "ease-out"。
35. zIndex:初始 z-index,預設 1000。
36. enableUIWebViewRepositionTimeout:檢查裝置方向變更,預設 false。
37. uiWebViewResetPositionDelay:上述檢查的間隔,預設 500ms。
38. preventDefaultTouchEvents:阻止預設 touch 事件(如頁面滾動),預設 true。
39. target:必須是合法 DOM 元素,預設 window(全螢幕);指定基層元素時只在該元素內顯示。
這幾個回呼讓你能改寫插件的預設行為:
getToolbar: function () {
/* 回傳要顯示在工具列中的 HTML 字串 */
},
getImageSource: function (el) {
/* 告訴 gallery 如何取得圖片 src。
預設假設 <a> 包著 <img>,且 <a> 的 href 就是原圖網址。
有 jQuery 時改寫起來更省事,也可以改讀 rel、data-src 等自訂屬性。 */
return el.getAttribute('rel');
},
getImageCaption: function (el) {
/* 同上,預設是讀 img 的 alt 屬性 */
},
getImageMetaData: function (el) {
/* 若監聽了 onDisplayImage,可用它取回額外資訊 */
return {
longDescription: el.getAttribute('data-long-description')
};
}在 Android 上,多層堆疊的元素若都綁了點擊事件,會出現「關閉上層後,下層也跟著被觸發」的問題。我們最後的解法是用計時器做短時間攔截:
// Android 多層觸發點擊時,用計時器攔截
var event_timeout = 500; // 防止短時間內連續觸發
var multiClickPrevent = false;
function preventMultiClick() {
if (multiClickPrevent) {
return false;
}
multiClickPrevent = true;
window.setTimeout(function () {
multiClickPrevent = false;
}, event_timeout);
return true;
}
// 適配瀏覽器的事件名稱
var useragent = navigator.userAgent;
var likeIOS = useragent.match(/iPad|iPhone|iPod/i);
var likeAndroid = useragent.match(/android/i);
var specialClick = "click";
if (likeIOS) {
specialClick = "touchstart click";
} else if (likeAndroid) {
specialClick = "touchstart click";
}
// 用法一:需要攔截
$(".t_right").live(specialClick, function () {
if (preventMultiClick()) {
// 執行操作
} else {
return false; // 拒絕這次觸發
}
});
// 用法二:不攔截,但仍綁定複合事件
$("body").live(specialClick, function () {
if (preventMultiClick()) {
// 執行操作
}
});這個問題的根源在於行動瀏覽器為相容舊網站而實作的 click 延遲,以及 touchstart 與 click 先後觸發的機制。用 500ms 的時間窗攔截是實用但不優雅的解法;如果專案允許,改用 pointer events 或統一以 touchstart 處理會更乾淨。另外 .live() 在 jQuery 1.9 之後已被移除,新專案請改用 .on() 搭配事件委派。
總結來說,PhotoSwipe 3.x 的強項是「設定即完成」——大量參數讓你能在不動原始碼的情況下微調行為,而幾個自訂回呼則提供了跳出去客製的出口。搭配上面的事件攔截技巧,多數行動端的相冊需求都能覆蓋。