# API的版本兼容性适配和多设备兼容性适配

## 问题现象

在HarmonyOS应用开发中，若需将手机、平板、电脑、手表等多设备形态打包至同一APP包并上架审核：

1. **SDK版本限制**：同一APP包内仅支持一个targetSdkVersion和compatibleSdkVersion，直接降低compatibleSdkVersion可能导致高版本API（如hdsEffect）在低版本设备上闪退。
2. **设备能力差异**：手表等设备可能不支持特定API（如hdsEffect），导致功能无法使用。

## 背景知识

1.[应用和设备系统兼容性原则](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-intro#section144051257332)：

* 基于老版本HarmonyOS SDK开发的应用，在上架华为应用市场后，默认可分发到新版本的HarmonyOS设备，并正常运行。例外情况：API因体验优化或安全等因素，可能会发生行为变更，并对已上架应用产生影响，针对这部分变更会专门在版本说明中详细阐述，请开发者在升级API版本时候，关注版本说明。
* 针对基于新版本HarmonyOS SDK开发的应用，使用了新版本API，开发者对这些新版本API进行兼容性判断保护后，应用在老HarmonyOS设备上使用新API部分功能降级，并运行正常。

2.[系统能力与API](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/syscap)：

* SysCap，全称SystemCapability，即系统能力，指操作系统中每一个相对独立的特性，如蓝牙，WIFI，NFC，摄像头等，都是系统能力之一。
* HarmonyOS定义了API接口canIUse[判断API是否可以使用](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/syscap#使用能力查询接口判断api是否可用)，帮助开发者来判断该设备是否支持某个特定的SysCap。

## 解决方案

1. **API兼容性适配，解决低版本闪退。**
   * **版本判断机制** ：

     HarmonyOS设备独有特性接口，即接口标记为since M.S.F(N)，通过[distributionOSApiVersion](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-device-info#常量)，如6.0.0(20)对应60000。

     OpenHarmony底座接口，即接口标记为since N，通过[sdkApiVersion](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-device-info#常量)判断设备系统版本，动态启用或禁用高版本API。
     * **高版本设备**：直接调用hdsEffect等新API。
     * **低版本设备**：提供降级方案（如隐藏功能入口或替代实现）。
   * **关键逻辑** ：
     * 在代码中嵌入版本判断逻辑，确保仅在支持的设备上执行高版本API。
     * 对未支持设备，通过日志记录或明确提示用户功能限制。
2. **系统能力SysCap检查，检查设备能力差异。**
   * **能力验证** ：

     使用[canIUse](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-syscap#caniuse)接口验证设备是否支持特定系统能力。
     * **支持能力**：调用如hdsEffect实现高级功能。
     * **不支持能力**：禁用相关功能或提供基础替代方案。
   * **设备类型适配** ：
     * **手表设备**：通过deviceType字段wearable直接禁用不支持的API。
     * **其他设备**：根据能力验证结果动态调整功能可用性。
3. **动态资源管理，将不同版本资源分别保存。**
   * **资源目录分层** ：
     * **默认资源**：适用于所有设备（resources/base/）。
     * **高版本资源**：仅在6.0.0+设备加载（resources/v6/）。
     * **低版本资源**：兼容5.0.5及以下设备（resources/v5/）。
   * **运行时加载策略** ：

     根据设备版本动态选择资源路径，确保UI和功能适配性。

**4. 分发限制和运行降级。**

* **分发限制配置** ：

  在build-profile.json5中通过deviceType字段，如["phone","tablet","2in1"]限制功能仅在支持的设备类型上启用。
* **运行时降级方案** ：
  * **功能隐藏**：通过能力验证或设备类型判断，动态隐藏不支持的功能入口。
  * **替代实现**：提供低版本兼容的UI或逻辑（如禁用动画效果）。
  * **用户提示**：对不支持设备显示明确提示（如"当前设备不支持高级动画效果"）。

## 常见FAQ

Q：如何查询hdsEffect的起始版本？

A：在API文档中查看hdsEffect的"起始版本"字段。

Q：如何计算distributionOSApiVersion？

A：公式为M*10000+S*100+F，如6.0.0(20)→6*10000+0*100+0=60000。

Q：如何处理手表等设备不支持的API？

A：结合canIUse和deviceType判断，动态禁用或替换功能。