From e19fb45efa8fa09015a9740ce67174b97a6b59a7 Mon Sep 17 00:00:00 2001 From: HelloCrease Date: Sat, 27 Aug 2022 11:09:46 +0800 Subject: [PATCH] update ts template Signed-off-by: HelloCrease --- zh-cn/contribute/template/ts-template.md | 120 +++++++++-------------- 1 file changed, 46 insertions(+), 74 deletions(-) diff --git a/zh-cn/contribute/template/ts-template.md b/zh-cn/contribute/template/ts-template.md index 1ce1f8012c..ea914f9b3d 100644 --- a/zh-cn/contribute/template/ts-template.md +++ b/zh-cn/contribute/template/ts-template.md @@ -14,8 +14,8 @@ | 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 | @system api | 1. 如果某个模块全部接口均为system api，则在模块开头的版本说明下一行，增加：
- 本模块接口为系统接口。
2. 如果某个接口为system api，仅供OEM厂商使用，则需要在描述中增加：
**系统接口：** 此接口为系统接口。 | -| 14 | 示例代码语言 | 所有的示例代码采用代码块的样式，并标记开发语言为ts，且在示例代码最开始添加注释`// xxx.ets` | -| 15 | 链接写法 | 格式：[链接文字]\(链接内容)
跨文件夹链接：[指南]\(\.\./../xxx/xxx.md)，一个`../`表示上移一层文件夹。
页面内链接：[接口A7+]\(#xxxa7)，页面内链接和需要链接到的标题保持一致，全小写无特殊符号无标签。 | +| 11 | 示例代码语言 | 所有的示例代码采用代码块的样式，并标记开发语言为ts，且在示例代码最开始添加注释`// xxx.ets` | +| 12 | 链接写法 | 格式：[链接文字]\(链接内容)
跨文件夹链接：[指南]\(\.\./../xxx/xxx.md)，一个`../`表示上移一层文件夹。
页面内链接：[接口A7+]\(#xxxa7)，页面内链接和需要链接到的标题保持一致，全小写无特殊符号无标签。 | 下面进入具体每个API的写作。 @@ -66,31 +66,22 @@ import Curves from '@ohos.curves' > *写作说明* > -> 3.1 - 可选，若该模块的使用无需申请权限，则删除。 -> -> 3.2 - 描述清楚需要申请的权限名称，并给出对应的示例代码，具体形式请参考[权限申请声明](../application-dev/security/accesstoken-guidelines.md)。 - - 示例： - -使用网络图片时，需要在config.json或者module.json59+中添加网络使用权限ohos.permission.INTERNET。 - -module.json5文件示例： +> 1. 可选，若该模块的使用无需申请权限，则删除。 +> 2. 如果仅系统应用可申请，格式： +> **需要权限：** ohos.permission.xxxx，仅系统应用可用。 +> 3. 如果该权限所有应用可申请，格式： +> **需要权限：** ohos.permission.xxxx +> 4. 如果该接口涉及多个权限，则采用“和、或”进行分割，格式： +> **需要权限：** ohos.permission.A 和 ohos.permission.B +> **需要权限：** ohos.permission.A 或 ohos.permission.B -``` -"abilities": [ - { - ... - "permissions": ["ohos.permission.INTERNET"], - ... - } -] -``` + ohos.permission.INTERNET，具体申请方式请参考[权限申请声明](../application-dev/security/accesstoken-guidelines.md)。。 ## 子组件 > *写作说明* > -> 4.1 - 可选，若组件不包含子组件，则删除。 +> 1. 可选，若组件不包含子组件，则删除。 示例：可以包含子组件。 @@ -98,23 +89,15 @@ module.json5文件示例： >*写作说明* > ->4.3 - 若该模块为系统内置组件，则必选，如果没有接口可删除此二级标题。 -> ->4.4 - 方法具体的调用形式和d.ts保持一致，需要包括参数名、参数类型。 -> ->4.5 - 若该参数为可选，则在参数名后添加问号（？）做以标识。 -> ->4.6 - 方法调用涉及到的符号均为英文符号，注意在冒号（：）后添加空格。 -> ->4.7 - 删除方法调用描述后的分号（；）。 -> ->4.8 - 参数类型如果为自定义类型（对象、枚举等），若该类型首次出现，以无序列表的形式，在此描述。若该类型在其他模块已做说明，则建立相对链接。 -> ->4.9 - 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符< > 。 -> ->4.10 - 注意：组件接口中的方法无返回值，不以三级/二级标题形式体现，其余要求同[方法](#方法)。 -> ->4.11 - 注意：默认值需要在描述中换行体现。 +>1. 若该模块为系统内置组件，则必选，如果没有接口可删除此二级标题。 +>2. 方法具体的调用形式和d.ts保持一致，需要包括参数名、参数类型。 +>3. 若该参数为可选，则在参数名后添加问号（？）做以标识。 +>4. 方法调用涉及到的符号均为英文符号，注意在冒号（：）后添加空格。 +>5. 删除方法调用描述后的分号（；）。 +>6. 参数类型如果为自定义类型（对象、枚举等），若该类型首次出现，以无序列表的形式，在此描述。若该类型在其他模块已做说明，则建立相对链接。 +>7. 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符< > 。 +>8. 注意：组件接口中的方法无返回值，不以三级/二级标题形式体现，其余要求同[方法](#方法)。 +>9. 注意：默认值需要在描述中换行体现。 如果接口有两个及以上的创建方法，此处给出接口不同创建方式的差异说明。 @@ -135,11 +118,9 @@ module.json5文件示例： > *写作说明* > -> 5.1 - 可选，如果没有属性可删除此二级标题。 -> -> 5.2 - 类型如果为自定义类型（对象、枚举等）需要建立链接到对应的interface或enum中。 -> -> 5.3 - 注意：默认值需要在描述中换行说明。 +> 1. 可选，如果没有属性可删除此二级标题。 +> 2. 类型如果为自定义类型（对象、枚举等）需要建立链接到对应的interface或enum中。 +> 3. 注意：默认值需要在描述中换行说明。 此处需说明该组件是否支持通用属性。 @@ -155,10 +136,8 @@ module.json5文件示例： > *写作说明* > -> 6.1 - 可选，如果没有事件可删除此二级标题。 -> -> 6.2 - 类型如果为自定义类型（对象、枚举等）需要建立链接到对应的interface或enum中。若该类型首次出现，以二级标题的形式，在该事件下方描述。若该类型在其他模块已做说明，则建立相对链接。 -> +> 1. 可选，如果没有事件可删除此二级标题。 +> 2. 类型如果为自定义类型（对象、枚举等）需要建立链接到对应的interface或enum中。若该类型首次出现，以二级标题的形式，在该事件下方描述。若该类型在其他模块已做说明，则建立相对链接。 此处需说明该组件是否支持通用事件。 @@ -168,8 +147,6 @@ module.json5文件示例： 此处给出每个事件的具体调用形式，要求同[方法](#方法)。 -例如： - ### onSubmit onSubmit(callback: (value: string) => void) @@ -186,21 +163,21 @@ onSubmit(callback: (value: string) => void) > *写作说明* > -> 7.1 - 可选，如果没有可删除。如果有多个方法，请分多个二级内容描述，并使用“##”自行新建二级标题。 +> 1. 可选，如果没有可删除。如果有多个方法，请分多个二级内容描述，并使用“##”自行新建二级标题。 > -> 7.2 - 二级标题名为方法名，采用导入类.方法名的形式。 +> 2. 二级标题名为方法名，采用导入类.方法名的形式。 > -> 示例： mediaquery.matchMediaSync +> 示例： mediaquery.matchMediaSync > -> 7.3 - **方法具体调用形式**：和d.ts保持一致，需要包括参数类型、参数名、返回值类型。 +> 3. **方法具体调用形式**：和d.ts保持一致，需要包括参数类型、参数名、返回值类型。 > -> 示例：matchMediaSync(condition: string): MediaQueryListener +> 示例：matchMediaSync(condition: string): MediaQueryListener > -> 7.4 - 尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符< > 。 +> 4. 尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“\<>”或使用转义字符< > 。 > -> 7.5 - **方法描述**：对方法实现的功能进行描述，包括其使用的前提条件（*如：在xx方法调用后才能调用、需要确保网络已连接……*）、使用之后的影响（*如：调用该接口后再进行xx将不起效*）、**权限限制**、**系统能力**等。 +> 5. **方法描述**：对方法实现的功能进行描述，包括其使用的前提条件（*如：在xx方法调用后才能调用、需要确保网络已连接……*）、使用之后的影响（*如：调用该接口后再进行xx将不起效*）、**权限限制**、**系统能力**等。 > -> 7.6 - **表格内换行**：markdown语法中，换行采用特殊标记
+> 6. **表格内换行**：markdown语法中，换行采用特殊标记
在此处给出方法的具体调用形式：（如果是静态方法需说明） 方法名称(参数1名称：参数1类型，参数2名称：参数2类型，……)：返回值类型 @@ -239,13 +216,10 @@ onSubmit(callback: (value: string) => void) > *写作说明* > -> 8.1 - 可选，如果没有可删除。如果有多个，请分多个二级内容描述，并使用“##”自行新建二级标题。 -> -> 8.2 - 二级标题名为class的名称。 -> -> 8.3 - 如果该Class既有属性，又有方法，需要先进行属性的写作，并使用“###”三级标题。 -> -> 8.4 - 如果该Class只有属性，那么不需要新建三级标题，直接使用表格陈列属性。 +> 1. 可选，如果没有可删除。如果有多个，请分多个二级内容描述，并使用“##”自行新建二级标题。 +> 2. 二级标题名为class的名称。 +> 3. 如果该Class既有属性，又有方法，需要先进行属性的写作，并使用“###”三级标题。 +> 4. 如果该Class只有属性，那么不需要新建三级标题，直接使用表格陈列属性。 此处说明该类的实现功能、使用场景、约束限制等。 @@ -253,7 +227,7 @@ onSubmit(callback: (value: string) => void) > *写作说明* > -> 8.5 - 必选，以代码段的形式说明类的创建方式 +> 1. 必选，以代码段的形式说明类的创建方式 示例： @@ -265,21 +239,20 @@ patternLockController: PatternLockController = new PatternLockController() > *写作说明* > -> 8.6 - 可选，除标题使用三级标题外，其余要求同[属性](#属性)。 +> 1. 可选，除标题使用三级标题外，其余要求同[属性](#属性)。 ### Class中的方法 > *写作说明* > -> 8.7 - 可选，标题名为方法名，使用三级标题，**没有前缀**。示例：scrollTo。 -> -> 8.8 - 无需提供示例代码和示例图，其他要求同[方法](#方法)。 +> 1. 可选，标题名为方法名，使用三级标题，**没有前缀**。示例：scrollTo。 +> 2. 无需提供示例代码和示例图，其他要求同[方法](#方法)。 ## 枚举 > *写作说明* > -> 9.1 - 可选，以二级标题的形式体现，在涉及到的方法、属性后就近描述。 +> 1. 可选，以二级标题的形式体现，在涉及到的方法、属性后就近描述。 ### FlexDirection枚举说明 @@ -294,7 +267,7 @@ patternLockController: PatternLockController = new PatternLockController() > *写作说明* > -> 10.1 - 可选，以二级标题的形式体现。 +> 1. 可选，以二级标题的形式体现，在涉及到的方法、属性后就近描述。 ### MouseEvent对象说明 @@ -310,9 +283,8 @@ patternLockController: PatternLockController = new PatternLockController() > *写作说明* > -> 11.1 - 必选，以二级/三级标题的形式体现，需要示例代码和示例图。 -> -> 11.2 - 若该组件/模块功能复杂，则按照功能点划分，按照三级标题的形式分块呈现示例代码和示例图。 +> 1. 必选，以二级/三级标题的形式体现，需要示例代码和示例图。 +> 2. 若该组件/模块功能复杂，则按照功能点划分，按照三级标题的形式分块呈现示例代码和示例图。 > > ```tsx > // 必选项。 -- GitLab