API接口说明模板

总体写作说明

说明：
所有的写作说明，在完成写作后，都要删除。

d.ts标签与文档字段的对应关系

以下字段，除版本说明外，均需下沉到每一个接口中。

如果是属性、interface表格，字段全表统一无差异，可统一写在表格上方；如果有一个不一致，需全部拆开，写到每一行的“说明”里。

下面进入具体每个API的写作。

文档标题

写作说明

1. 文档标题：作为文档标题，要求使用中文短语概括本模块功能；但如果部分概念使用英文更便于开发者理解，可以直接使用。如Ability、SIM卡管理等。
2. 标题层级：文档标题为一级标题，使用# ；namespace下的属性字段、function、class、interface、enum、type为二级标题，使用## ；class下的属性、function为三级标题，使用### 。
3. 起始版本说明：使用markdown的引用语法“>”对接口的起始版本进行说明，说明后需要换行。
   版本说明统一放在模块描述之后。一个模块只会有一个起始版本。
   采用标准句式：“本模块首批接口从API version x开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。”x需要修改为对应的版本号。

模块描述。此处对该模块的定义、功能、使用场景、使用建议进行描述，采用如下固定句式。

（模块介绍，可选）xxx是xxx。

（功能描述，必选）xxx模块提供xxx能力，包括xxx、xxx等。——当模块名不够语义化时，推荐此句式。

或 本模块提供xxx能力，包括xxx、xxx等。——当模块名已经表达了清晰的语义时，推荐此句式。

（使用场景，可选）当需要xxx时，使用本模块接口xxx。

（使用建议或注意事项，可选）本模块接口可与xxx联合使用，以提升开发效率……。

举例1：“后台任务管理模块”的模块描述示例

本模块提供后台任务管理能力。 当应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend），或长时任务避免进入挂起状态。

举例2：“拨打电话模块”的模块描述示例

本模块提供呼叫管理能力，包括拨打电话、跳转到拨号界面、获取通话状态、格式化电话号码等。 如需订阅通话状态，请使用observer.on('callStateChange')。

举例3：“分布式数据管理模块”的模块描述示例

分布式数据管理模块为应用程序提供不同设备间数据库的分布式协同能力。 通过调用分布式数据各个接口，应用程序可将数据保存到分布式数据库中，并可对分布式数据库中的数据进行增加、删除、修改、查询、同步等操作。

举例4：“线性容器ArrayList模块”的模块描述示例

ArrayList是一种线性数据结构，底层基于数组实现。ArrayList会根据实际需要动态调整容量，每次扩容增加50%。 ArrayList和Vector相似，都是基于数组实现。它们都可以动态调整容量，但Vector每次扩容增加1倍。 ArrayList和LinkedList相比，ArrayList的随机访问效率更高。但由于ArrayList的增删操作会影响数组内其他元素的移动，LinkedList的增加和删除操作效率更高。 当需要频繁读取集合中的元素时，推荐使用ArrayList。

说明：
本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

写作说明

1. 根据实际情况填写导入模块。采用代码段的样式，给出import语句。

2. 如果没有导入模块，将“导入模块”修改为“使用说明”。
   使用说明案例：
   在使用AbilityContext的功能前，需要通过[getContext()](链接到对应的接口说明文件中.md)先获取Context对象。

   import ability_featureAbility from '@ohos.ability.featureAbility';
   var context = ability_featureAbility.getContext();

import call from '@ohos.telephony.call';

属性

写作说明

1. 可选，如果没有属性可删除此二级标题。

2. 类型如果为自定义类型，需要建立链接到对应的interface或enum中。

3. 对于只读属性：d.ts中标有readonly字样。如果取值为有特殊含义的有限值，需要在说明里枚举，或是通过类型链接到对应枚举类型。

4. 对于必填属性：如果仅支持固定字段，需要进行说明。如该属性不作为入参类型的取值，可填写N/A。

系统能力： SystemCapability.xxx.xxx。（必选）

常量

写作说明

1. 可选，如果没有常量可删除此二级标题，对应d.ts中的const。

2. 类型如果为自定义类型，需要建立链接到对应的interface或enum中。

系统能力： SystemCapability.xxx.xxx。（必选）

方法

写作说明

1. 可选，如果没有可删除。如果有多个方法，请分多个二级内容描述，并使用“##”自行新建二级标题。

2. 二级标题名为方法名，采用导入类.方法名，如果是订阅方法，需要在方法名加上对应的订阅事件。

   示例： sim.getSimIccId 订阅方法：sim.on('exampleEvent')

3. 方法具体调用形式：和d.ts保持一致，需要包括参数类型、参数名、返回值类型。 示例：getNetworkState(slotId: number, callback: AsyncCallback<NetworkState>): void 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符&lt; &gt; 。

4. 方法描述：对方法实现的功能进行描述，包括其使用的前提条件（如：在xx方法调用后才能调用、需要确保网络已连接……）、使用之后的影响（如：调用该接口后再进行xx将不起效）、权限限制、系统能力等。

5. 异步方法描述：存在大量异步方法，其返回方式需要在方法描述处进行说明。具体写法参考总体写作说明第14项。

6. 表格内换行：markdown语法中，换行采用特殊标记<br>

（在此处给出方法的具体调用形式。如果是静态方法需说明） 方法名称(参数1名称：参数1类型，参数2名称：参数2类型，……)：返回值类型

在此处给出方法描述。说明请参考上述写作说明第4、5点。

模型约束：此接口仅可在FA模型下使用。（如不涉及可删除）

系统接口：此接口为系统接口。（如不涉及可删除）

需要权限：ohos.permission.xxx（如不涉及可删除）

系统能力：SystemCapability.xxx.xxx（必选）

参数： （可选，如不涉及可删除）

返回值：（可选，如不涉及可删除）

错误码：（可选，如不涉及可删除）

以下错误码的详细介绍请参见ohos.window(窗口)错误码。（链接到对应模块的“错误码参考”文档）

示例：

// 必选项。

// 所有的示例代码需要进行自检。
// 不能出现缺符号、变量前后不一致等低错。
// 所有使用到的变量要进行声明。

// 不允许直接写参数名，必须是可使用、易替代的实际用例。如果非用户自定义填写，需通过注释进行说明。
// 例如：var result = xxx.createExample(parameterOne); // parameterOne由扫描自动获取

// 注释要精简、突出要点。需提供注释的典型场景还有：
// 1. 当代码不能说明变量命名的具体含义，或不能说明代码逻辑时，必须提供注释。
// 2. 涉及到复杂算法或特殊语法时，必须提供注释。

on/off订阅方法

写作说明

1. 与方法要求一致，以下仅作差异项说明。

2. 二级标题名为方法名，采用导入类.方法名，需要在方法名加上对应的订阅事件。 示例：sim.on('exampleEvent') 、on('play' | 'pause' | 'stop' | 'reset')

3. 方法具体调用形式：和d.ts保持一致，需要包括参数类型、事件名、参数名、返回值类型。 示例：on(type: 'ringerModeChange', callback: Callback<AudioRingMode>): void 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符&lt; &gt; 。

（在此处给出方法的具体调用形式。如果是静态方法需说明） 方法名称(参数1名称：参数1类型，参数2名称：参数2类型，……)：返回值类型

在此处给出方法描述。说明请参考上述写作说明第4、5点。

模型约束：此接口仅可在FA模型下使用。（如不涉及可删除）

系统接口：此接口为系统接口。（如不涉及可删除）

需要权限：ohos.permission.xxx（如不涉及可删除）

系统能力：SystemCapability.xxx.xxx（必选）

参数： （可选，如不涉及可删除）

返回值：（可选，如不涉及可删除）

示例：

// 必选项。与方法要求一致。

// 所有的示例代码需要进行自检。
// 不能出现缺符号、变量前后不一致等低错。
// 所有使用到的变量要进行声明。

// 不允许直接写参数名，必须是可使用、易替代的实际用例。如果非用户自定义填写，需通过注释进行说明。
// 例如：var result = xxx.createExample(parameterOne); // parameterOne由扫描自动获取

// 注释要精简、突出要点。需提供注释的典型场景还有：
// 1. 当代码不能说明变量命名的具体含义，或不能说明代码逻辑时，必须提供注释。
// 2. 涉及到复杂算法或特殊语法时，必须提供注释。

Class/Interface

写作说明

1. 可选，如果没有可删除。如果有多个，请分多个二级内容描述，并使用“##”自行新建二级标题。

2. 二级标题名为class、interface的名称。

3. 如果该API中，既有属性，又有方法，需要先进行属性的写作，并使用“###”三级标题。 如果该API中，只有属性，那么不需要新建三级标题，直接使用表格陈列属性。

类描述/interface描述。如果有使用限制，需要在这个地方说明。比方说，是否有前提条件，是否需要通过什么方法先构造一个实例。

属性

写作说明

除标题使用三级标题外，其余要求同属性，如仅有属性，可删除。

Class/Interface中的方法

写作说明

1. 标题名为方法名，使用三级标题，没有前缀。如果是订阅方法，需要在方法名加上对应的订阅事件。 示例： getSimIccId 订阅方法：on('exampleEvent')
2. 其余与方法要求一致，不再重复。

枚举

写作说明

1. 可选，如果没有可删除。如果有多个枚举，请分多个二级内容描述，并使用“##”自行新建二级标题。

2. 二级标题名为实际枚举名，比方说 BatteryHealthState 。

在此处给出该枚举类型的简要描述。如：表示连接的充电器类型的枚举。

系统能力：SystemCapability.xxx.xxx（必选）

Type

写作说明

1. 可选，如果没有可删除此二级标题，对应d.ts中的type联合类型。

2. 如果为取值范围为具体取值，如固定的字符串、枚举值等，需要说明其数据类型和指定取值；如果取值范围为指定类型，需说明是否取类型下任意值，还是有取值范围。

3. 类型如果为自定义类型，需要建立链接到对应的interface或enum中。

在此处给出该联合类型的简要描述。如：表示允许的数据字段类型。

系统能力： SystemCapability.xxx.xxx（必选）

变更日志