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 不執行或提供擴充、改編和支援。