Masonry Gallery（可変グリッドギャラリー）

Masonry Gallery は縦横比の異なる画像を表示するコントロールです。各画像は比率を保ったまま最も短い列へ配置され、ページを下へスクロールすると次のデータページを自動で追加します。コントロール内に別のスクロールバーは作りません。

ポートフォリオ、写真、インスピレーションボード、メディア素材に適しています。業務レコードの状態、メタデータ、操作を表示する CardSet とは別の用途です。

コントロール	主な用途	データとレイアウト
Masonry Gallery	異なる縦横比を保った画像中心の連続閲覧	ページングされた画像レコード + ページ全体の無限スクロール
CardSet	状態、メタデータ、操作を含む業務レコードの要約	共通カードテンプレート + Pagination または Load More
Grid	ページ領域とコントロールの手動配置	固定 24 列レイアウト。レコードは繰り返しません

1. コントロールの追加

Page Designer の Containers を開きます。
Masonry Gallery をページへドラッグします。
Data Source を設定してからフィールドを対応付けます。
portfolioGallery などの安定した名前を付けます。

デザインキャンバスには異なる比率のサンプルが表示されます。Preview は実データを読み込みますが、編集時の連続読み込みを避けるため最大 2 ページです。

2. データソース

Model Data Source、Custom API、Media Library、Object Storage を利用できます。Model と Custom API は業務レコードを返し、後者 2 つはサーバー側の Media Connector を経由します。

2.1 Custom API のサンプル

POST /spark/api/sample/masonry-gallery/images

設定	値
URL	`/spark/api/sample/masonry-gallery/images`
Request Method	`POST`
Rows Path	`data.records`
Total Path	`data.total`
Current Page Path	`data.current`
Page Size Path	`data.pageSize`

Test & Import で 1 ページを取得し、次の Response Fields を取り込みます。

Field Path	Data Type	用途
`id`	TEXT	一意キー
`imageUrl`	URL	画像 URL
`title`	TEXT	タイトル
`caption`	TEXT	補足説明
`badge`	TEXT	カテゴリラベル
`alt`	TEXT	代替テキスト
`width`	NUMBER	元画像の幅
`height`	NUMBER	元画像の高さ

リクエスト本文にはページング情報が含まれます。

{"current": 1, "pageSize": 6}

{
  "success": true,
  "data": {
    "current": 1,
    "pageSize": 6,
    "total": 24,
    "records": [{
      "id": "gallery-1",
      "imageUrl": "/spark/api/sample/masonry-gallery/assets/coastal-architecture.jpg",
      "title": "Coastal Geometry",
      "caption": "Sunlit concrete forms above a quiet blue sea.",
      "badge": "Architecture",
      "alt": "White coastal architecture above the sea",
      "width": 1200,
      "height": 1200
    }]
  }
}

total が最も確実な終了条件です。ない場合は、返却件数が Items Per Request より少ないページで終了します。Row Unique Key は全ページで一意にしてください。重複キーは除外されます。

2.1 Media Library と Object Storage

最初に App Settings → Integrations → Media Connections で再利用可能な接続を作成します。

Console の Secret Management で資格情報を作成します。OSS/S3/MinIO は OBJECT_STORAGE、メディアプラットフォームは MEDIA_PROVIDER を使用します。
Media Connections で Provider と既存 Secret を選択します。フォームにはその Provider に必要な項目だけが表示され、自動利用する公式 API Endpoint は表示されません。
Masonry Gallery の Data Source では Media Library または Object Storage を選び、Connection だけを参照します。続いて Collection/Container、Path、Filter、Page Size を設定します。
Test を実行します。Test、デザインプレビュー、実行時は同じ Media Gateway とレスポンス解析を使用します。

現在利用できる本番 Provider：

Provider	Secret Management	Media Connection 設定
Cloudinary	`MEDIA_PROVIDER`。API Key に API Key、API Secret に API Secret を入力	Cloud Name は必須、Root Folder は任意
ImageKit	`MEDIA_PROVIDER`。API Key に Public API Key、API Secret に Private API Key を入力	Root Folder は任意。公式 API Endpoint は自動使用
Aliyun OSS / AWS S3 / MinIO	`OBJECT_STORAGE`。Access Key と Access Secret を入力	ストレージに応じて Endpoint、既定 Bucket、Root Prefix を設定

Spark Sample Media Library は外部アカウント不要の開発用です。Cloudinary と ImageKit は本番用 Media Library Connector です。Bynder、AEM Assets、完全な Spark Media Library はまだ利用できません。

ページ JSON に secretId、アクセスキー、一時署名 URL は保存されません。バックエンドは結果を records、nextCursor、hasMore、任意の total に正規化します。カードは thumbnailUrl、全画面表示は imageUrl を使用します。

{
  "records": [{
    "id": "asset-001",
    "imageUrl": "https://cdn.example/full.webp",
    "thumbnailUrl": "https://cdn.example/card.webp",
    "title": "Summer campaign",
    "alt": "Summer campaign launch",
    "width": 1600,
    "height": 1067
  }],
  "nextCursor": "opaque-next-cursor",
  "hasMore": true,
  "total": null
}

実行可能な例は spark-sample の SampleMasonryMediaConnector.java、masonry-gallery-media-connection.json、masonry-gallery-media-page.json にあります。

3. フィールド対応

プロパティ	推奨フィールド	必須
Row Unique Key	`id`	はい
Image URL Field	`imageUrl`	はい
Title Field	`title`	いいえ
Caption Field	`caption`	いいえ
Badge Field	`badge`	いいえ
Alternative Text Field	`alt`	推奨
Image Width Field	`width`	推奨
Image Height Field	`height`	推奨

Advanced の Width と Height を両方設定すると、画像取得前に正しい領域を確保でき、レイアウト移動を抑えられます。Alternative Text はファイル名ではなく画像内容を説明してください。未設定時は Title にフォールバックします。

4. レスポンシブレイアウト

プロパティ	推奨値	説明
Desktop Columns	`4`	ワイド画面の列数
Tablet Columns	`3`	中間幅の列数
Mobile Columns	`2`。テキストが多い場合は `1`	モバイルの列数
Spacing	`DEFAULT`	`COMPACT`、`DEFAULT`、`RELAXED`
Items Per Request	`6` または `12`	1 回の読み込み件数

列数はページ幅に追従し、画像を同じ高さへ切り抜きません。

5. スクロール読み込み

現在の末尾まで約 1.5 画面の位置で次ページを読み込みます。同時リクエストは 1 件だけです。読み込み中、Retry 可能なエラー、完了状態を表示します。短時間でページへ戻ると、読み込み済みレコードとスクロール位置を復元します。

固定高で内部スクロールを持つ狭いコンテナには配置しないでください。

6. 全画面プレビューとインタラクション

Enable Fullscreen Preview を有効にすると、クリックでビューアーが開きます。左右ボタン、方向キー、Escape、Tab、Enter、Space を利用できます。

onClick の前に選択レコードが Current Record へ設定されます。

record.id
record.imageUrl
record.title
record.badge

クリックはプレビューと onClick の両方を実行できます。直ちにページ遷移する場合は Fullscreen Preview を無効にしてください。

関数	動作
`reloadGallery`	状態を消去して 1 ページ目から再読込
`setGalleryData`	レコードを直接置換し、自動ページングを終了

7. リクエストコンテキスト

Data Source テスト、デザインプレビュー、実行時は同じ処理を使い、Spark が次の Header を自動付与します。

Header	値
`X-Spark-Page-Environment`	`DEV`、`TEST`、`PROD`
`X-Spark-Page-Render-Mode`	`DESIGN_PREVIEW`、`RUNTIME`

Data Source に手動追加する必要はありません。バックエンドは SparkPageRequestHeaders.resolve で解析し、DESIGN_PREVIEW では短いデータセットを返せます。

@PostMapping
public ApiResult<ProTablePageResult<MasonryGalleryImageDTO>> queryByPost(
        @RequestBody(required = false) MasonryGalleryQueryRequest request,
        @RequestHeader(value = SparkPageRequestHeaders.ENVIRONMENT, required = false) String environment,
        @RequestHeader(value = SparkPageRequestHeaders.RENDER_MODE, required = false) String renderMode) {
    return SparkApiResultHelper.success(
            Locale.ENGLISH,
            galleryService.query(request,
                    SparkPageRequestHeaders.resolve(environment, renderMode)),
            "SPARK-SAMPLE-MASONRY-GALLERY-0001");
}

Service はレンダリングモードに応じてデータ量を切り替えます。

int total = requestContext != null
        && requestContext.getRenderMode() == SparkPageRenderMode.DESIGN_PREVIEW
        ? 12
        : 24;

Java サンプル、ページ JSON、画像は spark-sample にあります。詳細はページリクエストコンテキストを参照してください。

8. 性能とデータの推奨事項

表示サイズに合う圧縮画像をキャッシュして配信します。
安定した id、width、height、有用な alt を返します。
1 回 6～20 件とし、バックエンドの並び順を安定させます。
画像の取得失敗とデータ API の失敗は分けて確認します。1 枚の画像が失敗してもページングは停止しません。

9. よくある問題

同じ画像が繰り返される： バックエンドが current と pageSize を適用しているか、応答パスが正しいかを確認します。
スクロールしても読み込まれない： total、短いページ、Retry 待ちの失敗リクエストを確認します。
レイアウトが大きく動く： width と height を返してマッピングします。
画像がプレースホルダーになる： Image URL Field、認証、CORS を確認します。
業務操作や詳細なメタデータが必要： CardSet を使用します。Masonry Gallery は Card Actions を提供しません。

1. コントロールの追加​

2. データソース​

2.1 Custom API のサンプル​

2.1 Media Library と Object Storage​

3. フィールド対応​

4. レスポンシブレイアウト​

5. スクロール読み込み​

6. 全画面プレビューとインタラクション​

7. リクエストコンテキスト​

8. 性能とデータの推奨事項​

9. よくある問題​