兼容性规则官网链接

以下部分描述了 SAP 在主要(major)、次要(minor)和补丁(patch)版本中可以更改的内容。 在使用 SAPUI5 或为 SAPUI5 开发应用程序、功能或控件时，请始终考虑这些规则。

作为应用开发人员，避免在 SAP UI5 代码中直接操作 CSS，例如：

domRef.className = "someCSSClass";

切勿使用或覆盖不属于 API 参考的“私有”函数。 私有函数通常（但不总是）以前面的“_”为前缀。 始终仔细检查 API 参考，那里没有列出私有函数。

API Evolution

除非另有说明，本节中的“API”一词指的是“公共 API”，意思是函数、类、命名空间、控件及其声明的属性、聚合等。

公共 API 的唯一定义是 API 参考即 API Reference，它包含在 SAPUI5 演示工具包中。 未提及的功能不是 API 的一部分。

以下规则适用于引入新 API 或对现有 API 进行不兼容的更改：

主要版本 (x.yy.zz 中的 x)：新的主要版本可以引入新的 API 或对现有 API 进行不兼容的更改。

次要版本 (x.yy.zz 中的 yy)：新的次要版本可以引入新的 API，但不得包含对任何 API 不兼容的更改。

补丁发布 (x.yy.zz中的 zz)：新补丁版本仅包含对现有实现的修复，但通常不包含新功能或不兼容的 API 更改。

Compatible Changes

对现有 API 的以下更改是兼容的，并且可以随时完成：

(1) 添加新的库、控件、类、属性、函数或命名空间

(2) 概括属性，即在继承层次结构中向上移动属性

(3) 向枚举类型添加新值； 这意味着在处理枚举属性时，始终准备接受新值，例如，在对枚举值做出反应时实现“默认”或“其他”路径。

Incompatible Changes

以下内容不是公共 API 的一部分，也就是说它们可能会在补丁和次要版本中发生变化：

开源库（参见第三方开源库）

日志消息

以下对现有 API 的更改不兼容，但可以在新的主要版本中完成：

重命名 API（库、命名空间、函数、属性、控件、事件等）

删除对参数的支持

删除对配置条目的支持

降低 API 的可见性； 这不会破坏 JavaScript 应用程序，但会改变契约

删除或重新排序 API 签名中的参数

减少可接受的值范围，例如，函数的参数

扩大返回值（或属性）的值范围。 例外：枚举

在模块之间移动 JavaScript 工件（命名空间、函数、类）

用前置条件检查替换断言

在继承层次结构中向下移动属性（等等）

更改枚举值的名称

更改默认值（属性、函数参数）

重命名或删除文件

Deprecation

如果可能且适当，我们会将旧工件标记为已弃用并创建新工件，而不是进行不兼容的更改。 相应 API 文档中的弃用注释，可能还有实现中的日志条目，解释了工件被弃用的原因和时间，并包含有关如何在不使用弃用功能的情况下实现相同结果的提示。

Third-Party Open Source Libraries

SAPUI5 包含并使用多个第三方开源库，例如 jQuery。 这些库也可由应用程序和/或自定义控件库使用，但本文档中描述的 SAPUI5 兼容性规则不适用于这些第三方库。

如果要使用 SAPUI5 中包含的第三方开源库，请注意以下限制：

SAP 决定提供所用库的哪些版本和模块。

即使在补丁版本中，SAP 也可以升级到所用库的更高版本。

如果我们更改为库的新默认版本，我们会记录可能对 SAPUI5 应用程序产生影响的发现（例如，请参阅从低于 1.20.0 的 SAPUI5 版本升级）。 确保在必要时调整您的代码！

出于安全等重要原因，SAPUI5 可以随时停止提供库。

第三方库按“原样”提供。 SAP 不执行或提供扩展、改编和支持。