diff --git a/zh-cn/contribute/template/js-template.md b/zh-cn/contribute/template/js-template.md index 07097149e469cc0591176ba8d66cfe210bf3ac36..fe3ed9c8c1dc972d89ac87fd5ae91e7eeee97bfb 100644 --- a/zh-cn/contribute/template/js-template.md +++ b/zh-cn/contribute/template/js-template.md @@ -1,24 +1,24 @@ # API接口说明模板 ## 总体写作说明 +> **说明：**
所有的写作说明，在完成写作后，都要删除。 | | 说明项 | 细则 | | ---- | --------------------------------- | ------------------------------------------------------------ | | 1 | 客户化写作基本要求 | **写作中，请变身开发者，对于开发者使用该API时所需的使用场景、参数选取原则、开发建议/经验、示例等信息进行清晰描述，达到指导开发者顺利使用本API进行开发的目标。** | -| 2 | | **所有的写作说明，在完成写作后，都要删除。** | -| 3 | 上传路径 | markdown文件：docs/zh-cn/application-dev/reference/apis
图片路径：docs/zh-cn/application-dev/reference/apis/figures，并在markdown文件中通过路径`![](figures/xxx.jpg)`或`![](figures/xxx.png)`引用。 | -| 4 | 文件命名 | 一个d.ts对应一个js api文档，文件名称应与模块名称保持一致，格式为：**js-apis-模块名.md**。
示例：
媒体@ohos.multimedia.audio，文件命名为：js-apis-audio.md
电话@ohos.telephony.sms，文件命名为：js-apis-sms.md | -| 5 | 目录修改 | 新增文件，需要修改对应的Readme，即`docs/zh-cn/application-dev/reference/apis/Readme-CN.md`。 | -| 6 | 文档结构 | - 模块说明
- 起始版本说明
- 导入模块/使用说明
- 接口（属性、方法、枚举、自定义类型）
描述顺序和代码保持一致，如果某些接口具有逻辑顺序，请注意排列。 | -| 7 | 接口版本说明 | 1. 每个模块要有起始版本说明，使用引用语法“>”对接口的起始版本进行说明。接口没有标记的，默认与模块同一个起始版本。
2. 已有模块新增接口使用\标签标记对应版本号。写法：`版本号+`
例如`7+`
示例：API 6已有的模块，在API 7新增了一个属性字段，则在属性后加标记，即newAttribute7+。
如果新增了一个方法，则在方法标题后增加标记，即 sim.getSimIccId7+，interface、class、枚举等同理。 | -| 8 | 废弃接口说明 | 废弃内容不能直接删去，在废弃内容后面加标注deprecated，并使用“>”引用语法建议使用的替代方式，加上对应的链接。
示例：abandonmentMethod(deprecated)
> 从API Version 7 开始不再维护，建议使用[newMethod]\(#newmethod)替代。 | -| 9 | 权限说明 | 与代码保持一致，下沉到各个方法、枚举、属性字段中。
1. 如果仅系统应用可申请，格式：
**需要权限：** ohos.permission.xxxx，仅系统应用可用。
2. 如果该权限所有应用可申请，格式：
**需要权限：** ohos.permission.xxxx
3. 如果该接口涉及多个权限，则采用“和、或”进行分割，格式：
**需要权限：** ohos.permission.A 和 ohos.permission.B
**需要权限：** ohos.permission.A 或 ohos.permission.B | -| 10 | @syscap | 1. 每个方法都需要进行描述，格式：
**系统能力**：SystemCapability.xxx.xxx
2. 每个表格（属性、枚举、常量、变量）可统一进行说明，分两种情况：
1）每个表格下系统能力无差异的，同方法的写法：
**系统能力**：SystemCapability.xxx.xxx
2）有差异的：在每一个表格项里进行描述。 | -| 11 | @system api | 1. 如果某个模块全部接口均为system api，则在模块开头的版本说明下一行，增加：
- 本模块接口为系统接口。
2. 如果某个接口为system api，仅供OEM厂商使用，则需要在描述中增加：
**系统接口：** 此接口为系统接口。 | -| 12 | @FAModelOnly
@StageModelOnly | 1. 如果某个模块均只针对某模型实现，则在模块开头的版本说明下一行，增加：
- 本模块接口仅可在FA模型/Stage模型下使用。
2. 如果某个接口只针对某模型实现，则需要在描述中增加：
**模型约束：** 此接口仅可在FA模型/Stage模型下使用。 | -| 13 | 异步接口说明（callback、Promise） | 对于callback、Promise在方法描述、参数说明、返回值说明的具体描述要求如下：
**callback**的固定句式：
方法介绍：xxx（方法描述）。使用callback异步回调。
参数说明：
**callback\**：回调函数。返回true表示xxx；返回false表示xxx。
**callback\**：回调函数，返回xxx。例如”回调函数，返回音频采集器对象。“
**AsyncCallback\**：回调函数。当具体的操作（视具体接口功能描述）成功，err为undefined，否则为错误对象。
**AsyncCallback\**：回调函数。当具体的操作（视具体接口功能描述）成功，err为undefined，data为获取到的Object x；否则为错误对象。
**Promise**的固定句式：
方法介绍：xxx（方法描述）。使用Promise异步回调。
参数说明：
**Promise\**：Promise对象。返回true表示xxx；返回false表示xxx。
**Promise\**：Promise对象，返回xxx。例如”Promise对象，返回音频采集器对象。“
**Promise\**：Promise对象。无返回结果的Promise对象。 | -| 14 | 示例代码语言 | 所有的示例代码采用代码块的样式，并标记开发语言。
JS和eTS通用的标注`js`；仅eTS可用的，标注`ts`。 | -| 15 | 链接写法 | 格式：[链接文字]\(链接内容)
跨文件夹链接：[指南]\(\.\./../xxx/xxx.md)，一个`../`表示上移一层文件夹。
页面内链接：[接口A7+]\(#xxxa7)，页面内链接和需要链接到的标题保持一致，全小写无特殊符号无标签。 | +| 2 | 上传路径 | markdown文件：docs/zh-cn/application-dev/reference/apis
图片路径：docs/zh-cn/application-dev/reference/apis/figures，并在markdown文件中通过路径`![](figures/xxx.jpg)`或`![](figures/xxx.png)`引用。 | +| 3 | 文件命名 | 一个d.ts对应一个js api文档，文件名称应与模块名称保持一致，格式为：**js-apis-模块名.md**。
示例：
媒体@ohos.multimedia.audio，文件命名为：js-apis-audio.md
电话@ohos.telephony.sms，文件命名为：js-apis-sms.md | +| 4 | 目录修改 | 新增文件，需要修改对应的Readme，即`docs/zh-cn/application-dev/reference/apis/Readme-CN.md`。 | +| 5 | 文档结构 | - 模块说明
- 起始版本说明
- 导入模块/使用说明
- 接口（属性、方法、枚举、自定义类型）
描述顺序和代码保持一致，如果某些接口具有逻辑顺序，请注意排列。 | +| 6 | 接口版本说明 | 1. 每个模块要有起始版本说明，使用引用语法“>”对接口的起始版本进行说明。接口没有标记的，默认与模块同一个起始版本。
2. 已有模块新增接口使用\标签标记对应版本号。写法：`版本号+`
例如`7+`
示例：API 6已有的模块，在API 7新增了一个属性字段，则在属性后加标记，即newAttribute7+。
如果新增了一个方法，则在方法标题后增加标记，即 sim.getSimIccId7+，interface、class、枚举等同理。 | +| 7 | 废弃接口说明 | 废弃内容不能直接删去，在废弃内容后面加标注deprecated，并使用“>”引用语法建议使用的替代方式，加上对应的链接。
示例：abandonmentMethod(deprecated)
> 从API Version 7 开始不再维护，建议使用[newMethod]\(#newmethod)替代。 | +| 8 | 权限说明 | 与代码保持一致，下沉到各个方法、枚举、属性字段中。
1. 如果仅系统应用可申请，格式：
**需要权限：** ohos.permission.xxxx，仅系统应用可用。
2. 如果该权限所有应用可申请，格式：
**需要权限：** ohos.permission.xxxx
3. 如果该接口涉及多个权限，则采用“和、或”进行分割，格式：
**需要权限：** ohos.permission.A 和 ohos.permission.B
**需要权限：** ohos.permission.A 或 ohos.permission.B | +| 9 | @syscap | 1. 每个方法都需要进行描述，格式：
**系统能力**：SystemCapability.xxx.xxx
2. 每个表格（属性、枚举、常量、变量）可统一进行说明，分两种情况：
1）每个表格下系统能力无差异的，同方法的写法：
**系统能力**：SystemCapability.xxx.xxx
2）有差异的：在每一个表格项里进行描述。 | +| 10 | @system api | 1. 如果某个模块全部接口均为system api，则在模块开头的版本说明下一行，增加：
- 本模块接口为系统接口。
2. 如果某个接口为system api，仅供OEM厂商使用，则需要在描述中增加：
**系统接口：** 此接口为系统接口。 | +| 11 | @FAModelOnly
@StageModelOnly | 1. 如果某个模块均只针对某模型实现，则在模块开头的版本说明下一行，增加：
- 本模块接口仅可在FA模型/Stage模型下使用。
2. 如果某个接口只针对某模型实现，则需要在描述中增加：
**模型约束：** 此接口仅可在FA模型/Stage模型下使用。 | +| 12 | 异步接口说明（callback、Promise） | 对于callback、Promise在方法描述、参数说明、返回值说明的具体描述要求如下：
**callback**的固定句式：
方法介绍：xxx（方法描述）。使用callback异步回调。
参数说明：
**callback\**：回调函数。返回true表示xxx；返回false表示xxx。
**callback\**：回调函数，返回xxx。例如”回调函数，返回音频采集器对象。“
**AsyncCallback\**：回调函数。当具体的操作（视具体接口功能描述）成功，err为undefined，否则为错误对象。
**AsyncCallback\**：回调函数。当具体的操作（视具体接口功能描述）成功，err为undefined，data为获取到的Object x；否则为错误对象。
**Promise**的固定句式：
方法介绍：xxx（方法描述）。使用Promise异步回调。
参数说明：
**Promise\**：Promise对象。返回true表示xxx；返回false表示xxx。
**Promise\**：Promise对象，返回xxx。例如”Promise对象，返回音频采集器对象。“
**Promise\**：Promise对象。无返回结果的Promise对象。 | +| 13 | 示例代码语言 | 所有的示例代码采用代码块的样式，并标记开发语言。
JS和eTS通用的标注`js`；仅eTS可用的，标注`ts`。 | +| 14 | 链接写法 | 格式：[链接文字]\(链接内容)
跨文件夹链接：[指南]\(\.\./../xxx/xxx.md)，一个`../`表示上移一层文件夹。
页面内链接：[接口A7+]\(#xxxa7)，页面内链接和需要链接到的标题保持一致，全小写无特殊符号无标签。 | 下面进入具体每个API的写作。