鸿蒙api是什么、在哪里获取、如何使用及调用

本文旨在围绕HarmonyOS（鸿蒙）的API，提供详细、具体的开发者视角信息，解答关于其本质、获取途径、使用方法以及相关维度的问题，避免探讨宏观意义和发展历程，直接深入技术细节。

HarmonyOS API 是什么？

HarmonyOS API，全称为HarmonyOS Application Programming Interface，是鸿蒙操作系统向应用程序开发者提供的接口集合。它允许开发者构建运行在各种鸿蒙设备上的应用程序和服务，调用系统功能、访问硬件能力、实现分布式特性等。

核心概念与层级

鸿蒙操作系统的API设计充分体现了其分布式架构和一次开发多端部署的理念。

OpenHarmony APIs

• HarmonyOS的API基于OpenHarmony项目。OpenHarmony是底座操作系统，鸿蒙操作系统是基于OpenHarmony的商业发行版。开发者通过HarmonyOS SDK使用的API，大部分源自OpenHarmony开放的接口能力。

API 层级

从抽象程度上，鸿蒙API可以分为几个层级，以便不同需求的开发者使用：

• 系统能力层API： 提供对底层系统服务和硬件能力的直接访问，如进程管理、内存管理、文件系统、网络协议栈等。这类API通常更为底层，需要开发者对系统有较深入的理解。
• 服务层API： 基于系统能力层构建，提供更高级的服务接口，如媒体播放、图形渲染、安全认证、用户界面（UI）组件等。这是大多数应用开发者日常接触最多的API层级。
• 应用框架层API： 这是最贴近应用开发的API，提供Ability Framework、UI框架（如ArkUI）等。开发者通过这些API构建应用的业务逻辑、界面以及不同Ability（原子化服务）之间的交互。

Ability Framework相关API

HarmonyOS的核心应用组织形式是Ability。与之相关的API是理解和使用鸿蒙的关键：

• FA (Feature Ability) API： 用于构建具有UI界面的前端Ability，通常用于与用户直接交互的场景。相关的API包括生命周期管理、界面跳转、参数传递等。
• PA (Particle Ability) API： 用于构建无UI界面的后台服务能力，可以在后台运行，或者被其他Ability调用。相关的API涉及服务的启动、停止、绑定、解绑定等。
• Service Ability API： PA的一种具体实现形式，专注于提供服务能力。
• Data Ability API： 提供结构化数据访问能力，允许应用对本地或分布式的数据进行增删改查（CRUD）操作，如访问联系人、媒体库、应用程序自身存储的数据等。

分布式能力集成API

鸿蒙最具特色的分布式能力是通过特定的API来实现的：

• 分布式任务调度（Distributed Task Schedule）API： 允许应用在不同设备上发现和调度运行其Ability或服务。
• 分布式数据管理（Distributed Data Management）API： 提供分布式数据库或KV Store能力，让数据可以在多设备间无感同步和访问。
• 分布式文件系统（Distributed File System）API： 允许应用跨设备访问文件。
• 分布式软总线（Distributed Soft Bus）API： 提供设备发现、网络连接、数据传输等底层分布式通信能力。

主要分类

根据功能领域，鸿蒙API可以细分为多个类别，每个类别包含一系列相关的接口和类：

• UI 开发 API： 包括ArkUI框架的组件、布局、事件处理、动画等，用于构建美观、响应式的用户界面。
• 连接与网络 API： 提供Wi-Fi、蓝牙、NFC、蜂窝网络、软总线等连接能力的控制和数据传输接口。
• 分布式 API： 前面已提及，涵盖分布式任务调度、数据管理、软总线等核心分布式功能。
• 系统管理与安全 API： 包括权限管理、账户管理、设备管理、安全认证、加密解密等与系统运行和安全相关的接口。
• 多媒体 API： 提供音频、视频的播放、录制、编辑以及相机访问等功能。
• 图形图像 API： 包括2D/3D图形绘制、图片处理、屏幕截图等。
• 传感器与硬件交互 API： 访问加速度计、陀螺仪、GPS、NFC等硬件传感器，以及控制震动、闪光灯等硬件功能。
• 数据管理 API： 除了分布式数据管理，还包括本地文件操作、preferences存储、SQLite数据库等。

在哪里获取 HarmonyOS API 信息？

获取鸿蒙API信息的主要渠道是官方提供的文档和开发工具。

官方文档

最权威和完整的API信息来源是HarmonyOS的官方开发者网站。

• 通常可以在类似“dev.harmonyos.com”这样的官方开发者门户找到。
• API Reference（API 参考）： 这是查找特定类、接口、方法详细说明的地方。包括方法的参数、返回值、抛出的异常、所需权限以及适用的API版本和设备类型等信息。
• 开发指南（Developer Guides）： 提供按功能组织的API使用教程、概念解释和最佳实践。
• 示例代码（Sample Code）： 官方提供的各类功能示例，是学习API如何具体应用的重要资源。

开发工具与SDK

开发者通过官方提供的集成开发环境（IDE）及其附带的SDK来使用API。

• DevEco Studio： 这是华为为HarmonyOS开发者提供的官方IDE。它集成了代码编辑、编译、调试、性能分析等功能。
• HarmonyOS SDK： 通过DevEco Studio的SDK Manager下载和管理。SDK包含了编译所需的库文件、头文件、模拟器镜像以及API文档的离线版本。开发者在项目中引用SDK中的库，才能调用HarmonyOS的API。
• SDK Manager： 在DevEco Studio中，可以通过SDK Manager选择安装不同API版本、不同设备类型的SDK，确保开发环境与目标设备兼容。

如何使用与调用 HarmonyOS API？

在HarmonyOS中调用API通常遵循标准的面向对象或组件化编程模式，具体取决于使用的开发语言（如ArkTS/TypeScript、Java、C++）和框架（如ArkUI）。

基本调用模式

API的调用方式可能涉及同步或异步操作。

• 同步调用： 调用立即执行并返回结果，阻塞当前线程直到操作完成。适用于简单、快速的操作。
• 异步调用： 调用后立即返回，实际操作在后台进行，结果通过回调函数、Promise或事件机制通知。适用于耗时操作（如网络请求、文件读写），避免阻塞UI线程，保持应用响应性。鸿蒙的许多API，特别是涉及跨进程、跨设备或耗时操作的API，都采用异步设计。

在应用中的集成流程

使用HarmonyOS API的一般步骤如下：

1. 创建HarmonyOS项目： 在DevEco Studio中创建一个新的HarmonyOS项目，选择合适的模板和语言。
2. 声明依赖或导入模块： 根据需要使用的API，可能需要在项目的配置文件（如build.gradle或module.json5）中添加依赖，或者在代码文件中使用import语句导入相应的模块、类或接口。
3. 获取实例（如果需要）： 有些API通过静态方法直接调用，有些则需要先获取系统服务的实例或创建对象。例如，获取系统服务通常使用getContext().getAbilityManager()或类似的模式。
4. 调用API方法： 根据API参考文档，调用具体的类或对象的成员方法，传递所需的参数。
5. 处理结果与错误： 对于同步调用，直接处理返回值和可能的异常；对于异步调用，则在回调函数或Promise的then/catch分支中处理结果和错误。
6. 处理权限： 如果API需要特定权限，必须在module.json5文件中声明，并在运行时按需向用户请求授权。

例如，使用ArkUI框架创建一个简单的文本组件并显示：

在ArkTS文件中：
import { Text } from ‘@ohos.arkui.basic’; // 导入Text组件API

@Entry
@Component
struct MyComponent {
build() {
Text(‘你好，HarmonyOS API！’) // 调用Text API创建一个文本组件
.fontSize(20) // 调用fontSize方法设置字体大小
.fontColor(Color.Blue); // 调用fontColor方法设置字体颜色
}
}

分布式API调用示例（概念性）

调用分布式API通常涉及设备发现和跨设备通信。例如，调用一个运行在其他设备上的Service Ability：

1. 使用分布式软总线API发现附近的HarmonyOS设备及其提供的服务。
2. 使用分布式任务调度API，通过指定目标设备的ID和Ability信息，发起一次远程Service Ability的调用请求。
3. 框架底层通过软总线建立连接，并执行远程过程调用（RPC）。
4. 调用结果通过回调函数或Promise返回给发起调用的Ability。

权限管理

为了保护用户数据和设备安全，许多敏感的HarmonyOS API都需要特定的权限。开发者必须遵循以下步骤：

• 声明权限： 在模块的配置文件module.json5中的requestPermissions字段下声明应用需要使用的权限。例如：{ "name": "ohos.permission.DISTRIBUTED_DATASYNC" }。
• 检查权限： 在调用需要危险权限的API之前，使用权限管理API（如abilityAccessCtrl.checkAccessToken()）检查应用是否已被授予该权限。
• 请求运行时权限： 对于危险权限（会影响用户隐私或设备安全的权限），应用需要在运行时向用户发起授权请求（如abilityAccessCtrl.requestPermissionsFromUser()）。只有用户授权后，才能成功调用相应的API。

HarmonyOS API 有多少不同维度？

除了按功能分类，HarmonyOS API还具有其他重要维度，影响开发者的使用方式。

API 版本

HarmonyOS API随着系统的演进而不断更新和发展。每个API版本（如API Version 9, 10等）可能引入新的API、修改现有API的行为或废弃旧的API。

• 兼容性： 应用在开发时会指定一个目标API版本（targetApiVersion）和一个最低兼容API版本（minAPIVersion）。应用只能在minAPIVersion及更高版本的设备上运行。
• 条件判断： 开发者在代码中可以使用const apiVersion = requireNapi('system.api').apiVersion;等方式获取当前设备的API版本，并根据版本进行条件判断，以兼容不同版本的系统，避免调用在低版本上不存在或行为不同的API。

设备类型适配

HarmonyOS支持多种设备形态（手机、平板、智慧屏、穿戴设备、车机等）。虽然API设计尽量保持一致性，但某些API可能只在特定类型的设备上可用，或者在不同设备上的行为或能力有所差异。

• 功能可用性： 例如，电话相关的API主要在手机上可用；触摸屏相关的API可能在无触摸屏的设备上无意义。
• 资源差异： 不同设备硬件能力不同，如内存、CPU、屏幕尺寸等，会影响API的性能表现。
• 设备能力检查： 开发者可以使用设备管理或特性能力相关的API来判断当前设备是否支持某个特定的功能或硬件特性，然后有选择地调用API。

API 级别（Level）

虽然前面提到了系统能力层、服务层、应用框架层，但API文档中也常提到一个API的“访问级别”或“可见性”，如Public API、System API、Internal API等。开发者通常只能调用 Public API，System API和Internal API通常是供系统内部或特权应用使用的，普通应用无法直接调用。

为什么选择使用 HarmonyOS API 进行开发？

对于开发者而言，选择使用HarmonyOS API进行开发的原因主要在于其提供的特定能力和开发优势：

• 原生访问鸿蒙特性： 直接使用HarmonyOS API能够最大化地利用操作系统的原生能力，包括性能优化、电源管理、硬件访问等，获得最佳的应用性能和用户体验。
• 无缝分布式能力： 通过分布式API，开发者可以轻松实现应用在多设备间的协同，例如任务接续、数据共享、设备间调用等，这是构建创新多设备体验的关键。
• 多设备开发效率： 虽然具体实现需要适配，但HarmonyOS的设计理念和部分框架（如ArkUI）旨在支持一套代码或相似的代码运行在多种设备上，这有助于提高开发效率和降低维护成本。
• 性能优势： 原生API通常比通过中间层或兼容层调用的性能更高。
• 访问独特硬件功能： 某些HarmonyOS设备可能拥有独特的硬件或传感器，只有通过其提供的原生API才能访问和利用这些能力。

总结

HarmonyOS API是连接应用与操作系统的桥梁，它们是构建鸿蒙应用和服务的基础。理解API的层级、分类、获取途径以及调用方式，掌握权限管理和版本适配等关键点，对于开发者而言至关重要。通过DevEco Studio和官方文档，开发者可以详细了解每个API的功能、参数和限制，进而构建出能够充分利用HarmonyOS强大功能的创新应用。