スキルOfficialdevelopment

📋ui5-best-practices-integration-cards

プラグイン: ui5
ソース: GitHub で見る ↗

説明

UIインテグレーションカード（UI5インテグレーションカードとも呼ばれる）に関するあらゆるタスクの前に必ずロードすること。対象タスクは以下の通り: カードの作成・修正・検証・プレビュー・レビュー、`manifest.json` の編集、Configuration Editor（`dt/Configuration.js`）の設定、および各種分析チャートの設定。公式ガイドライン、バリデーションルール、サポートされるチャートタイプ、およびConfiguration Editorのパターンを提供します。

原文を表示

MUST be loaded before any UI Integration Cards (also called UI5 Integration Cards) task — creating, modifying, validating, previewing, or reviewing a card, its `manifest.json`, its Configuration Editor (`dt/Configuration.js`), or any analytical chart configuration. Provides the official guidelines, validation rules, supported chart types, and Configuration Editor patterns.

ユースケース

✓UIインテグレーションカードを作成するとき
✓カードを修正・検証するとき
✓manifest.jsonを編集するとき
✓Configuration Editorで設定するとき
✓分析チャートを設定するとき

本文（日本語訳）

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

UI Integration Card を作成・変更・検証・プレビューする際に Agent が従うべきルール。カードを正常に動作させるために、これらのルールの遵守は必須です。

各参照ファイルを読み込むタイミング

トリガー	読み込むファイル
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}` — 単括弧、`>` 区切り、`value` サフィックス。
Destination バインディング構文	`{{destinations.destinationName}}` — 二重括弧、ドット区切り。`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/ 配下に記述すること。

症状 — "No data to display": 多くの場合、主データパスを上書きする 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. Configuration Editor

Configuration Editor を使用すると、Administrator・Page/Content Administrator・Translator の各ペルソナが manifest.json を直接編集することなくカードをカスタマイズできます。

構成要素は 2 つです:

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

Administrator ペルソナを想定して設計すること。

ルール	詳細
マニフェストを反映する	Editor は `manifest.json` の現在の構造とパラメータを正確に反映する。`manifestpath` は既存の任意のパスをターゲットにできる。パラメータ化されたフィールドには `configuration/parameters/*/value`、静的なマニフェストプロパティには `/sap.card/header/icon/shape` のような直接パスを使用する。
既存フィールドをすべて編集可能にする	タイトル、サブタイトル、ヘッダーアイコン、パラメータをすべて設定可能にする。
ユーザーに確認する	公開するフィールドを決定する前に、「すべてのマニフェストフィールドを編集可能にしますか？他に追加するものはありますか？」と尋ねる。
独自フィールドを追加しない	`manifest.json` に存在しない Editor フィールドを追加してはならない。
同期を維持する	`manifest.json` への追加・削除に合わせて Editor も追加・削除する。

正規のペア例については references/configuration_editor_example.md を読み込むこと。

6. Analytical カード

チャートタイプのカタログ（UID および種類ごとの例）については references/analytical_chart_types.md を読み込むこと。

ルール	詳細
`chartType` を設定する	`sap.card/content/chartType` は必須。
チャートタイプに合わせた Feed を設定する	`measures`、`dimensions`、`feeds` は、チャートタイプが期待する UID と一致させる必要がある。参照ファイルにチャートごとの UID が記載されている。
各 Feed に 3 つのキーが必要	`type`（`Dimension` または `Measure`）、`uid`、`values`。
`chartProperties`	ラベル、カラー、凡例などに使用する。キーを独自に作成してはならない。デフォルトで問題なければ完全に省略する。

最小限の feeds 設定例（donut / pie）:

"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

原文（English）を表示

Best practices for UI Integration Cards development

Rules an agent must follow when creating, modifying, validating, or previewing a UI Integration Card. Adherence is critical for working cards.

When to load each reference

Trigger	Load
Working on or planning an Analytical card	`references/analytical_chart_types.md`
`dt/Configuration.js` exists, is being created, or is being modified	`references/configuration_editor_example.md`

If the trigger applies, load before producing any output. Do not work from memory.

1. Core rules

Rule	Detail
Prefer declarative cards	Types: List, Table, Calendar, Timeline, Object, Analytical. Create an Extension only in exceptional cases.
Use `create_integration_card` MCP tool	When creating a new declarative card.
Parameter binding syntax	`{parameters>/parameterKey/value}` — single braces, `>` separator, `value` suffix.
Destination binding syntax	`{{destinations.destinationName}}` — double braces, dot. Configure under `sap.card/configuration/destinations/`. Reference by name; never replace with raw URL.
Use destinations for service URLs	Wrap every external service URL in a destination under `sap.card/configuration/destinations/` and reference it as `{{destinations.name}}`.
i18n binding	Bind every non-data, user-visible string to the i18n model.
Links	Use the `actions` property; never inline `<a>` or hand-rolled URL handlers.
Validate before declaring done	See 3. Validation.
Show preview when requested	See 4. Preview.
Don't modify provided data	Use it as supplied.
JSON responses only	The endpoint behind `sap.card/data/request` must return JSON. For OData services, append `$format=json` to the request URL or parameters.

2. Data placement

sap.card/data/ is the only correct top-level location for the data request.

Path	Purpose
`sap.card/data/path`	Primary data path
`sap.card/content/data/path`	Content-specific path; overrides the primary path if set
`sap.card/header/data/path`	Header-specific path; overrides the primary path if set

Forbidden: putting the request itself under sap.card/content/data/ or sap.card/header/data/.

Symptom — "No data to display": typically caused by a content/data block that overrides the primary data path. Verify 2. Data placement before debugging anything else.

3. Validation

Rule	Detail
Valid JSON	`manifest.json` must parse.
`sap.app/type`	Must be `"card"`.
Schema validation	Use `run_manifest_validation` MCP tool.
No deprecated properties	In `manifest.json` or elsewhere.
Not a UI5 project	Except for `Component`-type cards.

4. Preview

If asked to preview, first check the card folder for an existing preview entry point — package.json start script, README.md, or an existing HTML file. Reuse it if present. Otherwise create an HTML page with a <ui-integration-card> element pointing at the manifest, and serve via an http server.

5. Configuration Editor

The editor lets the Administrator, Page/Content Administrator, and Translator personas customize a card without editing manifest.json directly.

Two pieces:

dt/Configuration.js — exports a function that returns new Designtime({ form: {...} }).
manifest.json — references the file at sap.card/configuration/editor.

Design as the Administrator persona.

Rule	Detail
Mirror the manifest	Editor reflects the current structure and parameters of `manifest.json` exactly. `manifestpath` can target any existing path — a `configuration/parameters/*/value` for parameterized fields, or a direct path like `/sap.card/header/icon/shape` for static manifest properties.
All existing fields editable	Title, subtitle, header icon, parameters — make them configurable.
Ask the user	Before deciding which fields to expose, ask: "Make all manifest fields editable? Anything else to add?"
No invented fields	Never add an editor field that does not exist in `manifest.json`.
Keep in sync	Add to or remove from the editor when adding to or removing from `manifest.json`.

Load references/configuration_editor_example.md for the canonical paired example.

6. Analytical cards

Load references/analytical_chart_types.md for the full chart-type catalog (UIDs and per-type examples).

Rule	Detail
Set `chartType`	`sap.card/content/chartType` is required.
Match feeds to chart type	`measures`, `dimensions`, and `feeds` must match the UIDs the chart type expects. The reference file lists them per chart.
Each feed needs three keys	`type` (`Dimension`\|`Measure`), `uid`, `values`.
`chartProperties`	Use it for labels, colors, legend, etc. Do not invent keys. Omit entirely if defaults are fine.

Minimal feeds example (donut/pie):

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

7. Card Explorer (reference)

Schema docs and live samples: https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html
Sample sources: https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。