开发中为了兼容老版本设备，常需设置较低的compatibleSdkVersion，但这可能导致应用在低版本系统上因调用未受保护的新API而崩溃。

本文介绍三种API兼容性保护的方法：

• 通过apiAvailable接口兼容性保护

• 通过@Available注解标注最低适用版本

• 接口使用规格限制说明

一、apiAvailable接口

接口定义

apiAvailable(version: string | number): boolean;

检查指定的API版本在当前设备上是否可用，会根据输入格式和API版本范围自动选择合适的版本检查方法。

使用

场景一：API 26.0.0及以后的版本

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

getTestData(): void {
    if (deviceInfo.apiAvailable('26.0.0')) {
        // 调用26.0.0的API新接口
    } else {
        // 降级方案
    }
}

场景二：HarmonyOS专有接口（since M.S.F(N)）

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

getTestData(): void {
    // 方式1：不带括号中的版本
    if (deviceInfo.apiAvailable('5.0.1')) {
        // 调用API版本5.0.1(13)的API新接口
    } else {
        // 降级方案
    }
    
    // 方式2：带括号中的版本
    if (deviceInfo.apiAvailable('5.0.1(13)')) {
        // 调用API版本5.0.1(13)的API新接口
    } else {
        // 降级方案
    }
}

场景三：OpenHarmony底座接口（since N）

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

getTestData(): void {
    if (deviceInfo.apiAvailable(22)) {
        // 调用22的API新接口
    } else {
        // 降级方案
    }
}

接口使用限制

入参校验：

工程类型	支持的版本格式
OpenHarmony工程	• 整数：0 < X < 26 • 语义化版本：X >= 26，0 <= Y <= 99，0 <= Z <= 99
HarmonyOS工程	• 整数：0 < X < 26 • 语义化版本：X > 0，0 <= Y <= 99，0 <= Z <= 99（X<26时需确认版本支持）

使用限制：

限制	说明
仅支持if语句	不支持自定义封装，不支持三元表达式
必须纯字面量	不支持变量赋值形式传入版本参数
不支持逻辑符复合	不支持&&、||、!等逻辑运算符

反例：

// 不支持类赋值
const Bb = new BbClass();
if (deviceInfo.apiAvailable(Bb.version)) { } // 编译报错

// 不支持自定义封装
let result = deviceInfo.apiAvailable('26.0.0');
if (result) { }

// 不支持逻辑非
if (!deviceInfo.apiAvailable('26.0.0')) { }

// 不支持逻辑且
if (deviceInfo.apiAvailable('26.0.0') && deviceInfo.softwareModel == 'ALN-AL00') { }

// 不支持逻辑或
if (deviceInfo.apiAvailable('26.0.0') || deviceInfo.apiAvailable(24)) { }

// 不支持三元表达式
if (condition ? deviceInfo.apiAvailable('26.0.0') : deviceInfo.apiAvailable('27.0.0')) { }

说明

说明	内容
推荐使用	面向开发者相关的API版本接口（如apiAvailable）
需关注	设置中的API版本信息
不应使用	distributionOSVersion、displayVersion等面向消费者的版本号（与API版本无严格对应关系）
注意	deviceInfo.sdkApiVersion仅能用于OpenHarmony底座接口的兼容性保护

二、通过@Available注解标注最低适用版本

2.1 使用说明

参数：minApiVersion表示API最低引入版本

支持工程类型：

工程类型	支持的配置
HarmonyOS	'22'、'OpenHarmony 22'、'HarmonyOS 6.0.2'、'26.0.0'
OpenHarmony	'22'、'OpenHarmony 22'

适用位置：变量声明、类型声明（struct/class/interface/typeAlias/enum）、函数声明、命名空间声明、注解声明、struct/class/interface的成员

不可用位置：非声明式元素

2.2 校验逻辑

编译器依据项目配置的compatibleSdkVersion进行校验，若该版本低于被注解API的引入版本，将触发兼容性告警。

2.3 示例

HarmonyOS工程：

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

@Available({minApiVersion: 'OpenHarmony 22'})
class testClassA {}

@Available({minApiVersion: '22'})
class testClassB {}

@Available({minApiVersion: 'HarmonyOS 6.0.2'})
class testClassC {}

@Available({minApiVersion: '26.0.0'})
class testClassD {}

@Available({minApiVersion: '27.0.0'})
class testClassE {}

OpenHarmony工程：

@Available({minApiVersion: 'OpenHarmony 22'})
class testClassA {}

@Available({minApiVersion: '22'})
class testClassB {}

三、完整示例

3.1 提供方（标注API版本）

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

@Available({minApiVersion: '22'})
export function commonPrintUtil(): void {
    // 调用6.0.2(22)版本的新接口
}

3.2 调用方

import { Available, deviceInfo } from '@kit.BasicServicesKit';
import { commonPrintUtil } from '../../util';

// 不建议：直接调用，低版本设备可能崩溃
function businessFuncA(): void {
    commonPrintUtil(); // 编译告警
}

// 建议方式1：使用apiAvailable判断
function businessFuncB(): void {
    if (deviceInfo.apiAvailable('22')) {
        commonPrintUtil();
    } else {
        // 降级方案
    }
}

// 建议方式2：父级函数标注@Available
@Available({minApiVersion: '22'})
function businessFuncC(): void {
    commonPrintUtil();
}

使用建议

场景	推荐方式
运行时判断API是否可用	apiAvailable
标注API的最低适用版本	@Available
降级方案处理	apiAvailable + else分支