ui5-best-practices-mdc

UI5 MDC 控件最佳实践

在使用 OData V4 服务的自由风格应用中生成、审查或排查 MDC 控件代码时，请遵循这些指南。

**UI5 版本基线：**SAPUI5 1.136+ LTS。除非另有说明，文中提及的所有功能均从此版本开始提供。

何时加载各参考文档

触发条件	加载
使用或计划使用 sap.ui.mdc.FilterBar	references/mdc-filter-bar.md
使用或计划使用 sap.ui.mdc.Chart	references/mdc-chart.md
使用或计划使用 sap.ui.mdc.Field	references/mdc-field.md
使用或计划使用 sap.ui.mdc.FilterField	references/mdc-filter-field.md
使用或计划使用 sap.ui.mdc.ValueHelp	references/mdc-value-help.md
使用或计划使用 sap.ui.mdc.Link	references/mdc-link.md
使用或计划使用 sap.ui.mdc.MultiValueField	references/mdc-multi-value-field.md
将 MDC 控件与 JSON 模型（非 OData）搭配使用	references/mdc-json-delegates.md

生成任何输出前都要先加载。不要凭记忆作答。

---

Delegate 模式

所有 MDC 控件都使用 delegate，以将控件与特定数据源的逻辑解耦。应用开发者必须：

1. 在 XML 中指定 delegate：delegate="{name: 'my/app/delegate/MyDelegate', payload: {entitySet: 'Products'}}"
2. 实现继承相应基类 delegate 的模块
3. 重写关键方法（至少包括 fetchProperties）

OData V4 的基类 delegate：

控件	基类 Delegate
Table	sap/ui/mdc/odata/v4/TableDelegate
FilterBar	sap/ui/mdc/odata/v4/FilterBarDelegate
Chart	sap/ui/mdc/odata/v4/vizChart/Delegate
ValueHelp	sap/ui/mdc/ValueHelpDelegate
Link	sap/ui/mdc/LinkDelegate
MultiValueField	sap/ui/mdc/field/MultiValueFieldDelegate

**JSON 模型用法：**MDC 控件也支持 JSON 模型。直接扩展基类 delegate（sap/ui/mdc/TableDelegate、sap/ui/mdc/FilterBarDelegate），而不要扩展 OData V4 变体。详情请参阅 references/mdc-json-delegates.md。

PropertyInfo —— fetchProperties 返回的核心元数据格式：

{
    key: "propertyName",        // Unique identifier (required)
    label: "Display Label",     // User-visible label (required)
    dataType: "sap.ui.model.odata.v4.type.String"  // Data type (required)
}

---

核心规则

强制要求

• 每个 MDC 控件都必须包含 delegate 属性，并指向有效的模块路径。
• 在 delegate 中实现 fetchProperties，返回 PropertyInfo[]，且至少包含：key、label、dataType。
• 对于 OData V4 服务，扩展相应的 OData V4 基础 delegate（见上表）。对于 JSON/其他模型，直接扩展通用基础 delegate。
• 使用 p13nMode 启用个性化设置（Table：Column、Sort、Filter、Group；Chart：Item、Sort、Filter、Type；FilterBar：Item）。
• 使用 sap.ui.mdc.condition.Condition.createCondition() 以编程方式构建条件。
• OData V4 模型的 PropertyInfo dataType 字段使用 sap.ui.model.odata.v4.type.* 类型。JSON 模型使用 sap.ui.model.type.*。在 TypeMap 中注册类型。
• 为 FilterBar 和 Chart 设置 ariaLabelledBy，以确保无障碍访问。
• 优先使用 Fiori elements 构建块，而不是 freestyle MDC。仅在不适用 Fiori elements 时使用 MDC。
• 使用 get_api_reference MCP 工具验证控件 API。使用 run_ui5_linter 验证代码。

禁止事项

• 不要将 MDC 控件用于 OData V2 模型。应改用 Smart 控件（sap.ui.comp）。MDC 适用于 OData V4 和 JSON 模型。
• 不要直接访问内部控件（例如，内部的 sap.chart.Chart 或 sap.m.Table）。应使用 delegate 或 MDC 控件的公共 API。
• PropertyInfo 对象中不得省略 key（以前为 name，现已弃用）。
• 不要将条件对象手动构造为普通 JSON。始终使用 Condition.createCondition(operator, values)。
• 生产代码中不要省略 delegate 实现（内置默认值仅用于演示）。
• 不要使用内联样式或脚本（以符合 CSP 要求）。
• 不要使用全局访问（sap.ui.mdc.FilterBar）。应使用 sap.ui.define 或 ES6 导入。

---

选择矩阵

控件	适用场景	不适用场景
MDC FilterBar	OData V4 或 JSON 模型、由 delegate 驱动的筛选 UI、MDC Table/Chart	OData V2（使用 SmartFilterBar）、简单搜索栏
MDC Chart	OData V4、由 delegate 驱动的图表可视化、下钻	OData V2（使用 SmartChart）、简单静态图表、没有分析数据
MDC Field	OData V4 或 JSON、根据数据类型自动渲染的单个字段	OData V2（使用 SmartField）、需要纯自定义渲染
MDC FilterField	在 MDC FilterBar 中设置单个筛选条件	在 FilterBar 上下文之外独立进行筛选
MDC ValueHelp	OData V4 或 JSON、输入联想 + 对话框值选择	OData V2（使用 ValueHelpDialog）、无需搜索的简单下拉列表
MDC Link	OData V4、语义对象导航、由 delegate 驱动的链接目标	OData V2（使用 SmartLink）、简单静态链接
MDC MultiValueField	OData V4 或 JSON、通过 items 聚合输入多个值的令牌	OData V2（使用 SmartMultiInput）、简单的单值字段

---

常见错误

症状	原因	修复方法
"Delegate module could not be loaded"	delegate 属性中的路径错误	确认模块路径与项目中的实际文件位置一致。
图表未显示数据	fetchProperties 返回了错误的 PropertyInfo（缺少 groupable/aggregatable）	确保维度设置了 groupable: true，度量设置了 aggregatable: true。
FilterBar 字段未显示	PropertyInfo 缺失或设置了 hiddenFilter: true	检查 delegate 的 fetchProperties 是否返回了可见性设置正确的属性。
字段显示了错误的内部控件	PropertyInfo 中的 dataType 与预期格式不匹配	确认 dataType 使用完整限定类型名称（例如 sap.ui.model.odata.v4.type.String）。
个性化对话框为空	未设置 p13nMode 或 PropertyInfo 不完整	添加 p13nMode="Column,Sort,Filter"，并确保 PropertyInfo 包含 sortable/filterable 标志。
ValueHelp 未打开	ValueHelp 未关联到 Field，或缺少容器	确认 Field 上的 valueHelp 关联，以及 Popover/Dialog 容器已定义。
条件未应用到绑定	delegate 中未实现 updateBindingInfo	实现 updateBindingInfo，将筛选条件应用到 OData 绑定。
链接始终呈现为文本	fetchLinkType 返回 LinkType.Text 或执行失败	实现 fetchLinkType，使其返回 Popup 或 DirectLink 类型。

---

性能与无障碍

应避免的反模式

• 只需要部分 PropertyInfo 时，却急切加载全部 PropertyInfo（从 fetchProperties 返回最小集合）。
• 未实现 updateBindingInfo（条件永远不会应用到数据绑定）。
• 跳过 p13nMode 配置（个性化功能默认处于禁用状态）。
• 创建大型 delegate 模块（将复杂逻辑拆分到按需加载的辅助模块中）。
• 在 delegate 方法中使用同步操作（所有 delegate 方法都应返回 Promise）。

无障碍检查清单

• 在 FilterBar 上设置 ariaLabelledBy，引用一个可见标题。
• 在 Chart 上设置 ariaLabelledBy，引用一个可见标题。
• 确认个性化对话框支持键盘导航。
• 使用屏幕阅读器测试 ValueHelp 的输入提示和对话框。
• 确保所有 FilterField 都通过 PropertyInfo 的 label 设置了有意义的标签。