OpenHarmony API声明文件探究

系统 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)
})

 

​想了解更多内容,请访问:​

​51CTO和华为官方合作共建的鸿蒙技术社区​

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

责任编辑:jianghua 来源: 鸿蒙社区
相关推荐

2022-07-04 16:26:07

鸿蒙屏幕截图

2022-03-29 10:04:44

APIHarmony文件管理

2010-09-28 14:00:25

DOMAPI

2021-11-25 09:54:54

鸿蒙HarmonyOS应用

2022-06-21 08:12:17

K8sAPI对象Kubernetes

2009-07-09 17:47:35

Java Servle

2010-09-28 15:27:09

JavaScript

2022-08-23 16:07:02

ArkUI鸿蒙

2009-08-20 10:34:46

C#中声明API函数

2023-07-27 14:38:33

开源鸿蒙

2023-07-18 14:00:00

鸿蒙Sample案例

2022-09-02 15:17:04

ArkUI鸿蒙

2021-03-26 11:02:20

Python自然语言API

2009-10-12 12:54:58

VB.NET声明API

2022-08-08 19:46:26

ArkUI鸿蒙

2021-11-01 15:51:33

OpenHarmony工业操作系统

2022-09-26 15:16:03

ArkUITS

2017-07-04 08:59:15

APIDevSecOps

2023-09-13 18:32:58

TypeScript类型API

2021-09-16 15:08:08

鸿蒙HarmonyOS应用
点赞
收藏

51CTO技术栈公众号