PhotoSwipe - Responsive JavaScript Modal Image Gallery
PhotoSwipeライブラリを使用して、Drupalウェブサイトに洗練されたJavaScriptベースのフォトギャラリーを提供するモジュール。モバイルブラウザでのスワイプ操作に優れた対応を実現。
photoswipe
インストール
composer require 'drupal/photoswipe:^5.0'
概要
PhotoSwipeモジュールは、人気の高いJavaScriptライブラリ「PhotoSwipe」をDrupalに統合し、レスポンシブで美しい画像ギャラリー表示を実現します。特にモバイルデバイスでのユーザーエクスペリエンスに優れており、スワイプによる画像切り替え、ピンチズーム、タップによる操作など、直感的なタッチジェスチャーをサポートしています。
画像フィールドやメディアエンティティ参照フィールドに対してフォーマッターとして適用でき、サムネイル画像をクリックするとモーダルライトボックス形式で拡大画像を表示します。レスポンシブイメージにも対応しており、デバイスの画面サイズに応じて最適な画像を表示できます。
サブモジュールのPhotoSwipe Dynamic Captionを有効にすると、画像にキャプションを追加でき、画像のalt属性、title属性、エンティティラベル、またはカスタムトークンベースのキャプションを設定できます。
Features
- 画像フィールドとメディアエンティティ参照フィールド用のPhotoSwipeフォーマッター
- レスポンシブイメージスタイルに対応したPhotoSwipe Responsiveフォーマッター
- モバイルブラウザでのスワイプ、ピンチズーム、タップジェスチャーの完全サポート
- 豊富なアニメーション設定（ズーム、フェード、表示/非表示のアニメーション時間など）
- キーボード操作対応（ESCキーで閉じる、矢印キーでナビゲーション）
- ローカルライブラリまたはCDNからのライブラリ読み込みの選択
- Twigテンプレートからの直接利用が可能なattach_photoswipe()関数
- Viewsとの統合（photoswipe-galleryクラスを使用したギャラリーグループ化）
- サブモジュールによる動的キャプション機能（alt、title、エンティティラベル、カスタムトークン対応）
- アクセシビリティ対応（フォーカストラップ、フォーカス復元機能）
Use Cases
製品ギャラリーの作成
ECサイトの製品詳細ページで、製品画像をPhotoSwipeギャラリーとして表示します。製品コンテンツタイプの画像フィールドの「表示管理」でPhotoSwipeフォーマッターを選択し、サムネイルには小さい画像スタイル、モーダルには大きい画像スタイルを設定します。複数の画像がある場合、自動的にギャラリーとしてグループ化され、スワイプで画像を切り替えられます。
ポートフォリオサイトのライトボックス
写真家やデザイナーのポートフォリオサイトで、作品を美しく表示するためにPhotoSwipeを使用します。Photoswipe Responsiveフォーマッターを使用することで、モバイルデバイスには小さい画像、デスクトップには高解像度画像を自動的に配信し、パフォーマンスを最適化できます。
Viewsでの画像ギャラリー
特定のカテゴリの画像をViewsで一覧表示し、各画像をクリックするとPhotoSwipeで拡大表示します。Viewsの「View mode」を画像フィールドにPhotoSwipeフォーマッターが設定されている表示モードに設定するか、フィールドとして追加してフォーマッターを直接設定します。単一画像ではなくギャラリーとして動作させるには、フィールドまたは行のラッパーに 'photoswipe-gallery' クラスを追加してください。
カスタムTwigテンプレートでの使用
カスタムテーマやモジュールのTwigテンプレート内でPhotoSwipeを使用します。{{ attach_photoswipe() }}関数を呼び出してライブラリをアタッチし、画像を<a>タグでラップして'photoswipe'クラスを追加、さらに外側のコンテナに'photoswipe-gallery'クラスを追加します。オプション設定をオーバーライドする場合は{{ attach_photoswipe({'bgOpacity': 0.5}) }}のように引数を渡します。
メディアエンティティでの使用
メディアライブラリを使用している場合、メディアエンティティ参照フィールドにPhotoSwipeフォーマッターを適用できます。フォーマッター設定で「Image field of the referenced entity」を指定することで、メディアエンティティ内のどの画像フィールドを使用するか選択できます。Dynamic Captionサブモジュールを有効にすると、メディアエンティティ名をキャプションとして表示することも可能です。
画像キャプションの表示
PhotoSwipe Dynamic Captionサブモジュールを有効にして、画像に説明文を追加します。フィールドの表示設定で「Photoswipe image caption」オプションから、画像のalt属性、title属性、ノードタイトル、またはカスタムトークンベースのキャプションを選択できます。カスタムキャプションでは[node:title]や[file:description]などのトークンを組み合わせて柔軟なキャプションを作成できます。
Tips
- パフォーマンス最適化: 大量の画像を扱う場合は、プリロード数を減らし（Preload Before/After）、プリローダー遅延を調整してください。
- モバイル最適化: wheelToZoomを無効にしておくと、タッチデバイスでより自然な操作感になります。
- アクセシビリティ: Trap FocusとReturn Focus設定を有効にして、キーボードユーザーのアクセシビリティを向上させてください。
- グローバル読み込み: photoswipe_always_load_non_adminを有効にすると、任意の場所で.photoswipeクラスを追加するだけでPhotoSwipeが使用できます。カスタムテーマで柔軟に使用したい場合に便利です。
- 設定の翻訳: PhotoSwipeはConfig Translationに対応しています。ツールチップやエラーメッセージを多言語サイトで翻訳できます。
- キャプションのカスタマイズ: hook_photoswipe_js_options_alterを使用して、サイト全体でキャプションオプションやその他の設定をカスタマイズできます。
Technical Details
Admin Pages 1
/admin/config/media/photoswipe
PhotoSwipeライブラリのグローバル設定を行う管理画面。アニメーション、ユーザーインタラクション、ローカライゼーション、パフォーマンス設定を調整できます。
Hooks 1
hook_photoswipe_js_options_alter
PhotoSwipeのJavaScriptに渡されるオプション設定を変更するためのフック。モジュールとテーマの両方から使用可能。
Troubleshooting 5
1. ステータスレポート(/admin/reports/status)でPhotoSwipeライブラリのステータスを確認してください。2. ライブラリが正しいパス(libraries/photoswipe/dist/)に配置されているか確認してください。3. CDNオプションを使用している場合は、外部URLへのアクセスがブロックされていないか確認してください。
Viewsでは、PhotoSwipeフォーマッターはデフォルトで単一画像として動作します。ギャラリーとしてグループ化するには、画像を含むラッパー要素に'photoswipe-gallery'クラスを追加してください。フィールドの複数値をグループ化する場合はフィールドラッパーに、複数のフィールドをグループ化する場合はビューの行ラッパーにクラスを追加します。
Responsive Imageモジュール（コア）が有効になっているか確認してください。また、少なくとも1つのレスポンシブ画像スタイルが設定されている必要があります。
これはDrupalコアの既知の問題です（Drupal Issue #2686145）。Viewsでサードパーティフォーマッター設定が表示されないため、Drupalコアにパッチを適用する必要があります。
CDNからの読み込みはGDPRなどのデータ保護規制に準拠しない可能性があります。また、一部の環境ではCDNへのアクセスがブロックされている場合があります。可能であればローカルライブラリのインストールを推奨します。
Security Notes 2
- CDNオプションを使用する場合、外部サービス（cdnjs.cloudflare.com、unpkg.com）にユーザーのIPアドレスなどの情報が送信される可能性があります。GDPRなどのデータ保護規制が適用される地域では、ローカルライブラリのインストールを検討してください。
- Dynamic Captionサブモジュールでカスタムキャプションを使用する際、ユーザー入力を含むフィールドをキャプションソースとして使用する場合、XSS対策としてXss::filter()が適用されています。