OpenHarmony API聲明文件探究

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

使用DevEco開發(fā)OpenHarmony應(yīng)用的小伙伴是不是經(jīng)常發(fā)現(xiàn)，那么跟著我一起來探究下OpenHarmony的聲明文件吧。

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

使用DevEco開發(fā)OpenHarmony應(yīng)用的小伙伴是不是經(jīng)常發(fā)現(xiàn)，明明OpenHarmony提供了接口支持，但是IDE卻沒有任何提示，甚至出現(xiàn)報(bào)錯(cuò)，需要使用忽略大法@ts-ignore才能使開發(fā)流程不被堵塞。

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

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

API聲明文件公共倉

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

選擇當(dāng)前系統(tǒng)對(duì)應(yīng)的版本，這里我的版本是3.1beta。

進(jìn)入api文件夾即可看到聲明文件。

DevEco聲明文件

文件位置：

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

typescript聲明文件

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

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

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

export和import聲明會(huì)導(dǎo)出或?qū)肽繕?biāo)的所有含義。

如何讀聲明文件

我們來看@ohos.resourceManager.d.ts這個(gè)文件。

公共倉：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
同時(shí)可以結(jié)合HarmonyOS的文檔進(jìn)行閱讀：
https://developer.harmonyos.com/cn/docs/documentation/doc-references/js-apis-resource-manager-0000001200042191

declare

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

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

引入該模塊。

import resmgr from '@ohos.resourceManager';

引入該模塊會(huì)發(fā)現(xiàn)報(bào)錯(cuò)了。

查看錯(cuò)誤：

我們?nèi)サ絊DK文件夾下檢查文件@ohos.resourceManager.d.ts，會(huì)發(fā)現(xiàn)末尾少寫了個(gè)大括號(hào)。

  ...  
  } //這里添上一個(gè)大括號(hào)
}
export default resmgr;

重啟DevEco，發(fā)現(xiàn)報(bào)錯(cuò)不見了，那么我們繼續(xù)。

namespace

命名空間定義了標(biāo)識(shí)符的可見范圍。

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

但是resmgr在DevEco中反而找不到任何提示。推測(cè)對(duì)于DevEco，namespace內(nèi)使用export是錯(cuò)誤的。

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

我們可以看到一般在命名空間內(nèi)會(huì)定義以下幾種類型。

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

函數(shù)重載

重載允許一個(gè)函數(shù)接受不同數(shù)量或類型的參數(shù)時(shí)，作出不同的處理。

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

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

實(shí)際上我們可以看到這兩個(gè)方法實(shí)現(xiàn)的是同一個(gè)能力，只是使用形式不同。

這里要特別說明一下在所有聲明文件當(dāng)中隨處可見的兩個(gè)接口：

AsyncCallback
Promise

AsyncCallback接口定義

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

調(diào)用getResourceManager(callback: AsyncCallback)

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

調(diào)用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

在這個(gè)文件里定義了幾個(gè)常用接口

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文件

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

為DevEco添加聲明文件

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

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

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

導(dǎo)出一個(gè)命名空間display

declare namespace display { 
}
export default display;

通過之前使用測(cè)試，我們發(fā)現(xiàn)OpenHarmony只支持display的getDefaultDisplay方法，該方法使用Promise形式返回一個(gè)Display對(duì)象。

Display對(duì)象只支持兩個(gè)可讀屬性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;

保存，重新啟動(dòng)DevEco。

注意：
不要直接拷貝HarmonyOS SDK的@ohos.display.d.ts文件，因?yàn)樘郞penHarmony沒有支持了。
js開發(fā)則需要在[OpenHarmony SDK文件夾]\js\3.1.0.0\api\phone添加@ohos.display.d.ts文件

現(xiàn)在報(bào)錯(cuò)沒有了，來使用API看看吧。

提示都出來啦~

打印一個(gè)分辨率在開發(fā)板上試試：

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

??想了解更多內(nèi)容，請(qǐng)?jiān)L問：??

??51CTO和華為官方合作共建的鴻蒙技術(shù)社區(qū)??