开发中为了兼容老版本设备常需设置较低的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 Nimport { deviceInfo } from kit.BasicServicesKit; getTestData(): void { if (deviceInfo.apiAvailable(22)) { // 调用22的API新接口 } else { // 降级方案 } }接口使用限制入参校验工程类型支持的版本格式OpenHarmony工程• 整数0 X 26• 语义化版本X 260 Y 990 Z 99HarmonyOS工程• 整数0 X 26• 语义化版本X 00 Y 990 Z 99X26时需确认版本支持使用限制限制说明仅支持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最低引入版本支持工程类型工程类型支持的配置HarmonyOS22、OpenHarmony 22、HarmonyOS 6.0.2、26.0.0OpenHarmony22、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分支