鸿蒙 升级targetSDKVersion的兼容性处理

升级targetSDKVersion可以让应用享受新版本特性，但如果不同时升级compatibleSdkVersion，就需要确保应用在低版本设备上仍能正常运行。

一、关系

compatibleSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion

升级说明

示例：

• 接口A在SDK版本5.0.2(14)产生行为变更并进行了版本隔离

• 应用升级targetSDKVersion ≥ 5.0.2(14)并适配了新版本行为

• compatibleSdkVersion仍保持设置为5.0.1(13)

要求：应用分发到低版本设备5.0.1(13)上时，需保证该应用在低版本设备能够兼容运行正常。

二、兼容性判断保护

HarmonyOS专有接口（since M.S.F(N)）

针对接口标记为since M.S.F(N)（SDK物理包中hms路径下所包含的接口），使用distributionOSApiVersion进行兼容性判断。

import { deviceInfo } from '@kit.BasicServicesKit';

// 针对HarmonyOS专有接口，即接口标记为since M.S.F(N)的接口
getTestData(): void {
    // 兼容性判断，50002是由新接口的since字段M*10000+F*100+S转换而来
    // 即5.0.2(14) → 5*10000 + 0*100 + 2 = 50002
    if (deviceInfo.distributionOSApiVersion >= 50002) {
        // 适配5.0.2(14)版本某API行为变更后的处理
        useNewApiBehavior();
    } else {
        // 兼容原有逻辑
        useOldApiBehavior();
    }
}

OpenHarmony底座接口（since N）

针对接口标记为since N（SDK物理包中openharmony路径下所包含的接口），使用sdkApiVersion进行兼容性判断。

import { deviceInfo } from '@kit.BasicServicesKit';

// 针对OpenHarmony底座公共接口，即接口标记为since N
getTestData(): void {
    // 增加兼容性判断，14即为API Level 14（对应5.0.2(14)）
    if (deviceInfo.sdkApiVersion >= 14) {
        // 适配5.0.2(14)版本某API行为变更后的处理
        useNewApiBehavior();
    } else {
        // 兼容原有逻辑
        useOldApiBehavior();
    }
}

三、接口对比

版本号转换示例

四、完整示例

import { deviceInfo } from '@kit.BasicServicesKit';

class ApiCompatibilityManager {
    // 判断HarmonyOS专有API是否可用
    static isHarmonyOSApiAvailable(major: number, minor: number, patch: number): boolean {
        const targetVersion = major * 10000 + minor * 100 + patch;
        return deviceInfo.distributionOSApiVersion >= targetVersion;
    }
    
    // 判断OpenHarmony底座API是否可用
    static isOpenHarmonyApiAvailable(apiLevel: number): boolean {
        return deviceInfo.sdkApiVersion >= apiLevel;
    }
    
    // 示例方法
    static doSomething(): void {
        // 检查5.0.2(14)版本的HarmonyOS专有API
        if (this.isHarmonyOSApiAvailable(5, 0, 2)) {
            // 使用新API
            console.info('使用5.0.2版本新API');
        } else {
            // 降级方案
            console.info('使用兼容旧API');
        }
    }
}