PhotoSwipeの使い方(最小限の実装)

サムネイル画像をクリックすると拡大表示できるJSライブラリ「PhotoSwipe」の使い方をできるだけ簡潔にまとめてみようと思います。Light Box(ライトボックス)系のライブラリは沢山ありますが、自分はこれが一番好きかもしれません。

はじめに

PhotoSwipeの公式サイトには、3ステップで実装可能とあります。

  • JSファイルとCSSファイルを読み込む
  • 拡大表示用HTMLコードの挿入
  • PhotoSwipe初期化(実行)

しかし、3つ目の「PhotoSwipe初期化(実行)」の部分で4つの引数を渡す必要があり、初心者にはハードルが高い。

公式ではこの部分を簡単に実装するためのサンプルスクリプトが用意してあります。今回はそれを使って実装していきたいと思います。

JSファイルとCSSファイルのダウンロードと読み込み

まず、必要なファイルをダウンロードしてから、それらを読み込みます。

ダウンロード

GitHubから入手できます。「Code」というボタンからzip形式でダウンロードします。 ダウンロードしたzipを解凍し、「dist」フォルダの中身を自分の作業フォルダの中の任意の場所にコピーします。

読み込み

以下の4行をHTML内に挿入します。(リンク先は先程コピーした場所までの相対パスです)

<!-- CSS -->
<link rel="stylesheet" href="./photoswipe/photoswipe.css"> 
<link rel="stylesheet" href="./photoswipe/default-skin/default-skin.css"> 

<!-- JavaScript-->
<script src="./photoswipe/photoswipe.min.js"></script> 
<script src="./photoswipe/photoswipe-ui-default.min.js"></script>

拡大表示用HTMLコードの挿入

HTML内の</body>の直前辺りに以下のコードを挿入します。 (サムネイルをクリックした時の拡大表示用HTMLコードです)

公式のコードそのままなのでコピペでOKです。

<!-- Root element of PhotoSwipe. Must have class pswp. -->
<div class="pswp" tabindex="-1" role="dialog" aria-hidden="true">

    <!-- Background of PhotoSwipe. 
         It's a separate element as animating opacity is faster than rgba(). -->
    <div class="pswp__bg"></div>

    <!-- Slides wrapper with overflow:hidden. -->
    <div class="pswp__scroll-wrap">

        <!-- Container that holds slides. 
            PhotoSwipe keeps only 3 of them in the DOM to save memory.
            Don't modify these 3 pswp__item elements, data is added later on. -->
        <div class="pswp__container">
            <div class="pswp__item"></div>
            <div class="pswp__item"></div>
            <div class="pswp__item"></div>
        </div>

        <!-- Default (PhotoSwipeUI_Default) interface on top of sliding area. Can be changed. -->
        <div class="pswp__ui pswp__ui--hidden">

            <div class="pswp__top-bar">

                <!--  Controls are self-explanatory. Order can be changed. -->

                <div class="pswp__counter"></div>

                <button class="pswp__button pswp__button--close" title="Close (Esc)"></button>

                <button class="pswp__button pswp__button--share" title="Share"></button>

                <button class="pswp__button pswp__button--fs" title="Toggle fullscreen"></button>

                <button class="pswp__button pswp__button--zoom" title="Zoom in/out"></button>

                <!-- Preloader demo https://codepen.io/dimsemenov/pen/yyBWoR -->
                <!-- element will get class pswp__preloader--active when preloader is running -->
                <div class="pswp__preloader">
                    <div class="pswp__preloader__icn">
                      <div class="pswp__preloader__cut">
                        <div class="pswp__preloader__donut"></div>
                      </div>
                    </div>
                </div>
            </div>

            <div class="pswp__share-modal pswp__share-modal--hidden pswp__single-tap">
                <div class="pswp__share-tooltip"></div> 
            </div>

            <button class="pswp__button pswp__button--arrow--left" title="Previous (arrow left)">
            </button>

            <button class="pswp__button pswp__button--arrow--right" title="Next (arrow right)">
            </button>

            <div class="pswp__caption">
                <div class="pswp__caption__center"></div>
            </div>

        </div>

    </div>

</div>

PhotoSwipe初期化(実行)のためのスクリプトの作成と挿入

はじめに書いた3ステップ目です。

公式が用意しているサンプルスクリプトそのままです。全部コピペでOKです!

initphotoswipe.js
var initPhotoSwipeFromDOM = function(gallerySelector) {

    // parse slide data (url, title, size ...) from DOM elements 
    // (children of gallerySelector)
    var parseThumbnailElements = function(el) {
        var thumbElements = el.childNodes,
            numNodes = thumbElements.length,
            items = [],
            figureEl,
            linkEl,
            size,
            item;

        for(var i = 0; i < numNodes; i++) {

            figureEl = thumbElements[i]; // <figure> element

            // include only element nodes 
            if(figureEl.nodeType !== 1) {
                continue;
            }

            linkEl = figureEl.children[0]; // <a> element

            size = linkEl.getAttribute('data-size').split('x');

            // create slide object
            item = {
                src: linkEl.getAttribute('href'),
                w: parseInt(size[0], 10),
                h: parseInt(size[1], 10)
            };



            if(figureEl.children.length > 1) {
                // <figcaption> content
                item.title = figureEl.children[1].innerHTML; 
            }

            if(linkEl.children.length > 0) {
                // <img> thumbnail element, retrieving thumbnail url
                item.msrc = linkEl.children[0].getAttribute('src');
            } 

            item.el = figureEl; // save link to element for getThumbBoundsFn
            items.push(item);
        }

        return items;
    };

    // find nearest parent element
    var closest = function closest(el, fn) {
        return el && ( fn(el) ? el : closest(el.parentNode, fn) );
    };

    // triggers when user clicks on thumbnail
    var onThumbnailsClick = function(e) {
        e = e || window.event;
        e.preventDefault ? e.preventDefault() : e.returnValue = false;

        var eTarget = e.target || e.srcElement;

        // find root element of slide
        var clickedListItem = closest(eTarget, function(el) {
            return (el.tagName && el.tagName.toUpperCase() === 'FIGURE');
        });

        if(!clickedListItem) {
            return;
        }

        // find index of clicked item by looping through all child nodes
        // alternatively, you may define index via data- attribute
        var clickedGallery = clickedListItem.parentNode,
            childNodes = clickedListItem.parentNode.childNodes,
            numChildNodes = childNodes.length,
            nodeIndex = 0,
            index;

        for (var i = 0; i < numChildNodes; i++) {
            if(childNodes[i].nodeType !== 1) { 
                continue; 
            }

            if(childNodes[i] === clickedListItem) {
                index = nodeIndex;
                break;
            }
            nodeIndex++;
        }



        if(index >= 0) {
            // open PhotoSwipe if valid index found
            openPhotoSwipe( index, clickedGallery );
        }
        return false;
    };

    // parse picture index and gallery index from URL (#&pid=1&gid=2)
    var photoswipeParseHash = function() {
        var hash = window.location.hash.substring(1),
        params = {};

        if(hash.length < 5) {
            return params;
        }

        var vars = hash.split('&');
        for (var i = 0; i < vars.length; i++) {
            if(!vars[i]) {
                continue;
            }
            var pair = vars[i].split('=');  
            if(pair.length < 2) {
                continue;
            }           
            params[pair[0]] = pair[1];
        }

        if(params.gid) {
            params.gid = parseInt(params.gid, 10);
        }

        return params;
    };

    var openPhotoSwipe = function(index, galleryElement, disableAnimation, fromURL) {
        var pswpElement = document.querySelectorAll('.pswp')[0],
            gallery,
            options,
            items;

        items = parseThumbnailElements(galleryElement);

        // define options (if needed)
        options = {

            // define gallery index (for URL)
            galleryUID: galleryElement.getAttribute('data-pswp-uid'),

            getThumbBoundsFn: function(index) {
                // See Options -> getThumbBoundsFn section of documentation for more info
                var thumbnail = items[index].el.getElementsByTagName('img')[0], // find thumbnail
                    pageYScroll = window.pageYOffset || document.documentElement.scrollTop,
                    rect = thumbnail.getBoundingClientRect(); 

                return {x:rect.left, y:rect.top + pageYScroll, w:rect.width};
            }

        };

        // PhotoSwipe opened from URL
        if(fromURL) {
            if(options.galleryPIDs) {
                // parse real index when custom PIDs are used 
                // http://photoswipe.com/documentation/faq.html#custom-pid-in-url
                for(var j = 0; j < items.length; j++) {
                    if(items[j].pid == index) {
                        options.index = j;
                        break;
                    }
                }
            } else {
                // in URL indexes start from 1
                options.index = parseInt(index, 10) - 1;
            }
        } else {
            options.index = parseInt(index, 10);
        }

        // exit if index not found
        if( isNaN(options.index) ) {
            return;
        }

        if(disableAnimation) {
            options.showAnimationDuration = 0;
        }

        // Pass data to PhotoSwipe and initialize it
        gallery = new PhotoSwipe( pswpElement, PhotoSwipeUI_Default, items, options);
        gallery.init();
    };

    // loop through all gallery elements and bind events
    var galleryElements = document.querySelectorAll( gallerySelector );

    for(var i = 0, l = galleryElements.length; i < l; i++) {
        galleryElements[i].setAttribute('data-pswp-uid', i+1);
        galleryElements[i].onclick = onThumbnailsClick;
    }

    // Parse URL and open gallery if it contains #&pid=3&gid=1
    var hashData = photoswipeParseHash();
    if(hashData.pid && hashData.gid) {
        openPhotoSwipe( hashData.pid ,  galleryElements[ hashData.gid - 1 ], true, true );
    }
};

// execute above function
initPhotoSwipeFromDOM('.my-gallery');

以上のコードを任意のファイル名で保存して、好きな場所に置いて読み込みます。

例えば、「initphotoswipe.js」というファイル名にして以下のように読み込みます。 先程ダウンロードしたファイルの読み込みよりも後に読み込んでください。

<script src="./photoswipe/initphotoswipe.js"></script>

アイテムリストの書き方

上のスクリプトが正確に実行されるためには、以下のルールに従ってアイテムリストを書く必要があります。

ルール

  • 「my-gallery」というClass名のDIVタグで全体を囲います。
  • アイテムリストはそれぞれ「figure」タグで囲います。
  • 「a」タグの「data-size」属性に拡大画像の実サイズを入れます。これがないと適切に拡大表示できません。
  • キャプションが必要なければ、「figcaption」タグは省略できます。
  • それぞれのタグの構成を変えるとうまく動きません。間に別の要素などは入れない。

見本

<div class="my-gallery">
    <figure>
        <a href="large-image.jpg" data-size="600x400">
            <img src="small-image.jpg" alt="Image description" />
        </a>
        <figcaption itemprop="caption description">Image caption</figcaption>
    </figure>
    <figure>
        <a href="large-image.jpg" data-size="600x400">
            <img src="small-image.jpg" alt="Image description" />
        </a>
        <figcaption itemprop="caption description">Image caption</figcaption>
    </figure>
</div>

オプション

PhotoSwipeにはさまざまなオプションが用意されています。

オプション一覧(公式)
https://photoswipe.com/documentation/options.html

オプションを反映させるためには、先程作成したスクリプト内の以下の部分に以下のように追記します。

initphotoswipe.js
// 184行目あたり
// Pass data to PhotoSwipe and initialize it
gallery = new PhotoSwipe( pswpElement, PhotoSwipeUI_Default, items, options);
gallery.init();

// ここに挿入
gallery.options.bgOpacity = '0.7';

上の見本では、拡大表示時の背景の透明度を指定しています。

gallery.options.[オプション名] = [オプションの値];

という形式で複数指定できます。

まとめ

以上で実装できたと思います。3ステップ目のPhotoSwipeの初期化の部分で、サンプルスクリプトを使わなくても4つの引数を渡す事ができる方は、アイテムリストをルール通りに書く必要はなく、実装もとてもシンプルにできるでしょう。