Swiper formatter
モダンなモバイルファーストのスワイプ/スライドライブラリであるSwiper.jsを、DrupalのFieldフォーマッターおよびViewsスタイルプラグインとして統合します。
swiper_formatter
インストール
composer require 'drupal/swiper_formatter:^2.0'
composer require 'drupal/swiper_formatter:^1.0'
概要
Swiper formatterは、最もモダンで機能豊富なスワイプ/スライドライブラリの1つであるSwiper.jsとDrupalを統合するモジュールです。従来の画像スライダーとは異なり、このモジュールはほぼあらゆる種類のコンテンツを扱える包括的なスワイプUIウィジェットとして設計されています。
このモジュールは水平・垂直両方のスライド方向をサポートし、画像、テキスト/マークアップField、Mediaリファレンス、Entityリファレンス、Paragraphs、Viewsの結果など、さまざまなFieldタイプで動作します。設定Entityシステムにより、ナビゲーション、ページネーション、自動再生、遅延読み込み、グリッドレイアウト、ブレークポイント、その他多くのSwiper.js機能のカスタマイズオプションを持つ再利用可能な「Swiperテンプレート」を作成できます。
コンテンツは通常のSwiper形式で表示することも、ダイアログ/モーダル機能付きで表示することもできます。後者ではスライドをクリックするとモーダル、オフキャンバス、またはダイアログオーバーレイでコンテンツが開きます。
Features
- 豊富なカスタマイズオプションを持つ再利用可能なSwiperテンプレートを作成するための設定Entityシステム
- 複数のFieldフォーマッター：Swiper images、Swiper markup（テキスト）、Swiper entity（Entityリファレンス）、Swiper Paragraphs（Paragraphs）
- すべてのフォーマッターにダイアログバリアントがあり、モーダル、ダイアログ、オフキャンバスオーバーレイでコンテンツを開くことが可能
- Viewsの結果をSwiperスライダーとして表示するViewsスタイルプラグイン
- Swiper.jsモジュールのサポート：Navigation、Pagination、Scrollbar、Autoplay、Lazy Loading、Grid
- レスポンシブブレークポイントのサポートと、異なるビューポートサイズ向けに他のSwiperテンプレートを参照する機能
- 複数のライブラリソースオプション：バンドルパッケージ、リモートCDN、ローカルインストール
- 画像のalt/titleや他のテキストFieldなど、さまざまなFieldソースからのキャプションサポート
- スライドトランジションエフェクト：slide、fade、cube、coverflow、flip、cards
- 動的なダイアログタイトルとカスタムリンクのためのToken統合
- View、Entityタイプ、Field、View modeごとにテンプレートをカスタマイズできる豊富なtheme suggestionシステム
- レンダリング前にSwiper設定をプログラムで変更するためのhook
Use Cases
遅延読み込み付き画像ギャラリー
複数値の画像FieldにSwiper imagesフォーマッターを使用して、レスポンシブな画像ギャラリーを作成します。Swiperテンプレートで遅延読み込みを有効にしてページ読み込みパフォーマンスを向上させます。slidesPerViewを設定して複数のサムネイルを表示し、ナビゲーションとページネーションを有効にして簡単にブラウズできるようにします。
ホームページのコンテンツカルーセル
注目コンテンツNodeを表示するViews Blockを作成し、Swiper formatterスタイルプラグインを使用します。5000msの遅延で自動再生を設定し、注目アイテムを自動的に循環させます。各Viewsの結果行は、指定されたView modeでレンダリングされたコンテンツを表示するスライドになります。
商品画像のライトボックス
商品の画像FieldにSwiper images Dialogフォーマッターを使用します。より大きな画像スタイルを表示するモーダルとして開くようにダイアログを設定します。ユーザーはSwiperのサムネイルをクリックして、モーダルオーバーレイでフルサイズの画像を表示できます。
テキスト付きお客様の声スライダー
お客様の声用の複数値text_long Fieldを作成し、Swiper markupフォーマッターを適用します。自動再生を有効にして自動循環させ、fadeエフェクトを使用してお客様の声間のスムーズなトランジションを実現します。
レスポンシブブレークポイント設定
複数のSwiperテンプレートを作成します：1つのメインテンプレートと、異なるビューポートサイズ（例：480px、960px）用の別々のブレークポイントテンプレート。メインテンプレートがブレークポイントテンプレートを参照し、各画面サイズでslidesPerViewとナビゲーションの表示を調整するように設定します。モジュールはモバイルファーストアプローチに従い、ブレークポイント演算子は指定された幅以上（>=）です。
Paragraphsスライダー
リッチなフォーマットでスライドコンテンツを作成するためにコンテンツタイプにParagraphs Fieldを追加します。Swiper Paragraphsフォーマッターを適用して、各Paragraphsアイテムをスライドとして表示します。これにより、コンテンツ編集者はカスタムレイアウト、画像、テキスト、その他のParagraphsコンポーネントを含むスライドを作成できます。
モーダルプレビュー付きMediaギャラリー
MediaEntityを参照するEntityリファレンスFieldにSwiper entity Dialogフォーマッターを使用します。スライドにサムネイルView modeを表示し、ダイアログにフルView modeを表示するように設定します。ユーザーはサムネイルをブラウズし、クリックしてモーダルまたはオフキャンバスパネルで大きなプレビューを開くことができます。
Tips
- 異なるユースケース（例：'Heroスライダー'、'商品ギャラリー'、'お客様の声'）用に専用のSwiperテンプレートを作成し、サイト全体で一貫した設定を維持しましょう。
- 本番サイトでは'Package'ライブラリソースを使用して、Swiper.jsをモジュールにバンドルし、外部CDN依存を避けましょう。
- 垂直スライダーの場合は、Swiperテンプレートで固定の高さを設定し、autoHeightを有効にしてください。
- パフォーマンス向上のためにCSSモードを使用する場合、slide以外のトランジションエフェクトなど一部のSwiper機能はサポートされていないことに注意してください。
- hook_swiper_formatter_settings_alterを使用して、スライド数やその他の実行時条件に基づいて設定を動的に調整できます。
- テンプレートサジェスチョンにより、View、コンテンツタイプ、Field名、または特定のSwiperテンプレートごとにカスタムTwigテンプレートを作成でき、マークアップを細かく制御できます。
- observerオプションは、Swiperがページ読み込み後に表示される非表示コンテナ（タブ、アコーディオン）内にある場合に便利です。
- パフォーマンスが重要な本番サイトでは、ローカル縮小版ライブラリソースを使用し、画像が多いスライダーでは遅延読み込みを有効にすることを検討してください。
Technical Details
Admin Pages 3
/admin/config/content/swiper-formatter
既存のすべてのSwiperテンプレート（設定Entity）を一覧表示します。ここからテンプレートの表示、編集、削除、および新規作成ができます。デフォルトテンプレートは削除できません。
/admin/config/content/swiper_formatter/add
カスタマイズ可能なSwiper.jsパラメータとモジュールを持つ新しいSwiper設定テンプレートを作成します。
/admin/config/content/swiper-formatter/{swiper_formatter}
既存のSwiper設定テンプレートを編集します。
権限 1
Hooks 1
hook_swiper_formatter_settings_alter
レンダリング前にSwiper formatter設定を変更できます。slidesPerView、グリッド設定、その他のSwiperオプションを動的に変更するために使用できます。
Troubleshooting 6
Swiperテンプレートが有効になっている（無効になっていない）ことを確認してください。ライブラリソースにアクセスできることを確認してください - ローカルを使用している場合は、ファイルが/libraries/swiper/に配置されていることを確認してください。ブラウザコンソールでJavaScriptエラーを確認してください。少なくとも2つのスライドがあることを確認してください。単一アイテムのFieldではSwiperはスキップされます。
Swiperテンプレート設定でナビゲーションおよび/またはページネーションモジュールが有効になっていることを確認してください。Fieldフォーマッターで選択されたテンプレートが、これらの機能が有効なテンプレートと一致していることを確認してください。
Swiperテンプレートで遅延読み込みが有効になっていることを確認してください。Viewsの場合、画像Fieldに画像スタイルが設定されていることを確認してください。モジュールは遅延読み込みが有効な場合、preloadImages: falseとwatchSlidesProgress: trueを自動的に設定します。
適切なDrupal Ajaxライブラリが読み込まれていることを確認してください。モーダルにはcore/drupal.dialog.ajaxが必要で、オフキャンバスにはcore/drupal.dialog.off_canvasが必要です。モジュールはこれらを自動的にアタッチするはずです。ダイアログが読み込もうとしているEntityが存在し、アクセス可能であることを確認してください。
Swiperはモバイルファーストアプローチを使用していることを覚えておいてください - ブレークポイントは指定された幅以上（>=）で適用されます。ブレークポイントテンプレートが「Breakpoint template」としてマークされていることを確認し、通常のフォーマッター選択に表示されないようにしてください。ブレークポイント値は数値（ピクセル）または@で始まるパーセント値である必要があります。
Swiperフォーマッターは複数値Field（カーディナリティ > 1）にのみ適用されます。EntityリファレンスFieldの場合、Fieldストレージが複数の値を許可していることを確認してください。単一値FieldはSwiperフォーマッターを使用できません。