目录

@ohos.annotation (Annotation)

This module defines the annotation types of HarmonyOS ArkTS APIs, such as the minimum available version of the lifecycle and suppressing warnings generated by APIs. It helps developers identify and manage API features such as compatibility and warning suppression. This module addresses issues such as version compatibility warnings, permission warnings, and multi-device adaptation warnings encountered during cross-version development and third-party SDK integration. Annotations are used to suppress unnecessary warnings, improving code maintainability and development efficiency.

  • 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 can be used on classes, interfaces, functions, 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. For example, HarmonyOS 6.0.2.

Example

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

@Available({minApiVersion: 'HarmonyOS 6.0.2'}) // Annotate the minimum available version of the function.
function myFunc() {}

@Available({minApiVersion: 'HarmonyOS 6.0.2'}) // Annotate the minimum available version of the class.
class MyClass {}

// Not recommended: If the compatibleSdkVersion value set in the build-profile.json5 file in the project root directory is less than 6.0.2 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.distributionOSApiVersion to obtain the API version of the distribution OS, which can prevent exceptions on devices using APIs of earlier versions and eliminate compilation warnings.
if (deviceInfo.distributionOSApiVersion >= 60002) {
  myFunc();
} else {
  // Select an approach for devices using APIs 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: 'HarmonyOS 6.0.2'})
function myNewFunc() {
  myFunc();
}

SuppressWarnings23+

@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 interfaces. After the corresponding annotation is added to the source code, the compiler automatically suppresses the corresponding warning based on the preset rules. This module can be used to temporarily ignore certain warnings in specific scenarios or prevent the compiler from generating interfering warnings. This helps you focus on key issues and improve development efficiency.

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. This parameter is used to specify the types of warnings to be suppressed. Multiple rules can be passed through an array to suppress multiple types of warnings. For details about the options, see SuppressWarningsType.

Example

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

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

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 suppression rule closest to the code generating the warning takes effect. When different types of warnings are matched by different suppression rules, each suppression rule takes effect independently.

import { SuppressWarnings, SuppressWarningsType, 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 'getAutoTimeStatus' 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 a comment is added above the code line triggering the warning, the compiler automatically suppresses the corresponding warning based on the rules. The identifiers in comments must match the enumerated values of SuppressWarningsType (for example, compatibility corresponds to COMPATIBILITY) and take effect only for the code line immediately following it.

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 of HarmonyOS is 6.0.0(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 'getAutoTimeStatus' 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 capability 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 capability is used, permission warnings are suppressed.
}

SuppressWarningsType23+

Defines the warning types that support suppression. Developers can selectively suppress compatibility warnings, multi-device warnings, and permission warnings as required. This helps ensure code quality, reduce unnecessary warning interference, and improve development experience.

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. This warning is generated when the start version of the API called is later than the compatible SDK version set for the project. It is recommended that this warning be suppressed when version check or compatibility processing has been performed. Suppressing this warning without proper handling may cause devices running earlier versions to malfunction.
SYSCAP syscap Multi-device warning. This warning is generated when the system capability obtained by calling the API is not supported on the target device.
PERMISSION permission

Permission warning. This warning is generated when an API that requires permissions is called but the corresponding permissions are not declared in the configuration file.

Since: 26.0.0