【如此之白】OpenHarmony API声明文件探究原创精华

如此之白

发布于 2022-2-21 16:41

浏览

12收藏

使用DevEco开发OpenHarmony应用的小伙伴是不是经常发现，明明OpenHarmony提供了接口支持，但是IDE却没有任何提示，甚至出现报错，需要使用忽略大法@ts-ignore才能使开发流程不被堵塞。

那么跟着我一起来探究下OpenHarmony的声明文件吧。

查看OpenHarmony API的声明文件也是辅助了解OpenHarmony接口能力的好方法。（但API不一定是全部被实现的）

API声明文件公共仓

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

选择当前系统对应的版本，这里我的版本是3.1beta。

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

进入api文件夹即可看到声明文件。

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

DevEco声明文件

文件位置：

[OpenHarmony SDK文件夹]\ets\3.1.0.0\api\common

[OpenHarmony SDK文件夹]\js\3.1.0.0\api\phone

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

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;
1.
2.
3.
4.
5.

引入该模块。

import resmgr from '@ohos.resourceManager';
1.

引入该模块会发现报错了。

查看错误：

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

我们去到SDK文件夹下检查文件@ohos.resourceManager.d.ts，会发现末尾少写了个大括号。

		...  
	} //这里添上一个大括号
}
export default resmgr;
1.
2.
3.
4.

重启DevEco，发现报错不见了，那么我们继续。

namespace

命名空间定义了标识符的可见范围。

一般来说，如果我们需要在外部可以调用resmgr中的类和接口，则需要在类和接口添加export关键字。

但是resmgr在DevEco中反而找不到任何提示。推测对于DevEco，namespace内使用export是错误的。

我们将@ohos.resourceManager.d.ts中namespace中的export关键字全部去掉，重启DevEco，现在提示都出来了。

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

我们可以看到一般在命名空间内会定义以下几种类型。

// 枚举
enum Direction {
    ...
}

// 类
class Configuration {
    ...
}

// 接口
interface ResourceManager {
    ...
}

// 方法
function getResourceManager(bundleName: string, callback: AsyncCallback<ResourceManager>);
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

函数重载

重载允许一个函数接受不同数量或类型的参数时，作出不同的处理。

在声明文件中我们可以看到这样的一个方法：

// 获取当前应用的资源管理对象，使用callback形式返回ResourceManager对象。
export function getResourceManager(callback: AsyncCallback<ResourceManager>);
    
// 获取当前应用的资源管理对象，使用Promise形式返回ResourceManager对象。
export function getResourceManager(): Promise<ResourceManager>;
1.
2.
3.
4.
5.

实际上我们可以看到这两个方法实现的是同一个能力，只是使用形式不同。

这里要特别说明一下在所有声明文件当中随处可见的两个接口：

AsyncCallback<T>
Promise<T>

AsyncCallback<T>接口定义

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

调用getResourceManager(callback: AsyncCallback<ResourceManager>)

resourceManager.getResourceManager((error, mgr) => {
    //成功时， error返回undefined
    if (error != null) { 
        console.log("error occurs" + error);
        return; 
    }
    
    console.log("mgr ready")
});
1.
2.
3.
4.
5.
6.
7.
8.
9.

调用getResourceManager(): Promise<ResourceManager>

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);
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

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;
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

我们来看@ohos.bundle.d.ts文件

// 导入basic声明接口
import { AsyncCallback, Callback } from './basic';
...

// 声明方法
function getBundleInfo(bundleName: string, bundleFlags: number, callback: AsyncCallback<BundleInfo>): void;
1.
2.
3.
4.
5.
6.

为DevEco添加声明文件

OpenHarmony支持显示设备属性@ohos.display，但是却没有为display添加声明文件。

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

那么我们自己来写一个@ohos.display.d.ts文件。

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

导出一个命名空间display

declare namespace display {
  
}

export default display;
1.
2.
3.
4.
5.

通过之前使用测试，我们发现OpenHarmony只支持display的getDefaultDisplay方法，该方法使用Promise形式返回一个Display对象。

Display对象只支持两个可读属性width和height。

interface Display {
   readonly width: number;
   readonly height: number;
}
1.
2.
3.
4.

getDefaultDisplay方法的定义

function getDefaultDisplay(): Promise<Display>;
1.

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

declare namespace display {
  function getDefaultDisplay(): Promise<Display>;

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

export default display;
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

保存，重新启动DevEco。

注意：

不要直接拷贝HarmonyOS SDK的@ohos.display.d.ts文件，因为太多OpenHarmony没有支持了。

js开发则需要在[OpenHarmony SDK文件夹]\js\3.1.0.0\api\phone添加@ohos.display.d.ts文件

现在报错没有了，来使用API看看吧。

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

提示都出来啦~

打印一个分辨率在开发板上试试：

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

【如此之白】OpenHarmony API声明文件探究-鸿蒙开发者社区

分类

标签

已于2022-9-7 11:47:52修改

4条回复

按时间正序

按时间倒序

红叶亦知秋

非常完整的教程，必须收藏一波

已于2022-2-21 17:22:53修改

2022-2-21 17:21:44

民之码农

666

2022-2-22 08:22:03

物联风景

厉害啦

2022-2-23 09:24:50

科技维度

好文，值得顶

2022-3-3 11:11:38

51CTO

51CTO博客

51CTO学堂

【如此之白】OpenHarmony API声明文件探究原创精华

API声明文件公共仓

DevEco声明文件

typescript声明文件

如何读声明文件

declare

namespace

函数重载

basic.d.ts

为DevEco添加声明文件

目录

订阅鸿蒙技术特刊，精选内容抢先看

51CTO

51CTO博客

51CTO学堂

【如此之白】OpenHarmony API声明文件探究 原创 精华

API声明文件公共仓

DevEco声明文件

typescript声明文件

如何读声明文件

declare

namespace

函数重载

basic.d.ts

为DevEco添加声明文件

目录

订阅鸿蒙技术特刊，精选内容抢先看

【如此之白】OpenHarmony API声明文件探究原创精华