@ohos.annotation (注解)

本模块定义了OpenHarmony ArkTS API的注解类型，如生命周期最小可用版本等。

说明：

• 本模块首批接口从 API version 22 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { Available, SuppressWarnings, SuppressWarningsType } from '@kit.BasicServicesKit';

Available

@interface Available { minApiVersion: string = '' }

系统提供的API注解能力，可用于标记API支持的最低可用版本。此注解可以标注在类、接口、变量、类型、模块、枚举上。在源码定义处添加注解后，编译工具会在使用处检查潜在的兼容性问题。当minApiVersion大于build-profile.json5中指定的compatibleSDKVersion字段，会生成兼容性警告。

卡片能力： 从API version 22开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Base

名称	类型	只读	可选	说明
minApiVersion	string	否	否	minApiVersion用于标识最低可用版本，由两部分组成：系统类型+版本号。仅当系统类型为OpenHarmony时可省略系统类型。例如：'OpenHarmony 20'，'20'。

示例：

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

@Available({minApiVersion: 'OpenHarmony 22'}) // 标记函数最低可用版本
function myFunc() {}

@Available({minApiVersion: '22'}) // 标记类最低可用版本，系统类型默认值为 OpenHarmony
class MyClass {}

// 不建议写法：如果工程根目录下build-profile.json5文件设置的compatibleSdkVersion值小于 22，直接调用myFunc方法且没有做版本判断处理，编译器会在myFunc方法调用处抛出告警，提示该方法可能在低版本设备上运行失败
myFunc();

// 建议写法1：使用deviceInfo.sdkApiVersion获取系统软件API版本进行判断，可以避免低版本设备运行异常，消除编译告警
if (deviceInfo.sdkApiVersion >= 22) {
  myFunc();
} else {
  // 根据业务逻辑选择低版本可用方法
}

// 建议写法2：在myFunc调用处的父级函数（或类）上，标记@Available起始版本信息，当新标记的版本号不低于 myFunc的最低可用版本, 消除编译告警
@Available({minApiVersion: 'OpenHarmony 22'})
function myNewFunc() {
  myFunc();
}

SuppressWarnings²³⁺

@interface SuppressWarnings {

rules: Array<SuppressWarningsType>;

}

系统提供的API告警屏蔽功能，允许开发者通过注解的方式来抑制API调用时产生的告警。该功能可应用于类、函数、变量、类型、接口等API元素上。在源码中添加相应标注后，编译器会根据预设规则自动屏蔽对应的告警信息。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Base

名称	类型	只读	可选	说明
rules	Array<SuppressWarningsType>	否	否	支持告警消除的规则集合

注解使用示例：

兼容性告警消除预置条件：OpenHarmony工程根目录下，build-profile.json5文件设置的compatibleSdkVersion值为20。

权限告警消除预置条件：module.json5配置文件的requestPermissions标签中没有申请权限。

说明：

用于容器节点时，会屏蔽节点下子节点产生的告警

重复规则屏蔽时，仅生效最近的符合规则的屏蔽类型

import { SuppressWarnings, SuppressWarningsType } from '@kit.BasicServicesKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';
import { systemDateTime } from '@kit.BasicServicesKit';
// 兼容性告警消除部分
systemDateTime.getAutoTimeStatus();  // 该接口起始版本为21，直接调用会生成兼容性告警。
// The 'startScan' API is supported since SDK version 21. However, the current compatible SDK version is 20.

@SuppressWarnings({rules: [SuppressWarningsType.COMPATIBILITY]})
function myFunc() {
  systemDateTime.getAutoTimeStatus(); // 使用@SuppressWarnings注解后，兼容性告警被抑制。用于myFunc()容器节点时，子节点的兼容性告警也被抑制。
}

@SuppressWarnings({rules: [SuppressWarningsType.COMPATIBILITY]})
class MyClass {
  status = systemDateTime.getAutoTimeStatus(); // 使用@SuppressWarnings注解后，兼容性告警被抑制。
}


// 权限告警消除部分
async function savePhotoToGallery(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg');
  // To use this API, you need to apply for the permissions: ohos.permission.WRITE_IMAGEVIDEO
}

@SuppressWarnings({rules: [SuppressWarningsType.PERMISSION]})
async function savePhotoToGallerySuppressCompatibility(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  @SuppressWarnings({rules: [SuppressWarningsType.COMPATIBILITY]}) // 如果同时存在两种屏蔽内容，仅生效最近的抑制类型。（兼容性告警被抑制，权限告警仍然存在）
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // 使用@SuppressWarnings注解后，兼容性告警被抑制，权限告警仍然存在。
}

@SuppressWarnings({rules: [SuppressWarningsType.PERMISSION]})
async function savePhotoToGallerySuppress(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // 使用@SuppressWarnings注解后，权限告警被抑制。
}

// @SuppressWarnings <SuppressWarningsType>

本功能支持以单行注释形式快速抑制告警。添加注释后，编译器将根据规则自动屏蔽对应的告警信息。

说明：

仅支持单行注释(//)格式，示例：// @SuppressWarnings compatibility

不支持多行注释(/**/)格式，示例：/* @SuppressWarnings compatibility */

不支持屏蔽容器节点下的子节点

注释使用示例：

兼容性告警消除预置条件：OpenHarmony工程根目录下，build-profile.json5文件设置的compatibleSdkVersion值为20。

权限告警消除预置条件：module.json5配置文件的requestPermissions标签中没有申请权限。

import { systemDateTime } from '@kit.BasicServicesKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';
// 兼容性告警消除部分
systemDateTime.getAutoTimeStatus();  // 该接口起始版本为21，直接调用会生成兼容性告警。
// The 'startScan' API is supported since SDK version 21. However, the current compatible SDK version is 20.

// @SuppressWarnings compatibility
systemDateTime.getAutoTimeStatus();  // 使用@SuppressWarnings注释后，兼容性告警被抑制。


// 权限告警消除部分
async function savePhotoToGallery(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg');
  // To use this API, you need to apply for the permissions: ohos.permission.WRITE_IMAGEVIDEO
}
// @SuppressWarnings permission
async function savePhotoToGallerySuppressNoUse(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // 使用注释后，容器内子节点的告警不支持消除，仍会产生告警
  // To use this API, you need to apply for the permissions: ohos.permission.WRITE_IMAGEVIDEO
}

async function savePhotoToGallerySuppress(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  // @SuppressWarnings permission
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // 使用@SuppressWarnings注释后，权限告警被抑制。
}

SuppressWarningsType²³⁺

支持消除告警的规则。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 23

系统能力： SystemCapability.Base

名称	值	说明
COMPATIBILITY	compatibility	支持消除兼容性告警。
SYSCAP	syscap	支持消除多设备告警。
PERMISSION	permission	支持消除权限告警。 起始版本： 26.0.0