ui5-best-practices-integration-cards

UI Integration Card 開発のベストプラクティス

UI Integration Card の作成、変更、検証、またはプレビュー時にエージェントが従うべきルールです。動作するカードを作るには、これらのルールに従うことが重要です。

各リファレンスを読み込むタイミング

トリガー	読み込むファイル
Analytical カードを作成または計画している	references/analytical_chart_types.md
dt/Configuration.js が存在する、作成中、または変更中である	references/configuration_editor_example.md

トリガーに該当する場合は、出力する前に読み込んでください。記憶に頼って作業してはいけません。

1. 基本ルール

ルール	詳細
宣言型カードを優先する	種類：List、Table、Calendar、Timeline、Object、Analytical。例外的な場合にのみ Extension を作成してください。
create_integration_card MCP ツールを使用する	新しい宣言型カードを作成する場合に使用します。
パラメーターのバインド構文	{parameters>/parameterKey/value} — 中かっこは1組、区切り文字は >、末尾は value です。
Destination のバインド構文	{{destinations.destinationName}} — 中かっこは2組、区切り文字はドットです。sap.card/configuration/destinations/ の下で設定します。名前で参照し、生の URL に置き換えてはいけません。
サービス URL には Destination を使用する	外部サービスの URL はすべて sap.card/configuration/destinations/ の下にある Destination でラップし、{{destinations.name}} として参照してください。
i18n バインド	データ以外のユーザー向け文字列はすべて i18n モデルにバインドしてください。
リンク	actions プロパティを使用してください。インラインの <a> や独自実装の URL ハンドラーを使用してはいけません。
完了を宣言する前に検証する	3. 検証 を参照してください。
求められた場合はプレビューを表示する	4. プレビュー を参照してください。
提供されたデータを変更しない	提供された状態のまま使用してください。
JSON のレスポンスのみ	sap.card/data/request の接続先エンドポイントは JSON を返す必要があります。OData サービスの場合は、リクエスト URL またはパラメーターに $format=json を追加してください。

2. データの配置

データリクエストを配置できる正しいトップレベルの場所は、sap.card/data/ のみです。

パス	用途
sap.card/data/path	主要なデータパス
sap.card/content/data/path	コンテンツ固有のパス。設定されている場合、主要なデータパスを上書きします
sap.card/header/data/path	ヘッダー固有のパス。設定されている場合、主要なデータパスを上書きします

禁止事項：リクエスト自体を sap.card/content/data/ または sap.card/header/data/ の下に配置すること。

症状 —「表示するデータがありません」： 通常は、主要なデータパスを上書きする content/data ブロックが原因です。他の問題をデバッグする前に、2. データの配置 を確認してください。

3. 検証

ルール	詳細
有効な JSON	manifest.json が解析できる必要があります。
sap.app/type	"card" である必要があります。
スキーマ検証	run_manifest_validation MCP ツールを使用してください。
非推奨プロパティを使用しない	manifest.json などで非推奨プロパティを使用してはいけません。
UI5 プロジェクトではない	Component タイプのカードを除きます。

4. プレビュー

プレビューを求められた場合は、まずカードのフォルダーに既存のプレビュー用エントリーポイントがあるか確認してください。対象は package.json の start スクリプト、README.md、または既存の HTML ファイルです。存在する場合は再利用してください。存在しない場合は、マニフェストを参照する <ui-integration-card> 要素を含む HTML ページを作成し、http サーバー経由で配信してください。

5. 設定エディター

エディターを使うと、管理者、ページ／コンテンツ管理者、翻訳者の各ペルソナは、manifest.json を直接編集せずにカードをカスタマイズできます。

次の2つで構成されています。

1. dt/Configuration.js — new Designtime({ form: {...} }) を返す関数をエクスポートします。
2. manifest.json — sap.card/configuration/editor でファイルを参照します。

管理者ペルソナとして設計してください。

ルール	詳細
マニフェストを反映する	エディターには、manifest.json の現在の構造とパラメーターを正確に反映します。manifestpath では、パラメーター化されたフィールドの configuration/parameters/*/value や、静的なマニフェストプロパティの /sap.card/header/icon/shape など、既存の任意のパスを指定できます。
既存のフィールドはすべて編集可能にする	タイトル、サブタイトル、ヘッダーアイコン、パラメーターなど、設定可能にします。
ユーザーに尋ねる	公開するフィールドを決める前に、「すべてのマニフェストフィールドを編集可能にしますか？ほかに追加するものはありますか？」と尋ねます。
フィールドを作り出さない	manifest.json に存在しないエディターフィールドは追加しないでください。
同期を保つ	manifest.json にフィールドを追加または削除したら、エディターにも反映してください。

正式な対応例については、references/configuration_editor_example.md を読み込んでください。

6. 分析カード

チャートタイプの一覧（UID とタイプごとの例）については、references/analytical_chart_types.md を読み込んでください。

ルール	詳細
chartType を設定する	sap.card/content/chartType は必須です。
フィードをチャートタイプに合わせる	measures、dimensions、feeds は、チャートタイプが想定する UID に一致させる必要があります。各チャートで必要な UID は参照ファイルに記載されています。
各フィードに3つのキーを設定する	type（Dimension|Measure）、uid、values を設定します。
chartProperties	ラベル、色、凡例などに使用します。キーを作り出さないでください。デフォルトで問題なければ、省略します。

最小限のフィード例（ドーナツ／円グラフ）：

"feeds": [
  { "type": "Dimension", "uid": "color", "values": ["Store Name"] },
  { "type": "Measure", "uid": "size", "values": ["Revenue"] }
]

7. Card Explorer（リファレンス）

• スキーマのドキュメントとライブサンプル：https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html
• サンプルのソース：https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples