ui5-best-practices-tables

UI5 表格最佳实践

在自由样式应用中生成、审查或排查 UI5 表格代码时，请遵循这些指南。

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

何时加载各参考文档

触发条件	加载
正在使用或规划 sap.m.Table（ResponsiveTable）	references/sap-m-table.md
正在使用或规划 sap.ui.table.Table（GridTable）	references/grid-table.md
正在使用或规划 sap.ui.table.TreeTable	references/tree-table.md
正在使用或规划 sap.ui.comp.smarttable.SmartTable	references/smart-table.md
正在使用或规划 sap.ui.mdc.Table	references/mdc-table.md
为任何表格添加拖放功能	references/drag-and-drop.md
添加列个性化功能	references/personalization.md
选择单元格模板、对齐方式或数据类型绑定	references/cell-templates.md

在生成任何输出之前加载。不要凭记忆操作。

---

核心规则

必须遵守

• 编写任何代码之前，使用选择矩阵选择表格类型。
• sap.ui.table.* 使用 rows 聚合，sap.m.Table 使用 items 聚合。切勿混用。
• 使用 sap.m.p13n.Engine 实现个性化功能。切勿自行构建个性化对话框。
• 为每个表格设置 ariaLabelledBy，并引用表格标题控件。
• 根据数据类型对齐单元格内容：数字和日期右对齐（hAlign="End"），文本和链接左对齐。
• 使用合适的单元格模板：显示内容使用 sap.m.Text，数字使用 sap.m.ObjectNumber，导航使用 sap.m.Link。
• 当需要总数时，为 sap.ui.table.* 向后端请求 $count=true。
• 为 sap.ui.table.* 使用 rowMode 聚合（而非已弃用的 visibleRowCountMode 属性）（UI5 1.119+）。

禁止事项

• 不要使用全局变量。请使用 sap.ui.define AMD 模块或 ES6 导入。
• 不要在 sap.ui.table.* 单元格中启用文本换行——这会破坏虚拟化。
• 不要假定 sap.ui.export.Spreadsheet 可用。使用前先检测该库。
• 不要在移动优先场景中使用 sap.ui.table.Table。请使用 sap.m.Table。
• 对于需要虚拟化且行数达到 1000+ 的数据集，不要使用 sap.m.Table。
• 不要在一个 sap.ui.table.Table 单元格中放置多个可交互元素。
• 格式化器不要返回枚举对象。请返回字符串字面量或原始值。
• 不要对 ColumnListItem 的 highlight 使用格式化器。请直接进行数据绑定。
• 不要在未检查模型是否可用的情况下访问模型——这会导致“Cannot read properties of undefined”。
• 不要混用类型命名空间：切勿将 sap.ui.model.odata.type.* 用于 JSON 模型，也不要将 sap.ui.model.type.* 用于 OData。

OData V4 政策

对于 OData V4，优先使用 SAP Fiori elements 构建块，而不是自由样式表格。只有在 Fiori elements 不适用时才使用 sap.ui.mdc.Table。

---

选择矩阵

表格类型	适用场景	不适用场景
sap.m.Table	移动设备/响应式布局、弹出行为、JSON 模型、行数少于 100	行数达到 1000+、需要虚拟化、仅限桌面端、需要单元格选择
sap.ui.table.Table	桌面端、行数达到 1000+、虚拟化、固定列、密集数据	移动优先、需要弹出、文本换行、小型数据集
sap.ui.table.TreeTable	层级数据、展开/折叠、父子关系	扁平数据、移动优先、分组（非层级结构）
SmartTable	OData V2、注解、自动生成列、智能筛选	仅限 JSON、需要精确控制、OData V4
sap.ui.mdc.Table	OData V4 freestyle（排除使用 Fiori elements 时）、委托模式	仅限 JSON、简单应用、OData V2

数据集大小指南

行数	推荐表格	策略
< 100	sap.m.Table	简单绑定，growing 可选
100–1000	sap.ui.table.Table	虚拟化，threshold=100
1000+	sap.ui.table.Table	虚拟化，threshold=100–500，需要时使用 $count=true

---

常见错误

症状	原因	修复方法
未显示数据	绑定路径不正确或缺少模型	检查 bindRows/bindItems 路径和模型附加情况。
行无法滚动（sap.ui.table.*）	未请求计数	需要总数时，为 OData 设置 $count=true。
选择不起作用（sap.ui.table.*）	插件冲突	应用了选择插件时，不要调用表格选择 API；改用插件 API。
文本换行问题	在 sap.ui.table.* 中启用了换行	使用固定高度的内容，或切换到 sap.m.Table。
无法复制/粘贴	未附加插件或命名空间错误	附加正确的插件（参见“拖放”部分）。
个性化设置未持久化	未配置引擎	检查 sap.m.p13n.Engine 注册情况。
CopyProvider 错误	未定义 extractData	在插件上实现 extractData。
表格不可见	容器结构无效	使用有效的容器（参见“容器结构”）。
JSON 模型使用了 OData 类型	类型命名空间错误	使类型命名空间与模型匹配：JSON 使用 sap.ui.model.type.*，OData V2 使用 sap.ui.model.odata.type.*，OData V4 使用 sap.ui.model.odata.v4.type.*。
Excel 导出静默失败	未加载库或 extractData 无效	检测库，从 extractData 返回二维数组，并确保绑定了 dataSource。
“无可用数据”	绑定前未设置模型	在路由器初始化前，于 Component.init() 中设置模型。

---

容器结构

有效

结构	用例
View > Page > content > Table	标准页面
View > Page > content > Panel > Table	分组内容
View > Page > content > IconTabBar > items > IconTabFilter > Table	选项卡
View > SplitApp > detailPages > Page > Table	主从视图
View > Dialog > content > Table	模态框
View > Table	独立使用

无效（及原因）

结构	问题
Page > content > VBox > Table	VBox 需要显式设置高度，因此表格会变得不可见
Page > VBox > Table	VBox 不在 content 中，因此不会渲染表格
Page > content > FlexBox > Table	尺寸冲突，表格会折叠
Page > content > ScrollContainer > Table	双重滚动会导致虚拟化失效

---

性能与无障碍

应避免的反模式

• 手工制作个性化对话框（使用 sap.m.p13n.Engine）。
• 在 sap.ui.table.Table 单元格中使用文本换行。
• 在一个 GridTable 单元格中放置多个交互元素。
• 将 OData V2 SmartTable 与 V4 服务混用。
• 在单元格模板中深度嵌套。
• 未经负载测试便固定 threshold。
• 无条件使用 $count=true（仅在需要时请求计数）。

无障碍检查清单

• 为每个表格设置 ariaLabelledBy，并引用可见标题。
• 使用 sap.m.Text（而非原始文本节点）作为单元格模板。
• 对于 sap.ui.table.Table：测试键盘导航（Tab、方向键，以及用空格键/Enter 键进行选择）。
• 确认个性化对话框可通过键盘操作。
• 发布前使用屏幕阅读器（Windows 上的 NVDA/JAWS，macOS 上的 VoiceOver）进行测试。