之前，我们为各位开发者带来首份API差异报告，收到众多开发者的热捧。不少开发者表示希望看到一份完整的API差异说明，这次，它来了，就让我们来完整了解这份API差异报告吧。
首先是版本信息说明。目前发布HarmonyOS SDK 2.2.0.1(API Version 6 Beta 1)，相较上一版本HarmonyOS SDK 2.1.1.21(API Version 5)，SDK的变更主要体现在两个方面，分别是Java API变更(API 6 -> API 5)和JS API变更(API 6 -> API 5)。下面让我们正式进入差异报告解读。
一、JS API变更(API 6 -> API 5)
1. 新增提供功能子系统的API
相较于 JS API Version 5 ，JS API Version 6新增API如下表所示：
2. 变更差异
JS API Version 6，新增了较多原子化服务相关的接口，本文列举了部分新增接口。
更多详细的更新内容请访问官网链接：https://developer.harmonyos.com/cn/docs/documentation/doc-releases/apidiff-js-api-6-phone-component-0000001170697425
(1)JS UI框架子系统
新增了媒体、画布、栅格组件，如下表所示：
(2) 泛sensor子系统
新增了方向传感器及陀螺仪传感器的订阅、取消订阅接口，如下表所示：
(3)文件子系统
原文件存储“@system.file”接口，从API Version 6开始不再维护，推荐使用新接口’@ohos.fileio’进行文件管理，新增部分接口如下表：
(4)网络子系统
原数据请求’@system.fetch’，从API Version 6开始不再维护，推荐使用新接口’@ohos.net.http’发起http数据请求。新增部分接口如下表：
(5)分布式管理子系统
原数据存储’@system.storage’，从API Version 6开始不再维护，推荐使用新接口’@ohos.data.storage’进行数据管理。新增部分接口如下表：
二、 Java API变更(API 6 -> API 5)
1. 基础能力增强
(1)Intent新增MissionTop启动flag
Intent中新增了应用通过missionTop模式启动的字段FLAG_ABILITY_MISSION_TOP。如果启动ability的现有实例已经位于任务堆栈的顶部，则将重用该实例。否则，将创建新的ability实例。相关使用代码如下：
- Intent intent = new Intent();
- Operation operation = new Intent.OperationBuilder()
- .withDeviceId("")
- .withBundleName("com.demoapp")
- .withAbilityName("com.demoapp.XxxAbility")
- .withFlags(Intent. FLAG_ABILITY_MISSION_TOP)
- .build();
- intent.setOperation(operation);
- startAbility(intent);
(2)Intent新增文件打开相关Action和Entity
Class ohos.utils.IntentConstants中新增了Action和Entity，用于文件打开，如下所示：
- String ACTION_EDIT_DATA = "ability.intent.EDIT_DATA";
- String ACTION_SELECT = "ability.intent.SELECT";
- String ACTION_SEND_DATA = "ability.intent.SEND_DATA";
- String ACTION_SEND_MULTIPLE_DATA = "ability.intent.SEND_MULTIPLE_DATA";
- String ACTION_SCAN_MEDIA_FILE = "ability.intent.SCAN_MEDIA_FILE";
- String ACTION_VIEW_DATA = "ability.intent.VIEW_DATA";
- String ENTITY_BROWSABLE = "entity.system.browsable";
开发者需要打开文件相关应用时，在Intent中设置对应Action，代码如下所示：
- Intent intent = new Intent();
- Operation operation = new Intent.OperationBuilder()
- .withDeviceId(“”)
- .withAction(IntentConstants.ACTION_EDIT_DATA)
- .withEntities(IntentConstants.ENTITY_BROWSABLE)
- .build();
- intent.setOperation(operation);
- startAbility(intent);
(3)FA流转新增回调方法
Class ohos.aafwk.ability.continuation.IContinuationDeviceCallback 下新增了两个方法，onConnected ( ContinuationDeviceInfo deviceInfo )和onDisconnected ( String deviceId )。用于在FA主动流转时，在选择设备列表选择设备的回调中，新增设备名称参数，让应用区分流转的具体设备。其中ContinuationDeviceInfo中包含deviceId，deviceType，deviceName(新增)字段，开发者可以根据需要获取。
JAVA API 6 废弃原有回调方法onDeviceConnectDone(StringdeviceId, String deviceType),onDeviceDisconnectDone(StringdeviceId);
2. 卡片服务能力强化
(1)实现卡片服务克隆
由于没有卡片克隆功能，以往将卡片从旧设备迁移到新设备时，系统默认创建一个新的卡片，卡片原本携带的数据将不能克隆到新设备。本次更新，为卡片管理服务FMS适配了克隆接口，实现卡片的克隆。
(2)获取卡片状态
小艺建议是HarmonyOS2上一款主动推荐当下所需服务和应用的智慧化助手，在卡片智能推荐中，当卡片的状态未完成之前，可能会给消费者推荐一张空白卡片，这样对于消费者来说毫无意义。本次版本更新，Class ohos.aafwk.ability.Ability中新增了onAcquireFormState(Intent)方法，提供获取卡片状态功能，通过调用onAcquireFormState，询问卡片状态是否ready。只有卡片状态ready的情况下，才会显示在小艺建议推荐位。
(3)设置下一次卡片刷新时间
以往的卡片刷新，以30min作为一个基础值，按照30*N(N=1、2、3、4…)来设置更新频率。这无法满足某些应用如基金、航班类的卡片刷新需求，因为应用希望能在某些时间段动态的设置下次卡片的刷新时间。
本次版本更新中，Class ohos.aafwk.ability.Ability中新增了setFormNextRefreshTime(long,long)方法，设置下次卡片刷新时间，用于卡片动态定时刷新。设置的时间间隔最小是5min，每天最多设置50次。卡片管理服务根据提供方设置的时间更新定时器，定时器到点后，触发卡片应用的更新回调。
3. 新增沙盒文件分享
(1) FileAbility
ohos.data.file类中新增了FileAbility能力，提供应用沙盒文件分享的能力，用于沙盒内文件的分享。获取沙盒文件的流程如下所示：
class FileAbility中封装了获取文件信息的方法。
- public class FileAbility extends Ability {
- public FileAbility() {
- throw new RuntimeException("Stub!");
- }
- public void onStart(Intent intent) {
- throw new RuntimeException("Stub!");
- }
- public String getType(Uri uri) {
- throw new RuntimeException("Stub!");
- }
- public String[] getFileTypes(Uri uri, String mimeTypeFilter) {
- throw new RuntimeException("Stub!");
- }
- public FileDescriptor openFile(Uri uri, String mode) {
- throw new RuntimeException("Stub!");
- }
- public static Uri getUriViaFile(Context context, String Authority, File file) {
- throw new RuntimeException("Stub!");
- }
- public static File getFileViaUri(Uri uri) {
- throw new RuntimeException("Stub!");
- }
- }
(2)FileAbility开发步骤
Step 1 声明：
config.json中配置FileAbility类，指明ability类型为data, 权限配置 grantPermission : true。
- {
- "name": "ohos.data.file.FileAbility",
- "icon": "$media:icon",
- "description": "$string:myfileability_description",
- "type": "data",
- "visible": true,
- "uri": "dataability://ohos.data.file.FileAbility",
- "grantPermission": true
- }
Step 2 配置转换关系：
在hap包内resources/rawfile/ 目录下新建fileability.json的配置文件，用于配置File到Uri转换关系，同时指明哪些文件目录可以用来分享。配置转换关系后，路径会转换为对应name。fileability.json的配置文件如下所示：
- {
- "paths": [
- {
- "tag" : "fileability-external-path",
- "name" : "external_storage_root",
- "path" : "."
- },
- {
- "tag" : "fileability-files-path",
- "name" : "files-path",
- "path" : "."
- },
- {
- "tag" : "fileability-cache-path",
- "name" : "cache-path",
- "path" : "."
- },
- {
- "tag" : "fileability-external-files-path",
- "name" : "external_file_path",
- "path" : "."
- },
- {
- "tag" : "fileability-external-cache-path",
- "name" : "external_cache_path",
- "path" : "."
- },
- {
- "tag" : "fileability-root-path",
- "name" : "root-path",
- "path" : ""
- }
- ]
- }
Step 3沙盒文件分享：
发送侧调用getUriViaFile()
- File photoFile = new File(getFilesDir(), "test.jpg");
- Uri uri = FileAbility.getUriViaFile(getContext(), "/ohos.data.file.FileAbility ", photoFile)；
- Intent intent1 = new Intent();
- intent1.addFlags(0x00000001);
- intent1.addFlags(Intent.FLAG_NOT_OHOS_COMPONENT);
- intent1.setUriAndType(uri, "image/png");
- ElementName element = new ElementName("",
- "com.os1devp.intentapplication2", "com.os1devp.intentapplication2.MainAbility");
- intent1.setElement(element);
- startAbility(intent1);
接收侧调用DataAbility.open()获取文件句柄，处理沙盒文件：
- DataAbilityHelper helper = DataAbilityHelper.creator(getContext());
- Uri intentUri = intent.getOperation().getUri();
- FileDescriptor fs = helper.openFile(intentUri, "r");
4. 新增后台代理提醒
(1)原方案
如下图所示，在原来的方案中，通过Timer类实现定时提醒，需要在后台拉起或者唤醒应用，导致后台应用对系统资源的占用，影响前台应用的用户体验。
(2)改进方案
能不能实现一个后台代理提醒的功能?统一托管所有提醒业务，在应用冻结或者退出之后，仍可进行倒计时、日历、闹钟的系统提醒。现在，他来了!
如下图所示，开发者可以使用后台代理提醒的能力。通过后台代理实现定时提醒的同时，实现对后台应用的严格管控，减少后台应用被拉起或者唤醒次数，从而节省系统资源的开销。
(3)新增内容
如何实现后台代理功能?在本次API更新中， Package ohos.event.notification中新增了5大基础类，包括ReminderHelper、ReminderRequest、ReminderRequestTimer、ReminderRequestCalendar、ReminderRequestAlarm，基础类之间的关系如下图所示：
Class ReminderHelper中封装了代理通知基本操作，包括发布定时提醒类通知、注册提醒类需要使用的实例，取消指定的提醒类通知、取消当前应用设置的所有提醒。
Class ReminderRequest中封装了通知提醒的基本方法，包括获取设置的提醒时长、获取设置的延迟提醒次数、获取提醒的标题等。
Class ReminderRequestTimer，提醒类子类，用于闹钟类提醒。
Class ReminderRequestCalendar，提醒类子类，用于日历类提醒。
Class ReminderRequestAlarm，提醒类子类，用于倒计时提醒。
5. 新增支持continueAbility免安装拉起FA
在以往的跨端迁移过程中，需要两台设备都安装对应的FA，否则将无法实现跨端迁移。本次更新，增强了continueAbility接口功能，在指定deviceId情况下，如果检测到远端设备未安装FA，远端设备的框架会自动向HAG查询、下载并安装FA并将其拉起。
此外，IAbilityContinuation接口中还新增了异常回调函数及错误码，如下所示：
- public interface IAbilityContinuation {
- int ERR_ABILITY_QUERY_FAILED = -2;
- int ERR_CONTINUE_TIMEOUT = -8;
- int ERR_DEVICE_OFFLINE = -9;
- int ERR_INSTALL_FREE_NOT_SUPPORTED = -4;
- int ERR_NETWORK_UNAVAILABLE = -3;
- int ERR_PARAMETER_INVALID = -6;
- int ERR_PERMISSION_DENIED = -5;
- int ERR_REMOTE_DEVICE_INCOMPATIBLE = -7;
- int ERR_UNKNOWN = -1;
- int SUCCESS = 0;
- default void onFailedContinuation(int errorCode) {
- throw new RuntimeException("Stub!");
- }
- }
6. 其他新增功能
(1)StartAbility()
Class ohos.aafwk.ability.Ability中新增了带有回调参数的方法startAbility(Intent,IAbilityStartCallback), 作用是在对端Ability免安装成功拉起后，回调开发者。避免了Ability在对端设备启动过程中的盲目等待。
(2)getIconId()、getLabelId()
Class ohos.bundle.ApplicationInfo中新增了getIconId()、getLabelId()两个方法，用于在feature没有配置HomeAbility的情况下，获取到应用的label和icon。Label是应用的标签，icon为应用的图标。
