开源鸿蒙5.0.2对应的api版本是14

5.0社区仓有工具检查接口规范性报告工具: interface/sdk-js/build-tools/api_check_plugin

api_check_plugin是什么?

在解释api_check_plugin是什么之前得先知道 应用调用的api接口都是文件名后缀为.d.ts的文件,这些文件内部声明了arkts的api,应用只需要从这些d.ts的文件中导入命名空间或着类,就可以在代码中使用相应的函数功能.

api的定义有着一定的规范

比如定义一个枚举,需要如下声明:

    /**

     * Enumerates  state.

     * @enum {number}

     * @syscap SystemCapability.XXXXX.XXXXX

     * @systemapi

     * @since 11

     */

比如定义一个接口,需要如下声明

    /**
     * Provides the device information definitions.
     * @interface DevInfo
     * @syscap SystemCapability.XXXX.XXXX
     * @systemapi
     * @since 11
     */

很多时候我们自己添加的d.ts虽然功能都能调通,但是d.ts文件却不满足api的声明规范,这时候可以用api_check_plugin工具来检查并纠错我们d.ts文件不规范的地方

api_check_plugin如何获取?

在开源鸿蒙的主干代码里面已经集成了这个仓,仓的相对路径为

interface/sdk-js/build-tools/api_check_plugin,可以直接在这里获取

但如果你只是个纯应用开发者,并没有下载开源鸿蒙的代码,那你可以从如下链接获取:

开源鸿蒙项目原地址链接

个人仓链接

api_check_plugin如何使用?

获取到api_check_plugin后,在目录下有个README_zh.md文档

注意点为图中红色标记(如通过社区链接获取需要自己替换config.json内容,如通过个人链接获取则只需要修改mdFiles.txt即可)

添加d.ts路径

添加需要检测的d.ts文件全路径到mdFiles.txt

注意,如果需要一次检测多个d.ts文件则直接换行添加即可,如下:

安装npm

根据上面md文档的描述,在api_check_plugin目录下打开cmd并执行 npm install

使用工具

执行npm run test

在执行完后会在

生成报告文件,该文件中会指出你检测的d.ts文件中语法不规范的地方

根据Js_Api.xlsx修复dts文件

总体的修复逻辑就是正规的dts文件有着特定的声明规范,语法,当你有不规范的语法时,api_check_plugin会给你指出,下面截取一段有问题的报告并附上修复逻辑

首先这个表格只需要关注C D G列即可,C列表示出问题的行,D列表示出问题的具体apiname内容,G列表示报错的原因

比如:

the type of the [1] [param] tag is incorrect. Please check if it matches the type of the [1] parameter

这个问题是你标注的参数值有名字没有类型,应修改为带上参数

如上面所示,一个接口必须拥有

@param 

@syscap

@systemapi 

@since

如果该接口拥有返回值,则还需要拥有

@returns

在添加这些标签的时候还需附带上类型

比如:

the [syscap] tag value is incorrect. Please check if the syscap field is configured

这个表示你的@syscap不在鸿蒙的一直syscap内,这个一般不需要过多关注,只需确保syscap真实存在即可

比如:

Error words in [createWfdSink]: {Wfd}.Do you want to spell it as [afd,dfd,fd,ffd,rfd]?

这个表示Wfd不是一个正规的单次,如果类似这种缩写是在注释里面,则需要写全,不能用缩写,比如这里的Wfd是在函数名上,则不需要进行修改,如果出现在注释中,则需要改成全称: wifi display 

修复的原则是最后检测的报告中只能出现syscap的错误跟单词拼写错误(一些缩写出现在函数名跟参数中,不需要修改,报错不予理会即可)