HarmonyOS API Version 六關鍵差異點解讀
之前，我們為各位開發者帶來首份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為應用的圖標。
