diff --git a/zh-cn/contribute/template/js-template.md b/zh-cn/contribute/template/js-template.md new file mode 100644 index 0000000000000000000000000000000000000000..c86a6f192f1519771d566ab7fdbceef9630654ec --- /dev/null +++ b/zh-cn/contribute/template/js-template.md @@ -0,0 +1,318 @@ +# 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 开始支持。 + + +## 导入模块 + +必选,描述需导入的模块。如果有,则用import语句描述。如无,写“无需导入”。例如: + +```undefined +import app from '@system.app'; +``` + + +## 权限 + +必选,表示运行该模块所需的权限。如无需权限,写“无”。 + +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。 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| 示例:src | string | 是 | 是 | 播放的音频媒体uri。 | + + +### interface方法名称 + +> **说明:** +> 如果该interface有多个方法,则分多个subsection描写。 + + +在此处给出API的简要描述。需说明是什么方法(包括:构造方法、静态方法、实例方法),如有使用限制,一并在此说明。 + + +示例:构造方法,用于xxxxxx。 + + +然后,按照参数、返回值、示例对API进行详细描述。格式如下: + + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | 示例1:visible | boolean | 否 | 是否启动保活,默认值false。 如有默认值、合法值需要进行说明。 | + | 示例2:connection | [AbilityInfo](#abilityinfo) | 是 | 需要关闭的连接。 | + +- 返回值: + | 参数名 | 类型 | 说明 | + | -------- | -------- | -------- | + | 示例1:appName | string | 表示应用的名称。 | + | 示例2:versionName | [AbilityInfo](#abilityinfo)| 表示应用的版本名称。 | + +- 示例: + ```undefined + var info = app.getInfo(); + console.log(JSON.stringify(info)); + ``` + + +## type名称 + +> **说明:** +> 如果有多个type,则分多个section描写。 + + +| 名称 | 类型 | 描述 | +| -------- | -------- | -------- | +| | | | +| | | | + + +## AbilityInfo + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| bundleName | string | 是 | Ability的包名称,需要与PA端匹配,区分大小写。 | +| abilityName | string | 是 | Ability名称,需要与PA端匹配,区分大小写。 | +| entities | Array<string> | 否 | 希望被调起的FA所归属的实体列表,如果不填,默认查找所有实体列表。需配合action使用。 预定义类型待补充。 |