From 63c0e8d69e55a7a8090bf93886a6fcf0eaacf0ed Mon Sep 17 00:00:00 2001 From: zengyawen Date: Mon, 21 Feb 2022 06:37:26 +0000 Subject: [PATCH] =?UTF-8?q?=E6=A8=A1=E6=9D=BF=E6=B7=BB=E5=8A=A0syscap=20Si?= =?UTF-8?q?gned-off-by:=20zengyawen=20?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- zh-cn/contribute/template/js-template.md | 89 +++++++++++------------- 1 file changed, 42 insertions(+), 47 deletions(-) diff --git a/zh-cn/contribute/template/js-template.md b/zh-cn/contribute/template/js-template.md index 24f948162f..e4609e7873 100644 --- a/zh-cn/contribute/template/js-template.md +++ b/zh-cn/contribute/template/js-template.md @@ -7,10 +7,8 @@ > 0.2 - 上传路径：docs/zh-cn/application-dev/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 +> 媒体@ohos.multimedia.audio，文件命名为：js-apis-audio.md +> 电话@ohos.telephony.sms，文件命名为：js-apis-sms.md > > 0.4 - 新增文件，需要修改对应的Readme，即docs/zh-cn/application-dev/reference/apis/Readme-CN.md。 > @@ -19,17 +17,15 @@ > 0.6 - 文档标题为一级标题；namespace下的属性字段、function、class、interface、enum、type为二级标题；class下的属性、function为三级标题。 > > 0.7 - **对已有模块的新增接口标记起始版本：使用\标签，标记对应的版本号。** -> -> ​ 示例：API 6已有的模块，在API 7新增了一个属性字段，则在属性后加标记，即newAttribute7+。 -> -> ​ 如果新增了一个方法，则在方法标题后增加标记，即 sim.getSimIccId7+，interface、class、枚举等同理。 +> 示例：API 6已有的模块，在API 7新增了一个属性字段，则在属性后加标记，即newAttribute7+。 +> 如果新增了一个方法，则在方法标题后增加标记，即 sim.getSimIccId7+，interface、class、枚举等同理。 > > 0.8 - **废弃内容**：不能直接在文档上删去，在废弃内容后面加上标标注deprecated，并使用“>”引用语法建议使用的替代方式，加上对应的链接。 -> -> ​ 示例：abandonmentMethod(deprecated) +> 示例：abandonmentMethod(deprecated) > > > 从API Version 7 开始废弃，建议使用[newMethod](#newMethod)替代。 > +> 0.9 - **权限和syscap**：与代码保持一致，下沉到各个方法、枚举、属性字段中。 > 下面进入具体每个API的写作。 *** @@ -40,7 +36,8 @@ > 1.2 - 一个模块只会有一个起始版本。 > > 1.3 - 采用标准句式：“本模块首批接口从API version x开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。”x需要修改为对应的版本号。 -> + + > **说明** > @@ -48,16 +45,18 @@ 模块说明。此处对该模块提供的功能、使用场景和使用建议进行简要描述。 + + ## 导入模块 + > *写作说明* > > 2.1 - 根据实际情况填写导入模块。采用代码段的样式，给出import语句。 > > 2.2 - 如果没有导入模块，将“导入模块”修改为“使用说明”。 +> 使用说明案例： +> 在使用AbilityContext的功能前，需要通过[getContext()](链接到对应的接口说明文件中.md)先获取Context对象。 > -> ​ 使用说明案例： -> -> ​ 在使用AbilityContext的功能前，需要通过[getContext()](链接到对应的接口说明文件中.md)先获取Context对象。 > ```js > import ability_featureAbility from '@ohos.ability.featureAbility'; > var context = ability_featureAbility.getContext(); @@ -66,12 +65,7 @@ ```js import call from '@ohos.telephony.call'; ``` -## 系统能力 -> *写作说明* -> -> 3.1 - 必选。 -> -示例：SystemCapability.BundleManager.BundleFramework + ## 属性 @@ -85,10 +79,10 @@ import call from '@ohos.telephony.call'; > > 4.4 - 对于可写属性：如果仅支持固定字段，需要进行说明。 -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------ | -| pluggedType | [BatteryPluggedType](#BatteryPluggedType) | 是 | 否 | 表示当前设备连接的充电器类型。 | -| isBatteryPresent | boolean | 是 | 否 | 表示当前设备是否支持电池或者电池是否在位。 | +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------------------------ | +| pluggedType | [BatteryPluggedType](#BatteryPluggedType) | 是 | 否 | 表示当前设备连接的充电器类型。
**系统能力**：SystemCapability.xxx.xxx（必选） | +| isBatteryPresent | boolean | 是 | 否 | 表示当前设备是否支持电池或者电池是否在位。
**系统能力**：SystemCapability.xxx.xxx（必选） | ## 枚举 @@ -100,9 +94,9 @@ import call from '@ohos.telephony.call'; 在此处给出该枚举类型的简要描述。如：表示连接的充电器类型的枚举。 -| 名称 | 值 | 说明 | -| ---- | ---- | -------------------------- | -| NONE | 1 | 表示连接的充电器类型未知。 | +| 名称 | 值 | 说明 | +| ---- | ---- | ------------------------------------------------------------ | +| NONE | 1 | 表示连接的充电器类型未知。
**系统能力**：SystemCapability.xxx.xxx（必选） | ## 方法 @@ -112,17 +106,17 @@ import call from '@ohos.telephony.call'; > > 6.2 - 二级标题名为方法名，采用导入类.方法名，如果是订阅方法，需要在方法名加上对应的订阅事件。 > -> ​ 示例： sim.getSimIccId -> -> ​ 订阅方法：sim.on('exampleEvent') +> 示例： sim.getSimIccId +> +> 订阅方法：sim.on('exampleEvent') > > 6.3 - **方法具体调用形式**：和d.ts保持一致，需要包括参数类型、参数名、返回值类型。 > -> ​ 示例：getNetworkState(slotId: number, callback: AsyncCallback\): void -> -> ​ 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\\<>”或使用转义字符\< \> 。 +> 示例：getNetworkState(slotId: number, callback: AsyncCallback\): void +> +> 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\\<>”或使用转义字符\< \> 。 > -> 6.4.1 - **方法描述**：对方法实现的功能进行描述，包括其使用的前提条件（*如：在xx方法调用后才能调用、需要确保网络已连接……*）、使用之后的影响（*如：调用该接口后再进行xx将不起效*）、权限限制等。 +> 6.4.1 - **方法描述**：对方法实现的功能进行描述，包括其使用的前提条件（*如：在xx方法调用后才能调用、需要确保网络已连接……*）、使用之后的影响（*如：调用该接口后再进行xx将不起效*）、**权限限制**、**系统能力**等。 > > 6.4.2 - **异步方法描述**：存在大量异步方法，其返回方式需要在方法描述处进行说明。通过注册回调函数获取？还是通过Promise获取？ > @@ -132,7 +126,9 @@ import call from '@ohos.telephony.call'; 在此处给出方法描述。说明请参考6.4.1和6.4.2。 -需要权限：ohos.permission.XXX（如不涉及可删除，如果是系统权限要说明） +**需要权限**：ohos.permission.xxx（如不涉及可删除，如果是系统权限要说明） + +**系统能力**：SystemCapability.xxx.xxx（必选） **参数：** （可选，如不涉及可删除） @@ -170,7 +166,7 @@ import call from '@ohos.telephony.call'; > > 7.3 - 如果该API中，既有属性，又有方法，需要先进行属性的写作，并使用“###”三级标题。 > -> ​ 如果该API中，只有属性，那么不需要新建三级标题，直接使用表格陈列属性，具体示例参考[CustomType](#CustomType)。 +> 如果该API中，只有属性，那么不需要新建三级标题，直接使用表格陈列属性，具体示例参考[CustomType](#CustomType)。 类描述/interface描述。如果有使用限制，需要在这个地方说明。比方说，是否有前提条件，是否需要通过什么方法先构造一个实例。 @@ -186,9 +182,9 @@ import call from '@ohos.telephony.call'; > > 7.4 - 标题名为方法名，使用三级标题，**没有前缀**。如果是订阅方法，需要在方法名加上对应的订阅事件。 > -> ​ 示例： getSimIccId -> -> ​ 订阅方法：on('exampleEvent') +> 示例： getSimIccId +> +> 订阅方法：on('exampleEvent') > > 其余要求请参考[方法](#方法)中的说明。 @@ -196,7 +192,9 @@ import call from '@ohos.telephony.call'; 在此处给出方法描述。说明请参考6.4.1和6.4.2。 -需要权限：ohos.permission.XXX（如不涉及可删除，如果是系统权限要说明） +**需要权限**：ohos.permission.xxx（如不涉及可删除，如果是系统权限要说明） + +**系统能力**：SystemCapability.xxx.xxx（必选） **参数：** （可选，如不涉及可删除） @@ -228,10 +226,7 @@ import call from '@ohos.telephony.call'; 仅有k-v键值对的自定义类型示例。 -| 名称 | 类型 | 可读 |可写| 说明 | -| ------------ | ---- | ---- | ---- | ---- | -| parameterUrl | string | 是 | 是 |媒体输出URI。支持：
1. 协议类型为“internal”的相对路径，示例如下：
临时目录：internal://cache/test.mp4

2. 文件的绝对路径，示例如下：
file:///data/data/ohos.xxx.xxx/files/test.mp4| -| parameterOne | [CustomEnum](#枚举) | 是 | 是 |属性描述，要求与参数说明类似。| - - - +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------ | ------------------- | ---- | ---- | ------------------------------------------------------------ | +| parameterUrl | string | 是 | 是 | 媒体输出URI。支持：
1. 协议类型为“internal”的相对路径，示例如下：
临时目录：internal://cache/test.mp4

2. 文件的绝对路径，示例如下：
file:///data/data/ohos.xxx.xxx/files/test.mp4
**系统能力**：SystemCapability.xxx.xxx（必选） | +| parameterOne | [CustomEnum](#枚举) | 是 | 是 | 属性描述，要求与参数说明类似。
**系统能力**：SystemCapability.xxx.xxx（必选） | \ No newline at end of file -- GitLab