Ui5 Best Practices Integration Cards

作者 UI5a99b882ce364無授權條款收錄於 2026年10月8日更新於 2026年10月8日

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.

僅含說明Software Development

AI 產生的概覽

用於建置、驗證與預覽 SAP UI5 整合卡片及其資訊清單的準則與驗證規則。

功能: 提供代理在建立、修改、驗證、預覽或審查 UI 整合卡片時必須遵循的規則。內容涵蓋 manifest.json 結構、資料放置、參數與目的地綁定語法、i18n、驗證步驟、預覽設定、設定編輯器模式以及分析圖表設定。兩個參考檔案分別提供圖表類型目錄與成對的設定編輯器範例。
適用情境: 在涉及 UI 整合卡片的任何工作之前使用，包括建立或編輯卡片、其 manifest.json、其 dt/Configuration.js 編輯器或分析圖表設定。也適用於驗證或預覽現有卡片。
執行需求: 僅為指示性內容，未隨附指令碼。它引用兩個隨附的 Markdown 參考檔案，並需要名為 create_integration_card 與 run_manifest_validation 的 MCP 工具，以及用於預覽卡片的 http 伺服器。

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` [blocked]
`dt/Configuration.js` exists, is being created, or is being modified	`references/configuration_editor_example.md` [blocked]

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 [blocked] for the canonical paired example.

6. Analytical cards

Load references/analytical_chart_types.md [blocked] 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):

json

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

"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

來源與署名

來源：UI5/plugins-coding-agents位於plugins/ui5/skills/ui5-best-practices-integration-cards提交a99b882

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Ui5 Best Practices Integration Cards

Best practices for UI Integration Cards development

When to load each reference

1. Core rules

2. Data placement

3. Validation

4. Preview

5. Configuration Editor

6. Analytical cards

7. Card Explorer (reference)

來源與署名

更多來自 UI5/plugins-coding-agents 的技能

Modernize Ui5 App

Modernize Flp Sandbox

Fix Xml Native Html

Fix Table Row Mode

Fix Pseudo Modules

Fix Partially Deprecated Apis

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Testing Strategy

Tech Debt

System Design