DIV CSS 佈局教程網

手機端圖片縮放旋轉全螢幕:PhotoSwipe.js 完整參數與事件對策
編輯:關於JavaScript     

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
    });
});

三、HTML 結構

<!-- 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 上,多層堆疊的元素若都綁了點擊事件,會出現「關閉上層後,下層也跟著被觸發」的問題。我們最後的解法是用計時器做短時間攔截:

// 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 的強項是「設定即完成」——大量參數讓你能在不動原始碼的情況下微調行為,而幾個自訂回呼則提供了跳出去客製的出口。搭配上面的事件攔截技巧,多數行動端的相冊需求都能覆蓋。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved