Collapse

Collapse は関連する内容を展開・折りたたみ可能な領域に整理します。固定パネルを手動で作る方法と、モデルや API のレコードを 1 つのテンプレートで繰り返す方法があります。

1. Content Mode

モード	用途	内容の作り方
Static	パネル数と構造が固定	CollapsePanel を追加して内容を編集
Data Source	同じ種類のレコードをパネル化	Data Source と 1 つの Item Template

既存のページ JSON に Content Mode がない場合、プロパティパネルには Static が自動表示され、Runtime も Static として動作します。移行は不要です。

このガイドでは、相互補完する 3 つの例を使用します。以下のスクリーンショットと手順だけで再現でき、Spark Sample アプリへのアクセスは必要ありません。

Onboarding Checklist は Content Mode = Static を明示的に設定します。4 つのパネルに異なる読み取り専用フォームを配置し、静的構造、既定の展開、コンポーネント関数を示します。
Frequently Asked Questions は Content Mode = Data Source を使用し、/spark/api/sample/collapse/faqs からレコードを読み込み、FAQ Item Template を繰り返します。Test、フィールドマッピング、ページング、Current Record、開発プレビューデータを確認できます。
Support Answers with Custom Content は同じデータソースを再利用し、ページ Content を各動的パネル内で繰り返します。共有コンテンツと record.* バインディングを確認できます。

2. Static モード

Containers から Collapse を配置します。
Content Mode = Static のままにします。
Collapse Panels で項目を追加し、ドラッグして並べ替えます。
各パネルの Title、Description、Icon、既定の展開、Disabled、Trigger Area を設定します。
Form、Panel などをパネル内に配置します。

外側では Single Panel Mode、Show Border、Transparent Style、Size、Arrow Position を設定します。Trigger Area は Header を推奨します。この場合、右側の余白を含むヘッダー行全体で開閉できます。矢印だけをトリガーにする場合は Icon を選択します。Disabled でも Design Mode では選択して編集できます。

3. Data Source モード

3.1 データソース

Content Mode = Data Source を選びます。
id や code などの Row Unique Key を指定します。すべてのレコードで値が存在し、一意でなければなりません。
Items Per Request と Empty State Text を設定します。
モデルまたは Custom URL を設定し、URL、Method、Rows Path、Total Path、Record Fields を入力します。
Test を実行します。Test は Design Preview と Runtime と同じリクエスト・レスポンス処理を使い、キーの欠落や重複も検出します。

推奨レスポンス：

{
  "success": true,
  "data": {
    "total": 6,
    "current": 1,
    "pageSize": 4,
    "records": [{
      "id": "invite-team",
      "category": "Getting started",
      "question": "When should I invite the wider team?",
      "answer": "Invite the team after access rules are ready.",
      "disabled": false,
      "defaultExpanded": true
    }]
  }
}

Rows Path は data.records、Total Path は data.total にします。

3.2 Item Template

CardSet と同じ操作です。Item Template の編集ボタンを押し、ギャラリーからテンプレートを選び、同じダイアログでフィールドパラメーターを設定します。

Content ではタイトル、説明、本文、カテゴリー、バッジを割り当てます。Behavior では Icon、Visible、Disabled、Default Expanded を必要に応じて割り当てます。3 つのテンプレートは同じ動作契約を共有します。

テンプレート	用途	主なマッピング
FAQ	ヘルプセンター	Title、Answer、Category、Answer Format
Record Summary	業務レコード	Title、Description、Content、Badge
Custom Content	独自レイアウト	ヘッダー、動作フィールド、ページ Content への参照

Live Preview では Preview Record の切り替えと実データの再取得ができます。Save で確定し、Cancel、閉じる操作、Escape では既存テンプレートを変更しません。

3.3 Content でカスタム内容を作成する

Content はページ内で再利用できるリソースであり、Form や Collapse 内の隠れた子キャンバスではありません。Page Resources は Popups と Contents に分かれます。Content を開くと、パレットとプロパティパネルを維持したまま右側から幅広のデザインドロワーが開きます。タイトルバーの閉じるボタン、ドロワー外、Back to page、または Escape で戻れます。

Custom Content では、既存 Content の選択、Create Content、Edit Content、Unlink Content を利用できます。解除は現在の Collapse との参照だけを削除します。同じ Content を複数箇所で共有でき、変更はすべての参照先に反映されます。参照中の Content は削除できません。子コントロールはパラメータマッピングなしで record.* を直接参照できます。旧 Item Template panels は初回ロードまたは保存時に自動で Content に移行されます。

3.4 デザインプレビューと Runtime

Design Preview と Runtime は同じレンダラーを使います。
プレビューは 1 ページを取得し、実データがない場合は Sample Record と明示したサンプルを表示します。
初回はスケルトン、空状態とエラーは明示表示され、Retry できます。
Runtime は次のデータがあれば Load more を表示し、同時に 1 件だけ読み込みます。
再読み込み後も存在する展開キーを維持します。
Runtime は不正キーを除外し、Test は設定エラーとして通知します。

4. インタラクション

Static は Collapse onChange と CollapsePanel onClick、Data Source は Collapse onChange と Item Template onClick を使います。

動的項目では Current Record を書き込み、Item Template onClick、Collapse onChange の順に実行します。アクションは record.* と次の値を参照できます。

collapse.activeKeys
collapse.expandedCount
collapse.changedKey
collapse.changedIndex
collapse.changedNumber
collapse.changedRecord
collapse.expanded
collapse.accordion
collapse.contentMode

Toast の例：FAQ: [[record.question]]。

5. コンポーネント関数

関数	動作
`expandAll`	有効項目を展開。Single Panel Mode では先頭のみ
`collapseAll`	すべて折りたたむ
`resetPanels`	既定の展開状態に戻す
`reloadCollapse`	データを再取得して展開キーを調整
`setCollapseData(data)`	先行アクションが返した配列でデータを置換

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

Test、Design Preview、Runtime は次を自動送信します。

X-Spark-Page-Environment: DEV | TEST | PROD
X-Spark-Page-Render-Mode: DESIGN_PREVIEW | RUNTIME

手動追加は不要です。ページリクエストコンテキストも参照してください。Spark Sample は /spark/api/sample/collapse/faqs を使い、バックエンドは SparkPageRequestHeaders.resolve(environment, renderMode) でコンテキストを解決します。DESIGN_PREVIEW の場合は開発用の決定的なデータを返せます。

7. サンプルの再現

7.1 静的オンボーディングチェックリスト

Collapse を追加し、Static のまま Single Panel Mode をオフにします。
4 つの CollapsePanel を追加し、それぞれに異なる読み取り専用 Form を配置します。
最初の項目で Expanded by Default をオンにします。
expandAll、collapseAll、resetPanels を呼び出す 3 つのボタンを追加します。

7.2 動的 FAQ

Data Source、Single Panel Mode、Transparent Style を選びます。
Row Unique Key を id、Items Per Request を 4 にします。
/spark/api/sample/collapse/faqs、POST、data.records、data.total を設定します。
Test 後に FAQ テンプレートを選びます。
question、answer、category、disabled、defaultExpanded を割り当てます。
onChange に FAQ: [[record.question]] を追加します。

7.3 Custom Content のレコード詳細

Data Source モードの Collapse をもう 1 つ追加し、同じレスポンスパスで /spark/api/sample/collapse/faqs を再利用します。
Custom Content を選び、Title を question、Description を summary に割り当てます。
Create Content を押し、リソース名を Support answer content にして幅広のデザインドロワーで編集します。
Content に読み取り専用 Form を追加し、Controls Per Row を 2、Label を 4、Content を 8 にします。
[[record.category]]、[[record.environment]]、[[record.renderMode]] を表示する読み取り専用 Field を追加します。
[[record.answer]] を表示する全幅の読み取り専用 TextArea を追加します。
Preview Record を切り替え、ヘッダーと Form の両方が更新されることを確認します。

8. トラブルシューティング

Test で Row Unique Key の重複が表示される

行番号ではなく、ページング、並べ替え、再読み込み後も変わらない業務 ID を使用します。

Design Preview に Sample Record が表示される

データソースが未設定、接続不可、またはエラーです。Test で URL、レスポンスパス、バックエンドリクエストを確認します。

テンプレート変更後もプレビューが変わらない

テンプレートダイアログを保存し、Record Fields または実際のレスポンスに対象フィールドがあるか確認します。

Content 内で現在のレコードを読む

子コントロールの値や Interaction 式で record.* を使用し、プレビュー値を固定しないでください。

Load more 後に展開項目が消える

同じ業務レコードが同じ Row Unique Key を維持しているか確認します。Spark が保持できるのは安定したキーだけです。

9. 設計上の推奨事項

1 グループの表示パネルは 3～8 個程度にし、それ以上はカテゴリーや検索を用意します。
FAQ や長い説明では Single Panel Mode を優先し、比較が必要な場合は複数展開を許可します。
Title だけで展開後の内容が分かるようにし、Description で同じ文言を繰り返さないでください。
Disabled はグレー表示だけに頼らず、読める説明を添えます。
バックエンドは安定した一意キーを返し、ページングのレスポンス構造を統一します。
動的マッピングを Record Fields に宣言し、選択、テスト、保守を容易にします。
Collapse の多重ネストは避け、見出し、Tab、または別ページを使用します。

1. Content Mode​

2. Static モード​

3. Data Source モード​

3.1 データソース​

3.2 Item Template​

3.3 Content でカスタム内容を作成する​

3.4 デザインプレビューと Runtime​

4. インタラクション​

5. コンポーネント関数​

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

7. サンプルの再現​

7.1 静的オンボーディングチェックリスト​

7.2 動的 FAQ​

7.3 Custom Content のレコード詳細​

8. トラブルシューティング​

Test で Row Unique Key の重複が表示される​

Design Preview に Sample Record が表示される​

テンプレート変更後もプレビューが変わらない​

Content 内で現在のレコードを読む​

Load more 後に展開項目が消える​

9. 設計上の推奨事項​