OpenHarmony API聲明文件探究
??https://harmonyos.51cto.com??
使用DevEco開發(fā)OpenHarmony應用的小伙伴是不是經常發(fā)現(xiàn)，明明OpenHarmony提供了接口支持，但是IDE卻沒有任何提示，甚至出現(xiàn)報錯，需要使用忽略大法@ts-ignore才能使開發(fā)流程不被堵塞。
那么跟著我一起來探究下OpenHarmony的聲明文件吧。
查看OpenHarmony API的聲明文件也是輔助了解OpenHarmony接口能力的好方法。(但API不一定是全部被實現(xiàn)的)
API聲明文件公共倉
公共倉地址：https://gitee.com/openharmony/interface_sdk-js/tree/master
選擇當前系統(tǒng)對應的版本，這里我的版本是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 庫也能定義靜態(tài)類型。所以TypeScript 提出了DefinitelyTyped。
DefinitelyTyped就是讓你把 “類型定義文件(*.d.ts)”，配合編輯器(或插件)，就能夠檢測到 JS 庫中的靜態(tài)類型。
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';
引入該模塊會發(fā)現(xiàn)報錯了。
查看錯誤：
我們去到SDK文件夾下檢查文件@ohos.resourceManager.d.ts，會發(fā)現(xiàn)末尾少寫了個大括號。
} //這里添上一個大括號
}
export default resmgr;
重啟DevEco，發(fā)現(xiàn)報錯不見了，那么我們繼續(xù)。
namespace
命名空間定義了標識符的可見范圍。
一般來說，如果我們需要在外部可以調用resmgr中的類和接口，則需要在類和接口添加export關鍵字。
但是resmgr在DevEco中反而找不到任何提示。推測對于DevEco，namespace內使用export是錯誤的。
我們將@ohos.resourceManager.d.ts中namespace中的export關鍵字全部去掉，重啟DevEco，現(xiàn)在提示都出來了。
我們可以看到一般在命名空間內會定義以下幾種類型。
// 枚舉
enum Direction {
}
// 類
class Configuration {
}
// 接口
interface ResourceManager {
}
// 方法
function getResourceManager(bundleName: string, callback: AsyncCallback<ResourceManager>);
函數(shù)重載
重載允許一個函數(shù)接受不同數(shù)量或類型的參數(shù)時，作出不同的處理。
在聲明文件中我們可以看到這樣的一個方法：
// 獲取當前應用的資源管理對象，使用callback形式返回ResourceManager對象。
export function getResourceManager(callback: AsyncCallback<ResourceManager>);
// 獲取當前應用的資源管理對象，使用Promise形式返回ResourceManager對象。
export function getResourceManager(): Promise<ResourceManager>;
實際上我們可以看到這兩個方法實現(xiàn)的是同一個能力，只是使用形式不同。
這里要特別說明一下在所有聲明文件當中隨處可見的兩個接口：
- 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;
通過之前使用測試，我們發(fā)現(xiàn)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開發(fā)則需要在[OpenHarmony SDK文件夾]\js\3.1.0.0\api\phone添加@ohos.display.d.ts文件
現(xiàn)在報錯沒有了，來使用API看看吧。
提示都出來啦~
打印一個分辨率在開發(fā)板上試試：
display.getDefaultDisplay().then(dis => {
console.log('[DEMO]width:' + dis.width)
console.log('[DEMO]height:' + dis.height)
})
??https://harmonyos.51cto.com??
