@ohos.annotation (Annotation)

The annotation module defines the annotation types of OpenHarmony ArkTS APIs, such as the minimum available version of the lifecycle.

NOTE

• The initial APIs of this module are supported since API version 22. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

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

Available

@interface Available { minApiVersion: string = '' }

Annotates the minimum available version supported by an API. This annotation capability is provided by the system and can be used on classes, APIs, variables, types, modules, and enums. After the annotation is added to the source code, the compilation tool checks for potential compatibility issues. If the value of minApiVersion is greater than that of compatibleSDKVersion specified in build-profile.json5, a compatibility warning is reported.

Widget capability: This API can be used in ArkTS widgets since API version 22.

Atomic service API: This API can be used in atomic services since API version 22.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Base

Name	Type	Read-Only	Optional	Description
minApiVersion	string	No	No	Minimum available version, which consists of two parts: system type and version number. The system type can be omitted only when it is OpenHarmony, for example, 'OpenHarmony 20' or '20'.

Example

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

@Available({minApiVersion: 'OpenHarmony 22'}) // Annotates the minimum available version of the function.
function myFunc() {}

@Available({minApiVersion: '22'}) // Annotates the minimum available version of the class. The default system type is OpenHarmony.
class MyClass {}

// Not recommended: If the compatibleSdkVersion value set in the build-profile.json5 file in the project root directory is less than 22 and the myFunc method is directly called without version check, the compiler throws a warning at the call of myFunc, indicating that the method may fail to run on devices of earlier versions.
myFunc();

// Recommended approach 1: Use deviceInfo.sdkApiVersion to obtain the API version of system software for judgment, which can prevent exceptions on devices of earlier versions and eliminate compilation warnings.
if (deviceInfo.sdkApiVersion >= 22) {
  myFunc();
} else {
  // Select an approach for devices of earlier versions based on the service logic.
}

// Recommended approach 2: Annotate the start version information of @Available on the parent function (or class) where myFunc is called. If the new version number is not lower than the minimum available version of myFunc, the compilation warning is cleared.
@Available({minApiVersion: 'OpenHarmony 22'})
function myNewFunc() {
  myFunc();
}

SuppressWarnings²³⁺

@interface SuppressWarnings {

rules: Array<SuppressWarningsType>;

}

Suppresses warnings generated by APIs. This annotation capability is provided by the system and can be used on classes, functions, variables, types, and APIs. After the corresponding annotation is added to the source code, the compiler automatically suppresses the corresponding warning based on the preset rules.

Widget capability: This API can be used in ArkTS widgets since API version 23.

Atomic service API: This API can be used in atomic services since API version 23.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Base

Name	Type	Read-Only	Optional	Description
rules	Array<SuppressWarningsType>	No	No	Rules that support warning suppression.

Example

Prerequisites for compatibility warning suppression: The value of compatibleSdkVersion in the build-profile.json5 file under the project root directory is 20.

Prerequisites for permission warning suppression: No permission is requested under requestPermissions in the module.json5 file.

NOTE

When this annotation capability is used on a container node, warnings generated by its child nodes will be suppressed.

When a warning is matched by multiple suppression rules, only the latest suppression rule takes effect.

import { SuppressWarnings, SuppressWarningsType } from '@kit.BasicServicesKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';
import { systemDateTime } from '@kit.BasicServicesKit';
// Compatibility warning suppression
systemDateTime.getAutoTimeStatus();  // This API is available since API version 21. Directly calling this API will generate a compatibility warning.
// 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(); // After the @SuppressWarnings annotation is used, compatibility warnings are suppressed. When this capability is used on the myFunc() container node, compatibility warnings generated by its child nodes are also suppressed.
}

@SuppressWarnings({rules: [SuppressWarningsType.COMPATIBILITY]})
class MyClass {
  status = systemDateTime.getAutoTimeStatus(); // After the @SuppressWarnings annotation is used, compatibility warnings are suppressed.
}


// Permission warning suppression
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]}) // When there are two warning suppression rules, the latest rule takes effect. (Compatibility warnings are suppressed, but permission warnings still exist.)
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // // After the @SuppressWarnings annotation is used, compatibility warnings are suppressed, but permission warnings still exist.
}

@SuppressWarnings({rules: [SuppressWarningsType.PERMISSION]})
async function savePhotoToGallerySuppress(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg'); // After the @SuppressWarnings annotation is used, permission warnings are suppressed.
}

// @SuppressWarnings <SuppressWarningsType>

This capability supports quickly suppressing warnings with single-line comments. After the comment is added, the compiler automatically suppresses the corresponding warning based on the rules.

NOTE

Only the single-line comment is supported. Example: // @SuppressWarnings compatibility

Multi-line comment is not supported. Example: / @SuppressWarnings compatibility /

Warnings generated by the child nodes of the container node cannot be suppressed.

Example

Prerequisites for compatibility warning suppression: The value of compatibleSdkVersion in the build-profile.json5 file under the project root directory is 20.

Prerequisites for permission warning suppression: No permission is requested under requestPermissions in the module.json5 file.

import { systemDateTime } from '@kit.BasicServicesKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';
// Compatibility warning suppression
systemDateTime.getAutoTimeStatus();  // This API is available since API version 21. Directly calling this API will generate a compatibility warning.
// The 'startScan' API is supported since SDK version 21. However, the current compatible SDK version is 20.

// @SuppressWarnings compatibility
systemDateTime.getAutoTimeStatus();  // After the @SuppressWarnings annotation is used, compatibility warnings are suppressed.


// Permission warning suppression
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'); // After the annotation is used, warnings generated by the child nodes in the container cannot be suppressed.
  // 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'); // After the @SuppressWarnings annotation is used, permission warnings are suppressed.
}

SuppressWarningsType²³⁺

Defines the warning types that support suppression.

Widget capability: This API can be used in ArkTS widgets since API version 23.

Atomic service API: This API can be used in atomic services since API version 23.

Model restriction: This API can be used only in the stage model.

Since: 23

System capability: SystemCapability.Base

Name	Value	Description
COMPATIBILITY	compatibility	Compatibility warning.
SYSCAP	syscap	Multi-device warning.
PERMISSION	permission	Permission warning. Since: 26.0.0