diff --git a/zh-cn/contribute/template/ts-template.md b/zh-cn/contribute/template/ts-template.md index 1ce1f8012ce75c6bc2a9fa783c53fe706aeddb15..ea914f9b3dc1a69d810a6516813142a378b35144 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 > // 必选项。