开发说明

API参考主要用于开发者查阅应用开发相关的各类API说明。为了方便开发者使用API文档，对文档描述中的常用字段进行说明。

版本说明

API参考采用两种方式标记组件或接口开始支持的版本号：

系统能力（SystemCapability，简称SysCap），指操作系统中每一个相对独立的特性。不同的设备对应不同的系统能力集，每个系统能力对应多个接口。开发者可根据系统能力来判断是否可以使用某接口。具体可参考系统能力SystemCapability使用指南。

文档在每一个接口描述中说明了接口的系统能力，如：系统能力：SystemCapability.xxx.xxx

将应用/元服务的重要信息或操作前置到服务卡片（简称“卡片”），可达到服务直达、减少跳转层级的体验效果。

对于支持在ArkTS卡片UI界面中使用的接口，将会添加“卡片能力”的标记，如：从API version 12开始，该接口支持在ArkTS卡片UI界面中使用。
如果接口不支持在ArkTS卡片UI界面中使用，则不做特殊说明。

默认情况下，应用只能访问有限的系统资源。但某些情况下，应用为了扩展功能的诉求，需要访问额外的系统或其他应用的数据（包括用户个人数据）、功能。具体可参考访问控制开发概述。

当调用接口访问这些资源时，需要申请对应的权限。申请方式可参考访问控制开发指导。

ArkTS API在使用过程中，可能会遇到错误。

在可能出现错误的各个接口处，开发者可参考文档中提供的错误码部分，了解对应接口可能出现的错误码ID及错误信息，并根据需要进行处理。

当前ArkTS API分为异步接口和同步接口，以下为对应的错误处理方式：

针对同步接口，错误统一通过异常形式抛出，开发者需要通过try-catch的方式处理可能抛出的异常。
针对异步接口，错误可能包括异常和rejection，开发者若使用await/async方式，需要通过try-catch的方式处理可能抛出的异常和rejection。
针对异步接口，错误可能包括异常和rejection，开发者若使用Promise方式，需要通过try-catch的方式处理同步抛出的异常（一般为401异常），并通过Promise的catch()方法或then()方法中的onrejected回调函数处理rejection。
针对callback形式的异步接口（不推荐使用），错误可能包括异常和回调返回的错误，开发者若使用callback方式，需要通过try-catch的方式处理同步抛出的异常（一般为401异常），并处理通过回调参数呈现的错误（即BusinessError对象）。

随着系统的演进发展，先后提供了两种应用模型，FA模型和Stage模型。

OpenHarmony中提供的接口，部分是仅供OEM厂商使用的system api，普通应用无法使用。

针对这种情况，在文档中会进行系统接口的声明：

普通应用即在HarmonyAppProvision配置文件中应用程序类型为hos_normal_app的应用。工程新建时，该字段默认为hos_normal_app。

随DevEco下载的SDK为public-SDK，不包括系统接口。如需使用系统接口，需要：

参考full-SDK替换指南将SDK替换为full-SDK。
参考HarmonyAppProvision配置文件的说明修改HarmonyAppProvision配置文件中的app-feature字段为hos_system_app（系统应用）。

废弃接口会使用上标“^deprecated”标注，表示该接口不再推荐使用。

废弃接口均会标注废弃起始版本，OpenHarmony未来可能移除已废弃接口，但在移除前会提前通知开发者。