From 78d1ebad7a0c04954649e5ad1125ae6029e51e71 Mon Sep 17 00:00:00 2001 From: zengyawen Date: Mon, 22 Nov 2021 15:16:49 +0800 Subject: [PATCH] update js apis template Signed-off-by: zengyawen --- zh-cn/contribute/template/js-template.md | 495 ++++++++++------------- 1 file changed, 205 insertions(+), 290 deletions(-) diff --git a/zh-cn/contribute/template/js-template.md b/zh-cn/contribute/template/js-template.md index c86a6f192f..e7d2447815 100644 --- a/zh-cn/contribute/template/js-template.md +++ b/zh-cn/contribute/template/js-template.md @@ -1,318 +1,233 @@ -# API模板 - -- [完成写作后删除](#完成写作后删除) - - [版本说明](#版本说明) -- [导入模块](#导入模块) -- [权限](#权限) -- [属性](#属性) -- [方法名称](#方法名称) -- [枚举名称](#枚举名称) -- [类名称](#类名称) - - [类属性](#类属性) - - [类方法名称](#类方法名称) -- [以k-v表示的interface](#以k-v表示的interface) -- [类似class的interface](#类似class的interface) - - [interface属性](#interface属性) - - [interface方法名称](#interface方法名称) -- [type名称](#type名称) -- [AbilityInfo](#abilityinfo) - -## 完成写作后删除 - -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](#abilityinfo)）。 | - - -> **说明：** -> 从API Version x 开始支持。 - +# API接口说明模板 + +> *写作说明* +> +> 0.1 - 所有的写作说明，在完成写作后，都要删除。 +> +> 0.2 - 上传路径：docs/zh-cn/application-dev/js-reference/apis，图片放到对应的figures文件夹中。上传后可通过提issue的方式，触发翻译。 +> +> 0.3 - 一个d.ts文件对应一个js api接口文档。**文件名称：js-apis-模块名.md**。示例： +> +> ​ 媒体@ohos.multimedia.audio，文件命名为：js-apis-audio.md +> +> ​ 电话@ohos.telephony.sms，文件命名为：js-apis-sms.md +> +> 0.4 - 新增文件，需要修改对应的Readme，即docs/zh-cn/application-dev/js-reference/apis/Readme-CN.md。 +> +> 0.5 - **文档标题**：使用中文短语概括本模块功能。但如果部分概念使用英文更便于开发者理解，不必强求，比方说，Ability、SIM卡等概念可以直接使用。 +> +> 0.6 - 文档标题为一级标题；namespace下的属性字段、function、class、interface、enum、type为二级标题；class下的属性、function为三级标题。 +> +> 0.7 - **对已有模块的新增接口标记起始版本：使用标签，标记对应的版本号。** +> +> ​ 示例：API 6已有的模块，在API 7新增了一个属性字段，则在属性后加标记，即newAttribute7+。 +> +> ​ 如果新增了一个方法，则在方法标题后增加标记，即 sim.getSimIccId7+，interface、class、枚举等同理。 +> +> 0.8 - **废弃内容**：不能直接在文档上删去，在废弃内容后面加上标标注deprecated，并使用“>”引用语法建议使用的替代方式，加上对应的链接。 +> +> ​ 示例：abandonmentMethod(deprecated) +> +> > 从API Version 7 开始废弃，建议使用[newMethod](#newMethod)替代。 +> +> 下面进入具体每个API的写作。 + +*** +> *写作说明* +> +> 1.1 - 使用markdown的引用语法“>”对接口的起始版本进行说明。 +> +> 1.2 - 一个模块只会有一个起始版本。 +> +> 1.3 - 如果是第一个版本，只写第一句“从 API Version **x** 开始支持。”，x修改为对应的版本号，比方说API Version 7 +> +> 1.4 - 如果涉及新版本的接口，需要在新增接口中进行说明。在版本说明这里，要加上第二句，不必做任何改动。 + +> **说明** +> +> - 从 API Version x 开始支持。 +> - 标记x+的接口，表示从 API Version x 开始支持。 + +模块说明。此处对该模块提供的功能、使用场景和使用建议进行简要描述。 ## 导入模块 - -必选，描述需导入的模块。如果有，则用import语句描述。如无，写“无需导入”。例如： - -```undefined -import app from '@system.app'; +> *写作说明* +> +> 2.1 - 根据实际情况填写导入模块。采用代码段的样式，给出import语句。 +> +> 2.2 - 如果没有导入模块，将“导入模块”修改为“使用说明”。 +> +> ​ 使用说明案例： +> +> ​ 在使用AbilityContext的功能前，需要通过[getContext()](链接到对应的接口说明文件中.md)先获取Context对象。 +> ```js +> import ability_featureAbility from '@ohos.ability.featureAbility'; +> var context = ability_featureAbility.getContext(); +> ``` + +```js +import call from '@ohos.telephony.call'; ``` - -## 权限 - -必选，表示运行该模块所需的权限。如无需权限，写“无”。 - -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](#abilityinfo) | 是 | 需要关闭的连接。 | - -- 返回值： - 可选，若无返回值，不写此项，并在方法的调用描述中添加返回值为void。 - - 若返回值无参数名，可删除第一列。 - - 若返回值类型为一个自定义的引用数据类型，则在该章节的最后进行说明，并建立对应的超链接，如示例2所示 。 - | 参数名 | 类型 | 说明 | - | -------- | -------- | -------- | - | 示例1：appName | string | 表示应用的名称。 | - | 示例2：versionName | [AbilityInfo](#abilityinfo) | 表示应用的版本名称。 | - -- 示例： - ```undefined - var info = app.getInfo(); - console.log(JSON.stringify(info)); - ``` - - -## 枚举名称 - ->**说明：** -> 如果有多个枚举，则分多个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](#abilityinfo) | 是 | 需要关闭的连接。 | - -- 返回值： - 可选，若无返回值，不写此项，并在方法的调用描述中添加返回值为void。 - - 若返回值无参数名，可删除第一列。 - - 若返回值类型为一个自定义的引用数据类型，则在该章节的最后进行说明，并建立对应的超链接，如示例2所示 。 - | 参数名 | 类型 | 说明 | - | -------- | -------- | -------- | - | 示例1：appName | string | 表示应用的名称。 | - | 示例2：versionName | [AbilityInfo](#abilityinfo) | 表示应用的版本名称。 | - -- 示例： - ```undefined - var info = app.getInfo(); - console.log(JSON.stringify(info)); - ``` - - -## 以k-v表示的interface - -> **说明：** -> 如果有多个以k-v表示的interface，则分多个section描写。 -> -> 示例：AbilityInfo - - -在此处给出interface的简要描述。 - - -| 名称 | 参数类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| 示例：url | string | 否 | 拉起FA时，指定打开的页面的url。默认直接打开首页。 | - - -## 类似class的interface - -> **说明：** -> 如果有多个类似class的interface，则分多个section描写。 -> -> 示例：AbilityInfo - - -在此处给出interface的简要描述。 - - -### interface属性 - -> **说明：** -> “interface属性”是对不同属性的标识说明，在文档编写时直接以“属性”作为Section标题。 - -可选，如果该类里没有属性可删除此subsection。 +> *写作说明* +> +> 4.1 - 可选，如果没有属性可删除此二级标题。 +> +> 4.2 - 类型如果为自定义类型，需要建立链接到对应的interface或enum中。 +> +> 4.3 - 对于可读属性：如果取值为有特殊含义的有限值，需要进行枚举。 +> +> 4.4 - 对于可写属性：如果仅支持固定字段，需要进行说明。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------ | +| pluggedType | [BatteryPluggedType](#BatteryPluggedType) | 是 | 否 | 表示当前设备连接的充电器类型。 | +| isBatteryPresent | boolean | 是 | 否 | 表示当前设备是否支持电池或者电池是否在位。 | + +## 枚举 + +> *写作说明* +> +> 5.1 - 可选，如果没有可删除。如果有多个枚举，请分多个二级内容描述，并使用“##”自行新建二级标题。 +> +> 5.2 - 二级标题名为实际枚举名，比方说 BatteryHealthState 。 + +在此处给出该枚举类型的简要描述。如：表示连接的充电器类型的枚举。 + +| 名称 | 值 | 说明 | +| ---- | ---- | -------------------------- | +| NONE | 1 | 表示连接的充电器类型未知。 | + +## 方法 + +> *写作说明* +> +> 6.1 - 可选，如果没有可删除。如果有多个方法，请分多个二级内容描述，并使用“##”自行新建二级标题。 +> +> 6.2 - 二级标题名为方法名，采用导入类.方法名，如果是订阅方法，需要在方法名加上对应的订阅事件。 +> +> ​ 示例： sim.getSimIccId +> +> ​ 订阅方法：sim.on('exampleEvent') +> +> 6.3 - **方法具体调用形式**：和d.ts保持一致，需要包括参数类型、参数名、返回值类型。 +> +> ​ 示例：getNetworkState(slotId: number, callback: AsyncCallback\): void +> +> ​ 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符< > 。 +> +> 6.4.1 - **方法描述**：对方法实现的功能进行描述，包括其使用的前提条件（*如：在xx方法调用后才能调用、需要确保网络已连接……*）、使用之后的影响（*如：调用该接口后再进行xx将不起效*）、权限限制等。 +> +> 6.4.2 - **异步方法描述**：存在大量异步方法，其返回方式需要在方法描述处进行说明。通过注册回调函数获取？还是通过Promise获取？ +> +> 6.4.3 - **表格内换行**：markdown语法中，换行采用特殊标记
+ +在此处给出方法的具体调用形式：（如果是静态方法需说明） 方法名称(参数1名称：参数1类型，参数2名称：参数2类型，……)：返回值类型 + +在此处给出方法描述。说明请参考6.4.1和6.4.2。 + +需要权限：ohos.permission.XXX（如不涉及可删除，如果是系统权限要说明） + +**参数：** （可选，如不涉及可删除） + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| parameterOne | number \| string \| [CustomType](#CustomType) | 是 | 参数描述。给出取值范围、建议值。如果有固定格式，需要给出格式样例，尤其是URI。
自定义类型需要进行建链说明。 | +| callback | Callback\> | 否 | 参数描述。可选参数需要说明不填写该参数的后果。
如：不填该参数则取消该type对应的所有回调。 | + +**返回值**：（可选，如不涉及可删除） + +| 类型 | 说明 | +| ------------------------------------------ | -------------------------------------------- | +| string | 返回值描述。取到返回值之后，可以用来做什么。 | +| Promise\> | 返回值描述。通过Promise获取了什么。 | + +**示例：** + +```js +// 必选项。 +// 所有的示例代码需要进行自检。 +// 不能出现缺符号、变量前后不一致等低错。 +// 所有的使用到的变量要进行声明。 +// 不允许直接写参数名，必须是可使用、易替代的实际用例。 +// 如果非用户自定义填写，需通过注释进行说明。 +// 示例：var result = xxx.createExample(parameterOne); // parameterOne由扫描自动获取 +``` -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------- | -------- | -------- | -------- | -------- | -| 示例：src | string | 是 | 是 | 播放的音频媒体uri。 | +## Class/Interface +> *写作说明* +> +> 7.1 - 可选，如果没有可删除。如果有多个，请分多个二级内容描述，并使用“##”自行新建二级标题。 +> +> 7.2 - 二级标题名为class、interface的名称。 +> +> 7.3 - 如果该API中，既有属性，又有方法，需要先进行属性的写作，并使用“###”三级标题。 +> +> ​ 如果该API中，只有属性，那么不需要新建三级标题，直接使用表格陈列属性，具体示例参考[CustomType](#CustomType)。 -### interface方法名称 +类描述/interface描述。如果有使用限制，需要在这个地方说明。比方说，是否有前提条件，是否需要通过什么方法先构造一个实例。 -> **说明：** -> 如果该interface有多个方法，则分多个subsection描写。 +### 属性 +> *写作说明* +> +> 除标题使用三级标题外，其余要求同[属性](#属性)。 -在此处给出API的简要描述。需说明是什么方法（包括：构造方法、静态方法、实例方法），如有使用限制，一并在此说明。 +### Class/Interface中的方法 +> *写作说明* +> +> 7.4 - 标题名为方法名，使用三级标题，**没有前缀**。如果是订阅方法，需要在方法名加上对应的订阅事件。 +> +> ​ 示例： getSimIccId +> +> ​ 订阅方法：on('exampleEvent') +> +> 其余要求请参考[方法](#方法)中的说明。 -示例：构造方法，用于xxxxxx。 +在此处给出方法的具体调用形式。说明请参考6.3。 +在此处给出方法描述。说明请参考6.4.1和6.4.2。 -然后，按照参数、返回值、示例对API进行详细描述。格式如下： +需要权限：ohos.permission.XXX（如不涉及可删除，如果是系统权限要说明） +**参数：** （可选，如不涉及可删除） -- 参数： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | 示例1：visible | boolean | 否 | 是否启动保活，默认值false。 如有默认值、合法值需要进行说明。 | - | 示例2：connection | [AbilityInfo](#abilityinfo) | 是 | 需要关闭的连接。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| parameterOne | number \| string \| [CustomType](#CustomType) | 是 | 参数描述。给出取值范围、建议值。如果有固定格式，需要给出格式样例，尤其是URI。
自定义类型需要进行建链说明。 | +| callback | Callback\> | 否 | 参数描述。可选参数需要说明不填写该参数的后果。
如：不填该参数则取消该type对应的所有回调。 | -- 返回值： - | 参数名 | 类型 | 说明 | - | -------- | -------- | -------- | - | 示例1：appName | string | 表示应用的名称。 | - | 示例2：versionName | [AbilityInfo](#abilityinfo)| 表示应用的版本名称。 | +**返回值**：（可选，如不涉及可删除） -- 示例： - ```undefined - var info = app.getInfo(); - console.log(JSON.stringify(info)); - ``` +| 类型 | 说明 | +| ------------------------------------------ | -------------------------------------------- | +| string | 返回值描述。取到返回值之后，可以用来做什么。 | +| Promise\> | 返回值描述。通过Promise获取了什么。 | +**示例：** -## type名称 +```js +// 必选项。 +// 所有的示例代码需要进行自检。 +// 不能出现缺符号、变量前后不一致等低错。 +// 所有的使用到的变量要进行声明。 +// 不允许直接写参数名，必须是可使用、易替代的实际用例。 +// 如果非用户自定义填写，需通过注释进行说明。 +// 示例：var result = xxx.createExample(parameterOne); // parameterOne由扫描自动获取 +``` -> **说明：** -> 如果有多个type，则分多个section描写。 +## CustomType +仅有k-v键值对的自定义类型示例。 -| 名称 | 类型 | 描述 | -| -------- | -------- | -------- | -| | | | -| | | | +| 名称 | 类型 | 可读 |可写| 说明 | +| ------------ | ---- | ---- | ---- | ---- | +| parameterUrl | string | 是 | 是 |媒体输出URI。支持：
1. 协议类型为“internal”的相对路径，示例如下：
临时目录：internal://cache/test.mp4

2. 文件的绝对路径，示例如下：
file:///data/data/ohos.xxx.xxx/files/test.mp4| +| parameterOne | [CustomEnum](#枚举) | 是 | 是 |属性描述，要求与参数说明类似。| -## AbilityInfo -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| bundleName | string | 是 | Ability的包名称，需要与PA端匹配，区分大小写。 | -| abilityName | string | 是 | Ability名称，需要与PA端匹配，区分大小写。 | -| entities | Array<string> | 否 | 希望被调起的FA所归属的实体列表，如果不填，默认查找所有实体列表。需配合action使用。 预定义类型待补充。 | -- GitLab