CardSet コンポーネント
CardSet は、同じデータ ソースからの複数のレコードを応答性の高いカード コレクションにレンダリングするために使用されます。製品カタログ、アプリケーション リスト、資産カタログ、ナレッジ エントリなど、エンティティの概要を素早く参照する必要があるページに適しています。
このマニュアルを読んだ後、次の構成を完了できます。
- ビジネス オブジェクトまたはカスタム URL を使用してデータをロードする
- カスタム URL の再利用可能な応答フィールドを定義またはインポートする
- ビジュアル テンプレート ライブラリから標準、カバー、またはコンパクト カードを選択します
- 戻りレコードのフィールドをタイトル、説明、画像、ステータス、メタデータにマップします
- 固定フィルター、クエリフィールド、クエリフォームの設定
- デスクトップ、タブレット、モバイルデバイスの列数を設定します
- ページめくり方法を「ページネーション」と「もっと読み込む」から選択します。
- 現在のレコードを使用して、カード全体のクリックとカード操作を設定します
CardSet はデータ駆動型の繰り返しコレクションであり、静的カードを 1 枚ずつ手動で管理するためには使用されません。表形式のデータの場合は、DataList または ProTable を使用してください。
1. 使用前の準備
1.1 データソースの選択
CardSet は次のデータ ソースをサポートします。
| データソース | 該当するシナリオ |
|---|---|
| モデル データ ソース | データは Spark Business Object から取得され、DQL、モデル フィールド、またはクエリ フォームが必要です。 |
| カスタム URL | データはアプリケーション API、外部サービス、またはカスタム集計インターフェイスから取得されます。 |
モデル データ ソースを使用する前に、 オブジェクト デザイナー でビジネス オブジェクト、フィールド、クエリ、およびクエリ シナリオ データ フォームを完成させる必要があります。
カスタム URL は、ページング可能なレコードのコレクションを提供する必要があります。推奨される応答形式:
{
"success": true,
"data": {
"current": 1,
"pageSize": 12,
"records": [],
"total": 0
}
}
1.2 この記事の例
この記事では、Spark サンプル製品カタログ インターフェイスを使用します。
POST https://spark.hiforce.ai/spark/api/sample/cardset/products
インターフェイスは、以下を含む 23 個の英語の製品データを返します。
| フィールド | 目的 |
|---|---|
id | 一意のキーを記録する |
コード | カード補助タイトル |
名前 | カードタイトル |
説明 | カードの説明 |
imageUrl | 表紙画像 |
ステータス | ステータスラベル |
カテゴリー | 製品分類 |
| 「価格」 | 製品価格 |
| 「在庫」 | 現在の在庫 |
更新された | 更新時間 |
2. カードセットの追加
- 対象のページを開き、 ページ デザイナー と入力します。
- 左側のコンポーネント パネルで コンテナ を展開します。
- CardSet をページ コンテナにドラッグします。
- CardSet を選択し、最初に右側のプロパティ パネルで データ ソース を構成し、次に カード テンプレート を構成します。
- コントロールの安定した名前 (「productCardSet」 など) を設定します。
CardSet では、Java CardTemplate クラス名を推測する必要がなくなりました。テンプレートの外観とフィールド マッピングは、ビジュアル構成ダイアログ ボックスで統合されています。
3. データソースの構成
3.1 カスタム URL の例
データ ソース で カスタム URL を選択し、次のように設定します。
| プロパティ | 値 |
|---|---|
| URL | /spark/api/sample/cardset/products |
| リクエスト方法 | ポスト |
| 行パス | データ.レコード |
| 合計パス | データ.合計 |
| 現在のページのパス | データ.現在の |
| ページ サイズ パス | data.pageSize |
カスタム URL 自体はビジネス オブジェクトのようなモデル メタデータを提供できないため、 応答フィールド も同じデータ ソース ダイアログで構成する必要があります。この記事の構成例は次のとおりです。
| フィールドパス | ラベル | データ型 |
|---|---|---|
id | ID | 番号 |
コード | コード | テキスト |
名前 | 名前 | テキスト |
説明 | 説明 | テキスト |
imageUrl | 画像の URL | URL |
ステータス | ステータス | テキスト |
カテゴリー | カテゴリー | テキスト |
| 「価格」 | 価格 | 番号 |
| 「在庫」 | 在庫 | 番号 |
更新された | 更新日 | 日時 |
応答フィールドには 2 つの構成方法があります。
- プラス記号をクリックして、フィールド パス、ラベル、データ タイプを手動で追加します。
- URL、リクエスト メソッド、および応答パスを入力した後、[テストとインポート] をクリックして実際の応答からインポートします。
テストとインポートは最大 20 レコードを読み取り、そのレコード内に表示されるフィールドを結合します。ネストされたオブジェクトは、「owner.name」の形式でポイント パスを生成します。配列は ARRAY としてのみ登録され、配列の添字を含む不安定なパスは生成されません。インポートでは、手動で変更されたラベル、データ型、順序が保持され、新しいフィールドのみが追加され、古いフィールドは自動的に削除されません。インターフェイスが空の配列を返した場合、またはリクエストが失敗した場合、既存の構成は変更されません。
応答フィールドはページ設定に保存されるフィールド コントラクトであり、インターフェイスによって返されるサンプル値は保存されません。 [データ ソース] ダイアログ ボックスを開いても、バックグラウンドは自動的に呼び出されません。
CardSet は、現在のページ、ページごとの数、固定フィルター、クイック クエリ、およびクエリ フォームの値を送信します。 POST リクエストの例:
{
"current": 1,
"pageSize": 12,
"conditions": [
{"field": "status", "operator": "EQ", "value": "ACTIVE"}
],
"queryFormValues": {}
}
カスタム URL リクエストには、統合されたページ コンテキスト ヘッダーも自動的に送信されます。
| ヘッダー | 列挙値 | 説明 |
|---|---|---|
X-Spark-ページ環境 | 開発、テスト、本番 | 現在のページ環境。デザイナーのプレビューは DEV を使用するように修正されました。 |
| `X-Spark-Page-Render-Mode' | DESIGN_PREVIEW、RUNTIME | ページデザイナー、デザイナーによって開かれたプレビュー、および実際のレコードのプレビューは DESIGN_PREVIEW です。通常の実行ページは RUNTIME |
たとえば、開発環境の実行ページは DEV + RUNTIME を送信し、カード テンプレート ダイアログ ボックスの実レコード プレビューは DEV + DESIGN_PREVIEW を送信します。これは、CardSet だけでなく、すべてのページ デザイナーおよびページ ランタイムのバックエンド リクエストに対する統一仕様です。バックエンドは安定した列挙を処理する必要があり、リファラーを通じてシナリオを推論しないでください。クロスドメイン カスタム URL では、CORS の「Access-Control-Allow-Headers」でこれら 2 つのヘッダーを許可する必要もあります。
3.2 モデルデータソース
モデル データ ソース を選択した後:
- 「ビジネスオブジェクト」を選択します。
- 必要に応じて [DQL クエリ] を選択します。
- リクエストパラメータの DQL パラメータをバインドします。
- カード テンプレートのフィールド ドロップダウン リストは、現在のビジネス オブジェクトのフィールド メタデータを直接使用します。
モデル データ ソースのページング、DQL パラメーター、クエリ条件は、Spark ランタイムによって均一に処理されます。
4. カードテンプレートを選択します
カード テンプレート の右側にある編集アイコンをクリックして、幅広い設定ダイアログ ボックスを開きます。最上位のテンプレート ライブラリには、3 つのサムネイル プレビューが直接表示されます。
| テンプレート | 該当するシナリオ |
|---|---|
| 標準 | 一般的なビジネス エンティティ、タイトル、説明、ステータス、メタデータのバランスのとれた構造 |
| 表紙 | 16:9 のカバー画像をフィーチャーしたマーチャンダイジング、メディア、およびアセットのカタログ |
| コンパクト | 運用保守または管理ワークベンチ、記述領域の削減と情報密度の向上 |
テンプレートを選択すると、右側のプレビューがすぐに変わります。テンプレートの外観を判断するために実行ページを保存したり、入力したりする必要はありません。テンプレート ライブラリの下部は、テーマに応じて、 コンテンツ、 クエリ、 レイアウトとページング の 3 つのタブに分かれています。右側のプレビューは常に保持され、デスクトップ、タブレット、モバイルを使用してプレビュー幅を切り替えます。
設定エリアとプレビューエリアは独立してスクロールできます。コンテンツ内のカード フィールド、メタデータ、ステータス トーンはすべて独立したグループ化を使用します。クエリ フィールドと固定フィルターでも、列ヘッダーのある構成テーブルが使用されます。多くの構成がある場合は、現在のタブを下にスクロールし続ける必要があります。これにより、一番下の構成がダイアログ ボックスで切り取られなくなります。
5. フィールドマッピングの設定
コンテンツ タブに入り、カード フィールド、メタデータ、ステータス トーンを設定します。各カード フィールドの右側には、見出し、コーナー、タイトルの上、本文など、カードが含まれるカード領域がマークされます。タイトルには赤い必須マークが付いています。
この記事の表紙の例では、次のマッピングを使用します。
| カードエリア | フィールド |
|---|---|
| アイブロウフィールド | コード |
| タイトルフィールド | 名前 |
| 説明フィールド | 説明 |
| 画像フィールド | imageUrl |
| ステータスフィールド | ステータス |
タイトル フィールドは最も重要な識別フィールドであり、常に設定する必要があります。他のフィールドが空の場合、対応する領域には空白スペースは保持されません。
5.1 フィールドソースとカスタムパス
フィールド ドロップダウン リストはデータ ソースによって提供されます。
- モデル データ ソースはビジネス オブジェクト フィールドのメタデータを使用します。
- カスタム URL は、保存された応答フィールドを使用します。
フィールドを選択すると「ラベル(パス)」が表示され、ラベルまたはパスで検索できます。未登録の動的フィールドをバインドする必要がある場合は、 カスタム パスの追加 を選択し、手動で入力します。異なる CardSet または ProTable で文字列パスが繰り返しメンテナンスされることを避けるために、通常のフィールドを最初に応答フィールドに追加する必要があります。
ネストされたオブジェクトでは、次のような点線のパスが使用されます。
owner.name
pricing.amount
CardSet を保存するにはタイトル フィールドが必要です。他のオプションのマッピングが空の場合、対応するカード領域はレンダリングされません。
5.2 実際のプレビューを更新する
データ ソースとフィールド マッピングが保存されたら、右側の [ライブ プレビュー] タイトルの横にある更新アイコンをクリックします。デザイナーは pageSize=1 のレコードを読み取り、X-Spark-Page-Environment: DEV および X-Spark-Page-Render-Mode: DESIGN_PREVIEW を送信します。
更新では、右側のカードの表示値が更新されるだけで、応答フィールドの追加、削除、変更は行われません。リクエストが失敗した場合でも、現在のプレビューとフィールド設定を保持します。
5.3 メタデータの構成
メタデータは、価格、在庫、担当者、更新時間などの短い情報を表示するために使用されます。 [行を追加] をクリックして新しい行を追加します。構成テーブルには、ラベル、フィールド、およびフォーマットの列ヘッダーが永続的に表示されます。
| プロパティ | 説明 |
|---|---|
| ラベル | カードに表示される短いラベル。 「価格」 |
| フィールドパス | データ フィールド (「価格」など) |
| フォーマット | テキスト、数値、通貨、日付または日時 |
製品例では、以下を追加することを提案しています。
| ラベル | フィールド | フォーマット |
|---|---|---|
| カテゴリー | カテゴリー | テキスト |
| 価格 | 「価格」 | 通貨 |
| 在庫 | 「在庫」 | 番号 |
5.4 ステータストーンの設定
ステータス トーンは、オプションのステータス カラー マップです。設定テーブルでは、ステータスが等しい場合とトーンを表示するという 2 つの列を使用します。たとえば、「ACTIVE」は「SUCCESS」にマッピングされ、「DRAFT」は「WARNING」にマッピングされます。マッピングが設定されていない場合、CardSet は一般的な状態値には組み込みのセマンティック カラーを使用し、不明な値には「MUTED」を使用します。
6. クエリの構成
[クエリ] タブに入り、クエリ フォーム、フィルタ バーの表示、クエリ フィールド、および固定フィルタを設定します。クエリ フォームとフィルター バーの表示は上部のツールバーにあり、クエリ フィールドと固定条件は下にグループ化されています。
6.1 クエリフィールド
クエリフィールドはクエリ領域の最初の行に表示されます。構成テーブルのフィールド、ラベル、演算子、タイプ列ヘッダーの表示が修正されました。
フィールドを選択すると、デザイナーは応答フィールドまたはビジネス オブジェクト フィールドのラベルとデータ タイプをクエリ構成に事前に設定します。ラベルとクエリのタイプは引き続き調整できます。 OBJECTとARRAYはショートカットクエリフィールドの候補には表示されません。
おすすめ商品の例：
| フィールド | ラベル | オペレーター | タイプ |
|---|---|---|---|
名前 | 製品を探す | 「いいね」 | テキスト |
カテゴリー | カテゴリー | EQ | テキスト |
ステータス | ステータス | EQ | テキスト |
日付と時刻のタイプは、範囲ピッカーとして自動的にレンダリングされます。 [検索]、[詳細]、および [リセット] は常にクエリ バーの右側にあります。
6.2 固定フィルター
固定フィルターはクエリを実行するたびに有効になりますが、実行中のユーザーには表示されません。たとえば、有効な製品のみを表示するには:
| フィールド | オペレーター | 値 |
|---|---|---|
ステータス | EQ | アクティブ |
フィルター バーの表示 をオフにすると、ユーザー クエリ領域が非表示になるだけで、固定フィルターは無効になりません。
6.3 クエリフォーム
クエリ フォームは、オプションの高度なクエリ フォームです。ドロップダウン リストでクエリ シナリオのデータ フォームを選択した後、実行時に [詳細] をクリックしてフォームを展開します。 CardSet がモデル データ ソースを使用する場合、ドロップダウン リストでは現在のビジネス オブジェクトのクエリ フォームの表示が優先されます。カスタム URL を使用すると、アプリケーションで使用できる QUERY フォームが表示されます。
- モデル データ ソースは、現在のビジネス オブジェクトの QUERY データ フォームを選択する必要があります。
- カスタム URL は
queryFormValuesをそのままバックエンドに送信し、インターフェースがフィールドの意味を解釈します。
7. レイアウトとページングを構成する
[レイアウトとページング] タブに入り、応答性の高い列番号、間隔、ページング、および行の一意のキーを構成します。レスポンシブ列グループは、デスクトップ、タブレット、モバイルの 3 つのデバイス図を使用して、現在の列数をリアルタイムで表示します。ページングとデータ グループは、ページング モード、ページ サイズ、および行固有キーを一元的に管理します。
推奨されるデフォルト値:
| プロパティ | デフォルト値 |
|---|---|
| デスクトップコラム | 4 |
| タブレットコラム | 2 |
| モバイルコラム | 1 |
| 間隔 | デフォルト |
| ページサイズ | 12 |
| ページングモード | ページネーション |
| 行の一意のキー | id |
ページング モードは以下をサポートします。
PAGINATION: ページ管理に適した総ページ数とページ番号を表示します。LOAD_MORE: ディレクトリの参照に適したレコードの次のページを追加します。NONE: インターフェースから現在返されているデータのみが表示され、ページめくりコントロールは表示されません。
右側のデスクトップ、タブレット、モバイルのセグメント コントロールを使用して、1 枚のカードの幅を確認します。実際の動作時にはページ幅に応じて段数が自動的に切り替わります。
8. インタラクションを設定する
CardSet では、次の 2 つのレベルでインタラクションを設定できます。
- カード全体の
onClick。 - カード下部に表示するアクションの
onClick。
8.1 カードアクションを設定する
Card Actions は Card Template ダイアログの外で設定します。 キャンバス上の CardSet を選択し、右側のプロパティパネルにある Card Actions 子要素セクションを使用します。
- Add child element をクリックして
CardActionを作成します。 - 追加フォームに Title を入力して確定します。新しい CardAction が自動的に選択されます。
- CardAction のプロパティパネルで共通の Icon ピッカーを使用し、システムアイコンを選択するか、カスタム画像をアップロードします。
- Interaction をクリックし、
onClickイベントと実行するアクションを追加します。
既存のアクションを編集するには、 Card Actions リストで対象の行をクリックします。左側のドラッグハンドルで順序を変更できます。実行時には、先頭から 3 件のアクションがその順序で各カードの下部に表示されます。アクションのクリックはイベントの伝播を停止するため、カード全体のクリックは同時に実行されません。
8.2 カード全体のクリックを設定する
CardSet 本体を再度選択し、 Interaction をクリックして onClick を設定します。カード全体のクリックを設定したカードは Tab でフォーカスでき、Enter または Space で実行できます。
8.3 現在のレコードを参照する
どちらのインタラクションでも、CardSet は実行前にクリックされたカードのレコードを record としてランタイムコンテキストへ書き込みます。Interaction エディターでは、このデータソースが Current Record と表示され、後続のアクションから次のように参照できます。
record.id
record.code
record.name
これらは実行時にクリックしたカードの値であり、設計時に固定された値ではありません。Interaction エディターに適切な Current Record のフィールド候補を表示するには、Custom URL の Response Fields を設定するか、Model Data Source に Business Object のフィールドメタデータを用意してください。
8.4 例: ドロワー内のカードの詳細を表示する
View product の例では、同じ onClick の下に次の 2 つのアクションをこの順序で設定します。
- Set component value を追加し、 Fill product details という名前を付けます。
record.id、record.code、record.nameなどの Current Record フィールドを、詳細ドロワー内の対応するフォームコントロールへマッピングします。 - Open/close dialog/drawer を追加し、 Open product details という名前を付けます。Target component を Product details (Drawer) に設定し、 Open target を有効にします。
先にフォームへ値を書き込み、その後でドロワーを開いてください。Interaction エディターは Action tree を上から下へ実行します。順序を逆にすると、ドロワーを開いた直後に前のレコードや空の値が一時的に表示されることがあります。
設定後、カード下部の View product をクリックすると、そのカードの商品詳細がドロワーに表示されます。
9. バックエンド実装のサンプル
サンプルコードは次の場所にあります。
spark-sample/src/main/java/hiforce/spark/sample/cardset/
製品クエリでは、ProTable サンプルのページングと条件付き処理を再利用します。 CardSet コントローラーは専用 URL を公開する役割を果たします。カバー画像はローカル PNG エンドポイントによって生成され、外部画像サービスに依存しません。
ローカルで起動した後に確認できます。
curl -X POST 'http://localhost:18080/spark/api/sample/cardset/products' \
-H 'Content-Type: application/json' \
-H 'Accept-Language: zh-CN' \
-H 'X-Spark-Page-Environment: DEV' \
-H 'X-Spark-Page-Render-Mode: DESIGN_PREVIEW' \
-d '{"current":1,"pageSize":12,"conditions":[{"field":"status","operator":"EQ","value":"ACTIVE"}]}'
サンプル応答の data.requestContext は、正規化された environment と renderMode をエコーして、バックエンドが実際にページ コンテキストを受信して処理したことを確認します。運用ビジネス インターフェイスは、このコンテキストを使用して、エコーを必要とせずにデータを選択したり、監査を実行したりできます。
10. よくある質問
デザイナーにはテンプレート名のみがあり、外観はありません
新しい カード テンプレート 編集アイコンを使用していることを確認してください。テンプレートは 3 つのサムネイルとともに表示されます。 「ResourceInfoCard」のような古いクラス名がまだ表示される場合は、デザイナーのメタデータを更新し、CardSet を再度追加します。
実行中にカードがありません
順番に確認してください:
- データ ソースが保存されているかどうか。
- Rows Path が配列を指しているかどうか。
- タイトルフィールドがレコード内に存在するかどうか。
- ブラウザネットワークでのリクエストが成功したかどうかを確認します。
- 固定フィルターがすべてのレコードを除外するかどうか。
カスタム URL のフィールド ドロップダウン リストが空です
データ ソースを開いて、応答フィールドが保存されているかどうかを確認します。手動で追加することも、URL と行パスが正しいことを確認した後で テストとインポート を使用することもできます。ライブ プレビューの更新では、フィールド カタログの生成は行われません。
テストとインポートにはインポート フィールドがありません
URL、リクエストメソッド、行パス、ブラウザネットワークを確認してください。インターフェイスは、現在の条件下で少なくとも 1 つのレコードを返す必要があります。正当だが空の結果はフィールドを生成しないため、この場合は応答フィールドを手動で管理する必要があります。
画像が表示されない
画像フィールドは、ブラウザがアクセスできる画像 URL を返す必要があります。相対 URL は現在の Spark ドメイン名に基づいており、インターフェイスが HTML ログイン ページを返さないことを確認する必要があります。
クエリ後の結果に変化はありません
カスタム URL バックエンドは、「条件」と「クエリフォーム値」を処理する必要があります。 CardSet はクエリ セマンティクスの送信のみを担当し、ブラウザ内の完全なデータ セットに対して二次的なフィルタリングは実行しません。
11. 構成チェックリスト
- データ ソースは「レコード」と「合計」を返すことができます
- 設定および保存されたカスタム URL 応答フィールド
- 行の一意のキーは各レコード内で一意です
- サムネイルから適切なテンプレートが選択されました
- タイトル フィールドが設定されており、null 以外の値を返します
- カバー テンプレートにはアクセス可能な画像フィールドが設定されています
- メタデータはページのスキャンに必要な情報量を超えません
- クエリ フィールドと固定フィルターは、バックエンドでサポートされているフィールドと演算子を使用します
- カスタム URL バックエンドは 2 つの
X-Spark-Page-*ヘッダーを正しく処理します - デスクトップ、タブレット、モバイルのプレビューでオーバーフローなし
- ページネーションまたは Load More で次のページを正しく読み取ることができます
- カードのクリックとアクション項目で現在のレコードを読み取ることができます