SAP UI5 的 兼容性规则 Compatibility Rules

兼容性规则官网链接
以下部分描述了 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 不执行或提供扩展、改编和支持。

你可能感兴趣的:(SAP UI5 的 兼容性规则 Compatibility Rules)