ui5-best-practices-smart-controls

UI5 智能控件最佳实践

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

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

何时加载各参考文档

触发条件	加载
正在处理或规划 sap.ui.comp.smartfield.SmartField	references/smart-field.md
正在处理或规划 sap.ui.comp.smartform.SmartForm	references/smart-form.md
正在处理或规划 sap.ui.comp.smartfilterbar.SmartFilterBar	references/smart-filter-bar.md
正在处理或规划 sap.ui.comp.smartchart.SmartChart	references/smart-chart.md
正在处理或规划 sap.ui.comp.navpopover.SmartLink	references/smart-link.md
正在处理或规划 sap.ui.comp.smartmultiinput.SmartMultiInput	references/smart-multi-input.md
正在处理或规划 sap.ui.comp.filterbar.FilterBar	references/filter-bar.md
正在处理或规划 sap.ui.comp.valuehelpdialog.ValueHelpDialog	references/value-help-dialog.md

输出任何内容前都要先加载。不要凭记忆处理。

---

核心规则

必须遵守

• 始终在智能控件上指定 entitySet，或确保控件继承的绑定上下文能够解析实体类型。
• 在 XML 中使用 ControlConfiguration 覆盖 SmartFilterBar 字段设置（控件类型、筛选器类型、索引）。运行时只能修改 visible、label 和 visibleInAdvancedArea。
• 使用正确的层级结构：SmartForm > Group > GroupElement > SmartField。切勿将 SmartField 直接放在 SmartForm 中。
• 以编程方式访问内部控件（例如 getInnerControl()、getChart()）前，先等待 initialise 事件。
• 与 OData V2 模型配合使用时，在绑定中使用 sap.ui.model.odata.type.* 类型。切勿在 OData V2 中使用 sap.ui.model.type.*。
• 在 SmartFilterBar 和 SmartChart 上设置 ariaLabelledBy，并引用可见标题，以满足无障碍要求。
• 提交数据前，在 SmartForm 上使用 check() 进行客户端必填字段验证。
• 使用 MCP 工具 get_api_reference 验证控件 API。使用 run_ui5_linter 验证代码。

禁止事项

• 不要将 Smart 控件用于 OData V4 服务。请改用 MDC 控件（sap.ui.mdc）。
• 不要在 SmartField 的 value 属性上设置自定义格式化器。SmartField 会根据元数据自行管理渲染。请使用注解来影响行为。
• 不要在 SmartField 上使用复合绑定语法（parts: [...]）。对于单位/货币字段，SmartField 会自行管理复合绑定。
• 初始化期间不要同步调用 getChart()。请使用 initialise 事件或 getChartAsync()。
• 不要直接修改 SmartChart 或 SmartTable 的内部控件（例如内部的 sap.chart.Chart）。请使用智能控件的公共 API。
• 不要对字段标签进行硬编码。请在 OData 元数据中使用 sap:label 或 @Common.Label 注解。
• 不要在 HTML 中使用内联样式或脚本（以符合 CSP 要求）。
• 不要使用全局访问（sap.ui.comp.smartfield.SmartField）。请使用 sap.ui.define 或 ES6 导入。

---

选择矩阵

控件	适用场景	不适用场景
SmartField	OData V2、单个属性的显示/编辑、根据 Edm 类型和注解自动渲染	OData V4、JSON 模型、需要自定义渲染、复合/多属性字段
SmartForm	OData V2、包含多个 SmartField 的实体编辑、根据注解自动生成标签	OData V4、复杂的自定义布局、非 OData 数据
SmartFilterBar	OData V2、由注解驱动的筛选器 UI、与 SmartTable/SmartChart 集成	OData V4（请使用 MDC FilterBar）、仅使用 JSON、纯自定义筛选逻辑
SmartChart	OData V2、由注解驱动的图表可视化、下钻、变体管理	OData V4（请使用 MDC Chart）、非分析型数据、自定义图表 JS
SmartLink	OData V2、语义对象导航、通过 FLP 进行跨应用导航	OData V4（请使用 MDC Link）、简单的静态链接、无法使用 FLP
SmartMultiInput	OData V2、多值输入（带令牌）、带范围的值帮助	OData V4、简单的单值输入、仅使用 JSON
FilterBar	不使用 OData 注解的手动筛选器 UI、在 ValueHelpDialog 内、自定义筛选器	使用注解的 OData V2（请使用 SmartFilterBar）、OData V4（请使用 MDC FilterBar）
ValueHelpDialog	通过表格和条件页签进行复杂的值选择、基于令牌的多选	简单下拉列表、单值选择、OData V4（请使用 MDC ValueHelp）

---

常见错误

症状	原因	解决方法
SmartField 在编辑模式下显示为纯文本	缺少绑定上下文或 entitySet 错误	验证 value="{PropertyName}" 和实体上下文解析。
SmartField 显示为 Input 而不是 DatePicker	属性缺少 sap:display-format="Date"	添加注解，或在 ControlConfiguration 中使用 controlType。
SmartForm 缺少标签	OData 元数据中未设置 sap:label 注解	为属性添加 sap:label，或在 GroupElement 上设置 label。
SmartFilterBar 的类型前置输入不起作用	缺少目标路径正确的 ValueList 注解	验证目标：{Namespace}.{EntityName}/{FieldName}。
SmartFilterBar 忽略默认值	在 initialise 之后动态设置 ControlConfiguration	在 XML 中静态设置值，或使用 setFilterData() API。
SmartChart 高度为 0／不可见	容器未提供明确的高度	在父容器上设置高度（例如，height="50vh"）。
SmartChart 缺少维度／度量	UI.Chart 注解错误或缺失	验证注解中的 MeasureAttributes 和 DimensionAttributes。
SmartLink 弹出框显示“No content available”	FLP 中没有语义对象的导航目标	验证 FLP 配置和用户授权。
SmartLink 显示为文本（不可点击）	属性上没有 SemanticObject 注解	为 OData 属性添加 @Common.SemanticObject 注解。
SmartMultiInput 令牌未持久化	缺少 ValueList 或绑定不正确	验证 ValueList 注解和导航属性绑定。

---

性能与无障碍访问

应避免的反模式

• 急切地请求所有值列表（使用延迟加载；默认情况下，值列表会按需加载）。
• 在后端查询开销较大的情况下，对 SmartFilterBar 使用 liveMode="true"（会导致频繁重新获取数据）。
• SmartForm 组嵌套过深（保持层级扁平：Form > Group > GroupElement）。
• 绕过 SmartChart API 直接修改内部图表（会破坏个性化设置和变式管理）。
• 当某些图表类型无关时未设置 ignoredChartTypes（会产生不必要的 UI 选项）。

无障碍访问检查清单

• 在 SmartFilterBar 上设置 ariaLabelledBy，引用可见标题。
• 在 SmartChart 上设置 ariaLabelledBy，引用可见标题。
• SmartForm 会通过注解自动将标签传递给 SmartField。
• 验证 SmartFilterBar“Adapt Filters”对话框的键盘导航是否正常。
• 使用屏幕阅读器测试 SmartLink 弹出框（必须播报导航目标）。