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#系统能力与-api)：

*   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判断，动态禁用或替换功能。