@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: The value of compatibleSdkVersion in the build-profile.json5 file under the project root directory is 20.

import { Available, SuppressWarnings, SuppressWarningsType } from '@kit.BasicServicesKit';
import wifiManager from '@ohos.wifiManager';
wifiManager.startScan();  // 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() {
  wifiManager.startScan(); // After the @SuppressWarnings annotation is used, the warning is suppressed.
}

@SuppressWarnings({rules: [SuppressWarningsType.COMPATIBILITY]})
class MyClass {
  wifiScanResult = wifiManager.startScan(); // After the @SuppressWarnings annotation is used, the warning is 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 /

Example

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

import { Available } from '@kit.BasicServicesKit';
import wifiManager from '@ohos.wifiManager';
wifiManager.startScan();  // 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
wifiManager.startScan(); // After the @SuppressWarnings annotation is used, the warning is 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.

System capability: SystemCapability.Base

Name	Value	Description
COMPATIBILITY	compatibility	Compatibility warning.
SYSCAP	syscap	Multi-device warning.