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