!601 增加JS API参考的模板文件

Merge pull request !601 from 时睿/master

!601 增加JS API参考的模板文件
Merge pull request !601 from 时睿/master
c68bb4b6 · openharmony_ci · Gitee · aa44baa8 · 1f8ec867 · c68bb4b6
隐藏空白更改
内联并排

Showing with 318 addition and 0 deletion

zh-cn/contribute/template/js-template.md zh-cn/contribute/template/js-template.md +318 -0

未找到文件。
--- a/zh-cn/contribute/template/js-template.md
+++ b/zh-cn/contribute/template/js-template.md
+# 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等基本数据类型统一小写首字母；*
+   - *&lt;color&gt;、&lt;percentage&gt;、&lt;length&gt;等尖括号内的枚举类型统一小写首字母。*
+
+
+### 版本说明
+
+- 新增内容
+  - 新增整个组件/接口
+     在组件或API的概述下方，点击 **插入**，选择 **说明**“从 API Version 7 开始支持。”
+
+     > **说明：**
+     > 从 API Version 7 开始支持。
+  - 新增小部分内容
+     在新增部分后面添加“7+”，并使用“sup”标签设置为上标，示例：<sup>7+</sup>。
+
+     1. 新增属性、样式等，在属性名后加7+，示例：
+         | 名称 | 类型 | 默认值 | 必填 | 描述 |
+         | -------- | -------- | -------- | -------- | -------- |
+         | selected<sup>7+</sup> | string | - | 否 | 指定当前列表中被选中激活的项，可选值为list-item的section属性值。 |
+     2. 新增属性值，在属性值后加7+，示例：
+         | 名称 | 类型 | 默认值 | 必填 | 描述 |
+         | -------- | -------- | -------- | -------- | -------- |
+         | type | string | horizontal | 否 | 设置进度条的类型，该属性不支持动态修改，可选值为：<br/>-&nbsp;horizontal：线性进度条。<br/>-&nbsp;arc：弧形进度条。<br/>-&nbsp;eclipse<sup>7+</sup>：圆形进度条，展现类似月圆月缺的进度展示效果。 |
+     3. 新增部分描述，在增加的部分描述后加7+，示例：
+         仅父容器为&lt;div&gt;、&lt;list-item&gt;、&lt;tabs&gt;时生效。
+
+- 废弃内容
+  不要直接在文档上删去，在废弃内容后面加括号标注deprecated，并说明建议使用的替代方式，加上对应的链接。
+
+  并且按上述方式标注版本号。
+
+  | 名称 | 类型 | 默认值 | 必填 | 描述 |
+  | -------- | -------- | -------- | -------- | -------- |
+  | backgroundColor(deprecated)&nbsp;7+ | &lt;color&gt; | \#ff6384 | 否 | 设置线或柱的颜色（&nbsp;不推荐使用，建议使用 [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&lt;void&gt;
+
+
+如有使用限制，在此处进行详细描述说明。
+
+
+然后，按照参数、返回值、示例对API进行详细描述。格式如下：
+
+
+- 参数：
+  可选，若无参数，不写此项，并在方法的调用描述中设置参数为空。
+
+   如果参数类型为一个自定义的引用数据类型，则在该章节的最后进行说明，并建立对应的超链接，如示例2所示 。
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | *&nbsp;示例1：*visible | boolean | 否 | 是否启动保活，默认值false。&nbsp;如有默认值、合法值需要进行说明。 |
+  | *&nbsp;示例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&lt;void&gt;
+
+
+在此处给出该方法的简要描述。
+
+
+如有使用限制，在此处进行详细描述说明。
+
+
+然后，按照参数、返回值、示例对API进行详细描述。格式如下：
+
+
+- 参数：
+  可选，如无参数，不写此项，并在方法的调用描述中设置参数为空。。
+
+   如果参数类型为一个自定义的引用数据类型，则在该章节的最后进行说明，并建立对应的超链接，如示例2所示 。
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | 示例1：visible | boolean | 否 | 是否启动保活，默认值false。&nbsp;如有默认值、合法值需要进行说明。 |
+  | 示例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。&nbsp;如有默认值、合法值需要进行说明。 |
+  | 示例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&lt;string&gt; | 否 | 希望被调起的FA所归属的实体列表，如果不填，默认查找所有实体列表。需配合action使用。&nbsp;预定义类型待补充。 |