OpenHarmony API聲明文件探究

作者：拓維信息田怡婧 2022-02-25 15:08:06

系統 OpenHarmony

使用DevEco開發OpenHarmony應用的小伙伴是不是經常發現，那么跟著我一起來探究下OpenHarmony的聲明文件吧。

??想了解更多內容，請訪問：??

??51CTO和華為官方合作共建的鴻蒙技術社區??

??https://harmonyos.51cto.com??

使用DevEco開發OpenHarmony應用的小伙伴是不是經常發現，明明OpenHarmony提供了接口支持，但是IDE卻沒有任何提示，甚至出現報錯，需要使用忽略大法@ts-ignore才能使開發流程不被堵塞。

那么跟著我一起來探究下OpenHarmony的聲明文件吧。

查看OpenHarmony API的聲明文件也是輔助了解OpenHarmony接口能力的好方法。(但API不一定是全部被實現的)

API聲明文件公共倉

公共倉地址：https://gitee.com/openharmony/interface_sdk-js/tree/master

選擇當前系統對應的版本，這里我的版本是3.1beta。

進入api文件夾即可看到聲明文件。

DevEco聲明文件

文件位置：

[OpenHarmony SDK文件夾]\ets\3.1.0.0\api\common
[OpenHarmony SDK文件夾]\js\3.1.0.0\api\phone

typescript聲明文件

聲明文件以 .d.ts 結尾，里面主要用來定義類型。

TypeScript 身為 JavaScript 的超集，自然需要考慮到如何讓 JS 庫也能定義靜態類型。所以TypeScript 提出了DefinitelyTyped。

DefinitelyTyped就是讓你把 “類型定義文件(*.d.ts)”，配合編輯器(或插件)，就能夠檢測到 JS 庫中的靜態類型。

export和import聲明會導出或導入目標的所有含義。

如何讀聲明文件

我們來看@ohos.resourceManager.d.ts這個文件。

公共倉：https://gitee.com/openharmony/interface_sdk-js/blob/OpenHarmony-3.1-Beta/api/@ohos.resourceManager.d.ts
本地：[OpenHarmony SDK文件夾]\ets\3.1.0.0\api\common@ohos.resourceManager.d.ts
同時可以結合HarmonyOS的文檔進行閱讀：
https://developer.harmonyos.com/cn/docs/documentation/doc-references/js-apis-resource-manager-0000001200042191

declare

聲明變量使用關鍵字declare來表示聲明其后面的全局變量的類型。

declare namespace resmgr {
  ...
}
export default resmgr;

引入該模塊。

import resmgr from '@ohos.resourceManager';

引入該模塊會發現報錯了。

查看錯誤：

我們去到SDK文件夾下檢查文件@ohos.resourceManager.d.ts，會發現末尾少寫了個大括號。

  ...  
  } //這里添上一個大括號
}
export default resmgr;

重啟DevEco，發現報錯不見了，那么我們繼續。

namespace

命名空間定義了標識符的可見范圍。

一般來說，如果我們需要在外部可以調用resmgr中的類和接口，則需要在類和接口添加export關鍵字。

但是resmgr在DevEco中反而找不到任何提示。推測對于DevEco，namespace內使用export是錯誤的。

我們將@ohos.resourceManager.d.ts中namespace中的export關鍵字全部去掉，重啟DevEco，現在提示都出來了。

我們可以看到一般在命名空間內會定義以下幾種類型。

// 枚舉
enum Direction {
    ...
}
// 類
class Configuration {
    ...
}
// 接口
interface ResourceManager {
    ...
}
// 方法
function getResourceManager(bundleName: string, callback: AsyncCallback<ResourceManager>);

函數重載

重載允許一個函數接受不同數量或類型的參數時，作出不同的處理。

在聲明文件中我們可以看到這樣的一個方法：

// 獲取當前應用的資源管理對象，使用callback形式返回ResourceManager對象。
export function getResourceManager(callback: AsyncCallback<ResourceManager>);    
// 獲取當前應用的資源管理對象，使用Promise形式返回ResourceManager對象。
export function getResourceManager(): Promise<ResourceManager>;

實際上我們可以看到這兩個方法實現的是同一個能力，只是使用形式不同。

這里要特別說明一下在所有聲明文件當中隨處可見的兩個接口：

AsyncCallback
Promise

AsyncCallback接口定義

interface AsyncCallback<T> {
    (err: Error, data: T): void;
}

調用getResourceManager(callback: AsyncCallback)

resourceManager.getResourceManager((error, mgr) => {
    //成功時， error返回undefined
    if (error != null) { 
        console.log("error occurs" + error);
        return; 
    }  
    console.log("mgr ready")
});

調用getResourceManager(): Promise

resourceManager.getResourceManager().then(mgr => {
    console.log("mgr ready")
}).catch(error => {
    console.log("error occurs" + error);
});
// 或者
try{
  let mgr = await resmgr.getResourceManager()
}catch(error){
  console.log("error occurs" + error);
}

basic.d.ts

在這個文件里定義了幾個常用接口

export interface Callback<T> {
    (data: T): void;
} 
export interface ErrorCallback<T extends Error = BusinessError> {
    (err: T): void;
}
export interface AsyncCallback<T> {
    (err: BusinessError, data: T): void;
}
export interface BusinessError extends Error {
    code: number;
}

我們來看@ohos.bundle.d.ts文件

// 導入basic聲明接口
import { AsyncCallback, Callback } from './basic';
...
// 聲明方法
function getBundleInfo(bundleName: string, bundleFlags: number, callback: AsyncCallback<BundleInfo>): void;

為DevEco添加聲明文件

OpenHarmony支持顯示設備屬性@ohos.display，但是卻沒有為display添加聲明文件。

那么我們自己來寫一個@ohos.display.d.ts文件。

首先在[OpenHarmony SDK文件夾]\ets\3.1.0.0\api\common新建文件@ohos.display.d.ts。

導出一個命名空間display

declare namespace display { 
}
export default display;

通過之前使用測試，我們發現OpenHarmony只支持display的getDefaultDisplay方法，該方法使用Promise形式返回一個Display對象。

Display對象只支持兩個可讀屬性width和height。

interface Display {
   readonly width: number;
   readonly height: number;
}

getDefaultDisplay方法的定義

function getDefaultDisplay(): Promise<Display>;

那么完整的@ohos.display.d.ts

declare namespace display {
  function getDefaultDisplay(): Promise<Display>;
  interface Display {
    readonly width: number;
    readonly height: number;
  }
}
export default display;

保存，重新啟動DevEco。

注意：
不要直接拷貝HarmonyOS SDK的@ohos.display.d.ts文件，因為太多OpenHarmony沒有支持了。
js開發則需要在[OpenHarmony SDK文件夾]\js\3.1.0.0\api\phone添加@ohos.display.d.ts文件

現在報錯沒有了，來使用API看看吧。

提示都出來啦~

打印一個分辨率在開發板上試試：

display.getDefaultDisplay().then(dis => {
  console.log('[DEMO]width:' + dis.width)
  console.log('[DEMO]height:' + dis.height)
})