API模板

About 8 min

API模板

完成写作后删除

  1. 每个章节(Topic)对应一个d.ts文件。

  2. 章节(Topic)名称为接口提供的功能,优先选择动宾短语。如:打印日志

  3. 模板中的说明和示例,均使用斜体和蓝色文字以做区分, 正式文档使用正常黑色字体

  4. 参数类型的写法:

    • Object、Function、Array等引用数据类型统一大写首字母;
    • string、number、boolean等基本数据类型统一小写首字母;
    • <color>、<percentage>、<length>等尖括号内的枚举类型统一小写首字母。

版本说明

  • 新增内容

    • 新增整个组件/接口 在组件或API的概述下方,点击 插入,选择 说明“从 API Version 7 开始支持。”

      说明: 从 API Version 7 开始支持。

    • 新增小部分内容 在新增部分后面添加“7+”,并使用“sup”标签设置为上标,示例:7+

      1. 新增属性、样式等,在属性名后加7+,示例:
        名称 类型 默认值 必填 描述
        selected7+ string - 指定当前列表中被选中激活的项,可选值为list-item的section属性值。
      2. 新增属性值,在属性值后加7+,示例:
        名称 类型 默认值 必填 描述
        type string horizontal 设置进度条的类型,该属性不支持动态修改,可选值为:
        - horizontal:线性进度条。
        - arc:弧形进度条。
        - eclipse7+:圆形进度条,展现类似月圆月缺的进度展示效果。
      3. 新增部分描述,在增加的部分描述后加7+,示例: 仅父容器为<div>、<list-item>、<tabs>时生效。
  • 废弃内容 不要直接在文档上删去,在废弃内容后面加括号标注deprecated,并说明建议使用的替代方式,加上对应的链接。

    并且按上述方式标注版本号。

    名称 类型 默认值 必填 描述
    backgroundColor(deprecated) 7+ <color> #ff6384 设置线或柱的颜色( 不推荐使用,建议使用 AbilityInfo)。

说明: 从API Version x 开始支持。

导入模块

必选,描述需导入的模块。如果有,则用import语句描述。如无,写“无需导入”。例如:

import app from '@system.app';
1

权限

必选,表示运行该模块所需的权限。如无需权限,写“无”。

ohos.permission.INTERNET

属性

可选,如果没有属性可删除此section。

名称 参数类型 可读 可写 说明
示例:deviceType string 设备类型。

方法名称

说明: 方法名称的前缀为导入类的名称。如果有多个方法,则分多个section描写。

示例:storage.get

此处给出该方法的具体调用形式,为:方法名称(参数1名称:参数1类型,参数2名称:参数2类型,……):返回值类型,与d.ts文件中的方法描述保持一致。

示例:show(url:string, type:string):Promise<void>

如有使用限制,在此处进行详细描述说明。

然后,按照参数、返回值、示例对API进行详细描述。格式如下:

  • 参数: 可选,若无参数,不写此项,并在方法的调用描述中设置参数为空。

    如果参数类型为一个自定义的引用数据类型,则在该章节的最后进行说明,并建立对应的超链接,如示例2所示 。

    参数名 类型 必填 说明
    * 示例1:*visible boolean 是否启动保活,默认值false。 如有默认值、合法值需要进行说明。
    * 示例2:*connection AbilityInfo 需要关闭的连接。
  • 返回值: 可选,若无返回值,不写此项,并在方法的调用描述中添加返回值为void。

    若返回值无参数名,可删除第一列。

    若返回值类型为一个自定义的引用数据类型,则在该章节的最后进行说明,并建立对应的超链接,如示例2所示 。

    参数名 类型 说明
    示例1:appName string 表示应用的名称。
    示例2:versionName AbilityInfo 表示应用的版本名称。
  • 示例:

    var info = app.getInfo();
    console.log(JSON.stringify(info));
    
    1
    2

枚举名称

说明: 如果有多个枚举,则分多个section描写。

必选,在此给出该枚举类型的简要描述。如:用于表示电池充电状态。

名称 默认值 说明
示例:NONE 1 表示电池充电状态未知。

类名称

说明: 如果有多个类,则分多个section描写。

在此处给出类的简要描述。需要说明在使用该类的方法前,通过哪个方法构造实例。

类属性

说明: “类属性”是对不同属性的标识说明,在文档编写时直接以“属性”作为Section标题。

可选,如果该类里没有属性可删除此subsection。

名称 参数类型 可读 可写 说明
示例:src string 播放的音频媒体uri。

类方法名称

说明: 如果有多个方法,则分多个subsection描写。

示例:setPasteData

此处给出该方法的具体调用形式,为:(如果是静态方法需说明) 方法名称(参数1名称:参数1类型,参数2名称:参数2类型,……):返回值类型,与d.ts文件中的方法描述保持一致

示例:setPasteData(pasteData:PasteData): Promise<void>

在此处给出该方法的简要描述。

如有使用限制,在此处进行详细描述说明。

然后,按照参数、返回值、示例对API进行详细描述。格式如下:

  • 参数: 可选,如无参数,不写此项,并在方法的调用描述中设置参数为空。。

    如果参数类型为一个自定义的引用数据类型,则在该章节的最后进行说明,并建立对应的超链接,如示例2所示 。

    参数名 类型 必填 说明
    示例1:visible boolean 是否启动保活,默认值false。 如有默认值、合法值需要进行说明。
    示例2:connection AbilityInfo 需要关闭的连接。
  • 返回值: 可选,若无返回值,不写此项,并在方法的调用描述中添加返回值为void。

    若返回值无参数名,可删除第一列。

    若返回值类型为一个自定义的引用数据类型,则在该章节的最后进行说明,并建立对应的超链接,如示例2所示 。

    参数名 类型 说明
    示例1:appName string 表示应用的名称。
    示例2:versionName AbilityInfo 表示应用的版本名称。
  • 示例:

    var info = app.getInfo();
    console.log(JSON.stringify(info));
    
    1
    2

以k-v表示的interface

说明: 如果有多个以k-v表示的interface,则分多个section描写。

示例:AbilityInfo

在此处给出interface的简要描述。

名称 参数类型 必填 说明
示例:url string 拉起FA时,指定打开的页面的url。默认直接打开首页。

类似class的interface

说明: 如果有多个类似class的interface,则分多个section描写。

示例:AbilityInfo

在此处给出interface的简要描述。

interface属性

说明: “interface属性”是对不同属性的标识说明,在文档编写时直接以“属性”作为Section标题。

可选,如果该类里没有属性可删除此subsection。

名称 参数类型 可读 可写 说明
示例:src string 播放的音频媒体uri。

interface方法名称

说明: 如果该interface有多个方法,则分多个subsection描写。

在此处给出API的简要描述。需说明是什么方法(包括:构造方法、静态方法、实例方法),如有使用限制,一并在此说明。

示例:构造方法,用于xxxxxx。

然后,按照参数、返回值、示例对API进行详细描述。格式如下:

  • 参数:

    参数名 类型 必填 说明
    示例1:visible boolean 是否启动保活,默认值false。 如有默认值、合法值需要进行说明。
    示例2:connection AbilityInfo 需要关闭的连接。
  • 返回值:

    参数名 类型 说明
    示例1:appName string 表示应用的名称。
    示例2:versionName AbilityInfo 表示应用的版本名称。
  • 示例:

    var info = app.getInfo();
    console.log(JSON.stringify(info));
    
    1
    2

type名称

说明: 如果有多个type,则分多个section描写。

名称 类型 描述

AbilityInfo

参数名 类型 必填 说明
bundleName string Ability的包名称,需要与PA端匹配,区分大小写。
abilityName string Ability名称,需要与PA端匹配,区分大小写。
entities Array<string> 希望被调起的FA所归属的实体列表,如果不填,默认查找所有实体列表。需配合action使用。 预定义类型待补充。