DIV CSS 佈局教程網

PhotoSwipe.js 相冊插件完整用法:結構、屬性與事件
編輯:關於JavaScript     

PhotoSwipe 是一個專做圖片與相冊展示的元件,官網在 photoswipe.com,上面能取得檔案與官方範例。這個 1.0.x 版本以「簡單好用」取勝,幾行設定就能有一個像樣的相冊。

一、引入兩個檔案

<script type="text/javascript" src="simple-inheritance.min.js"></script>
<script type="text/javascript" src="code-photoswipe-1.0.11.min.js"></script>

二、頁面結構

<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="圖片路徑">。那些 class 只是用來排版縮圖牆,跟插件本身無關——插件會自己產生全螢幕的檢視層,你不需要寫任何彈出層的樣式。

三、兩種初始化寫法

原生方式,監聽 DOMContentLoaded:

document.addEventListener("DOMContentLoaded", function () {
    Code.photoSwipe('a', '#Gallery');
}, false);

兩個參數分別對應「要抓哪些 <a>」與「容器選擇器」。

jQuery 方式:

$(document).ready(function () {
    $("#Gallery a").photoSwipe();
});

四、實際效果

初始狀態是一整片縮圖牆:

點任一張之後進入全螢幕檢視:

上方顯示該圖 img 標籤 alt 裡的文字,下方四顆按鈕依序是:關閉回到縮圖牆、自動播放、上一張、下一張。桌面端可以用滑鼠左右拖曳切換,手持裝置則直接滑手指。

五、可調整的屬性

allowUserZoom:允許雙擊放大/拖曳檢視,預設 true。
autoStartSlideshow:啟動後自動播放,預設 false。
allowRotationOnUserZoom:僅 iOS,允許縮放時用手勢旋轉,預設 false。
backButtonHideEnabled:按返回鍵關閉相冊,主要用於 Android 與 Blackberry,預設 true。
captionAndToolbarAutoHideDelay:標題欄與工具列自動隱藏的延遲毫秒數,預設 5000;設為 0 則不自動隱藏。
captionAndToolbarFlipPosition:標題與工具列位置對調,預設 false。
captionAndToolbarHide:隱藏標題與工具列,預設 false。
captionAndToolbarOpacity:透明度 0–1,預設 0.8。
captionAndToolbarShowEmptyCaptions:標題為空時仍顯示標題欄,預設 true。
cacheMode:normal(預設)或 aggressive。激進模式會主動清空非「當前/上一張/下一張」的圖片,對舊版 iOS 載入大圖時的記憶體溢出很有幫助;一般情況用 normal 即可。
doubleTapSpeed:雙擊最大間隔,預設 300ms。
doubleTapZoomLevel:雙擊放大倍率,預設 2.5。
enableDrag:允許拖曳切換,預設 true。
enableKeyboard:鍵盤操作(左右鍵切換、Esc 退出、Enter 播放、空白鍵顯示或隱藏工具列),預設 true。
enableMouseWheel:滑鼠滾輪操作,預設 true。
fadeInSpeed / fadeOutSpeed:淡入淡出時間,預設各 250ms。
imageScaleMethod:fit(填滿螢幕,預設)、fitNoUpscale(同 fit 但不放大)或 zoom(全螢幕,可能非等比例)。
invertMouseWheel:反轉滾輪方向,預設 false。
jQueryMobile:是否整合 jQuery Mobile,預設自動偵測。
jQueryMobileDialogHash:對應的 hash 標籤,預設 "&ui-state=dialog"。
loop:是否循環播放,預設 true。
margin:兩圖間距(px),預設 20。
maxUserZoom / minUserZoom:最大放大 5.0、最小縮小 0.5,設為 0 則忽略。
mouseWheelSpeed:滾輪靈敏度,預設 500ms。
nextPreviousSlideSpeed:點擊上下張後的切換延遲,預設 0(立即)。
preventHide:禁止關閉,同時隱藏關閉按鈕,預設 false。
preventSlideshow:禁止自動播放,預設 false。
slideshowDelay:自動播放間隔,預設 3000ms。
slideSpeed:圖片滑入時間,預設 250ms。
swipeThreshold:觸發 swipe 的最小滑動像素,預設 50。
swipeTimeThreshold:觸發 swipe 的最大毫秒數,太慢則視為拖曳,預設 250。
slideTimingFunction:滑動 easing,預設 "ease-out"。
zIndex:初始 z-index,預設 1000。
enableUIWebViewRepositionTimeout / uiWebViewResetPositionDelay:定期檢查裝置方向是否改變,預設 false 與 500ms。
preventDefaultTouchEvents:阻止預設 touch 事件(例如頁面滾動),預設 true。
target:必須是合法 DOM 元素,預設 window(全螢幕);若指定某個基層元素,則只顯示於該元素內。

六、跳過縮圖牆直接開啟

$(document).ready(function () {
    var thumbEls = Code.photoSwipe('a', '#Gallery', { preventHide: true });
    Code.PhotoSwipe.Current.show(0);
});

七、可用的事件

官方文件對事件著墨不多,實際用法可以從這些名稱推知時機:

document.addEventListener('DOMContentLoaded', function () {

    // 相冊即將顯示前
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeShow, function (e) {
        console.log("onBeforeShow");
    });

    // 相冊顯示時
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onShow, function (e) {
        console.log("onShow");
    });

    // 隱藏前 / 隱藏後
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeHide, function (e) {
        console.log('onBeforeHide');
    });
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onHide, function (e) {
        console.log('onHide');
    });

    // 切換上一張 / 下一張
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onShowNext, function (e) {
        console.log('onShowNext');
    });
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onShowPrevious, function (e) {
        console.log('onShowPrevious');
    });

    // 圖片實際顯示(載入素材的關鍵時機)
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onDisplayImage, function (e) {
        console.log('onDisplayImage');
    });

    // 相冊尺寸或位置變化、裝置方向或視窗大小改變時
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onResetPosition, function (e) {
        console.log('onResetPosition');
    });

    // 自動播放開始 / 結束
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onSlideshowStart, function (e) {
        console.log('onSlideshowStart');
    });
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onSlideshowStop, function (e) {
        console.log('onSlideshowStop');
    });

    // 標題欄與工具列顯示 / 隱藏前
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeCaptionAndToolbarShow, function (e) {
        console.log('onBeforeCaptionAndToolbarShow');
    });
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onBeforeCaptionAndToolbarHide, function (e) {
        console.log('onBeforeCaptionAndToolbarHide');
    });

    // 點擊檢視區(通常緊接著觸發工具列顯示或隱藏)
    Code.PhotoSwipe.Current.addEventListener(Code.PhotoSwipe.EventTypes.onViewportClick, function (e) {
        console.log('onViewportClick');
    });

}, false);

其中 onSlideshowStart 我實驗時一直沒能觸發,原文描述是「相冊開始播放簡報時」,可能有版本差異,實測為準。

八、怎麼查未記載的 API

官網沒有完整的 API 文件,但所以有個取巧辦法:直接在主控台敲 Code.PhotoSwipe。

會看到裡面有一個 Current。再敲 Code.PhotoSwipe.Current:

資訊就更豐富了。例如 currentIndex 代表當前圖片在清單中的索引位置,串起來就是 Code.PhotoSwipe.Current.currentIndex。這個值很實用——你可以在 onDisplayImage 裡讀它,依目前第幾張顯示不同的資訊或廣告。

這也是個通用的學習技巧:文件不齊全時,主控台加上一點耐心,往往比翻文件更快找到答案。

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