ui5-best-practices-integration-cards

UI 集成卡片开发最佳实践

Agent 在创建、修改、验证或预览 UI 集成卡片时必须遵守的规则。严格遵守这些规则对卡片正常运行至关重要。

何时加载各参考资料

触发条件	加载
正在处理或规划分析型卡片	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 后缀。
目标绑定语法	{{destinations.destinationName}} —— 双花括号、点号。在 sap.card/configuration/destinations/ 下配置。通过名称引用；切勿替换为原始 URL。
使用目标存放服务 URL	将每个外部服务 URL 封装在 sap.card/configuration/destinations/ 下的目标中，并以 {{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。

包含两部分：

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. 分析卡片

加载 references/analytical_chart_types.md，查看完整的图表类型目录（UID 和各类型示例）。

规则	详情
设置 chartType	sap.card/content/chartType 为必填项。
让数据馈送与图表类型匹配	measures、dimensions 和 feeds 必须与图表类型所需的 UID 匹配。参考文件列出了各图表对应的 UID。
每个数据馈送需要三个键	type（Dimension|Measure）、uid、values。
chartProperties	用于设置标签、颜色、图例等。不要虚构键。如果默认值合适，则完全省略。

最简数据馈送示例（圆环图/饼图）：

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

7. 卡片浏览器（参考）

• 架构文档和实时示例：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