Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
OpenHarmony
Docs
提交
57b45e35
D
Docs
项目概览
OpenHarmony
/
Docs
大约 1 年 前同步成功
通知
159
Star
292
Fork
28
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
D
Docs
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
未验证
提交
57b45e35
编写于
9月 08, 2022
作者:
Z
zengyawen
提交者:
Gitee
9月 08, 2022
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
update zh-cn/contribute/template/js-template.md.
Signed-off-by:
N
zengyawen
<
zengyawen1@huawei.com
>
上级
dc19a58a
变更
1
显示空白变更内容
内联
并排
Showing
1 changed file
with
14 addition
and
14 deletion
+14
-14
zh-cn/contribute/template/js-template.md
zh-cn/contribute/template/js-template.md
+14
-14
未找到文件。
zh-cn/contribute/template/js-template.md
浏览文件 @
57b45e35
# API接口说明模板
## 总体写作说明
> **说明:** <br/>所有的写作说明,在完成写作后,都要删除。
| | 说明项 | 细则 |
| ---- | --------------------------------- | ------------------------------------------------------------ |
| 1 | 客户化写作基本要求 |
**写作中,请变身开发者,对于开发者使用该API时所需的使用场景、参数选取原则、开发建议/经验、示例等信息进行清晰描述,达到指导开发者顺利使用本API进行开发的目标。**
|
| 2 | |
**所有的写作说明,在完成写作后,都要删除。**
|
| 3 | 上传路径 | markdown文件:docs/zh-cn/application-dev/reference/apis
<br>
图片路径:docs/zh-cn/application-dev/reference/apis/figures,并在markdown文件中通过路径
`![](figures/xxx.jpg)`
或
`![](figures/xxx.png)`
引用。 |
| 4 | 文件命名 | 一个d.ts对应一个js api文档,文件名称应与模块名称保持一致,格式为:
**js-apis-模块名.md**
。
<br/>示例:<br/>媒体@ohos.multimedia.audio,文件命名为:js-apis-audio.md<br/>
电话@ohos.telephony.sms,文件命名为:js-apis-sms.md |
| 5 | 目录修改 | 新增文件,需要修改对应的Readme,即
`docs/zh-cn/application-dev/reference/apis/Readme-CN.md`
。 |
| 6 | 文档结构 | - 模块说明
<br/>
- 起始版本说明
<br/>
- 导入模块/使用说明
<br/>
- 接口(属性、方法、枚举、自定义类型)
<br/>
描述顺序和代码保持一致,如果某些接口具有逻辑顺序,请注意排列。 |
| 7 | 接口版本说明 | 1. 每个模块要有起始版本说明,使用引用语法“>”对接口的起始版本进行说明。接口没有标记的,默认与模块同一个起始版本。
<br/>
2. 已有模块新增接口使用
\<
sup>标签标记对应版本号。写法:
`<sup>版本号+</sup>`
<br/>
例如
`<sup>7+</sup>`
<br/>
示例:API 6已有的模块,在API 7新增了一个属性字段,则在属性后加标记,即newAttribute
<sup>
7+
</sup>
。
<br/>
如果新增了一个方法,则在方法标题后增加标记,即 sim.getSimIccId
<sup>
7+
</sup>
,interface、class、枚举等同理。 |
| 8 | 废弃接口说明 | 废弃内容不能直接删去,在废弃内容后面加标注deprecated,并使用“>”引用语法建议使用的替代方式,加上对应的链接。
<br/>
示例:abandonmentMethod
<sup>
(deprecated)
</sup><br/>
> 从API Version 7 开始不再维护,建议使用[newMethod]
\(
#newmethod)替代。 |
| 9 | 权限说明 | 与代码保持一致,下沉到各个方法、枚举、属性字段中。
<br/>
1. 如果仅系统应用可申请,格式:
<br/>
**需要权限:**
ohos.permission.xxxx,仅系统应用可用。
<br/>
2. 如果该权限所有应用可申请,格式:
<br/>
**需要权限:**
ohos.permission.xxxx
<br/>
3. 如果该接口涉及多个权限,则采用“和、或”进行分割,格式:
<br/>
**需要权限:**
ohos.permission.A 和 ohos.permission.B
<br/>
**需要权限:**
ohos.permission.A 或 ohos.permission.B |
| 10 | @syscap | 1. 每个方法都需要进行描述,格式:
<br/>
**系统能力**
:SystemCapability.xxx.xxx
<br/>
2. 每个表格(属性、枚举、常量、变量)可统一进行说明,分两种情况:
<br/>
1)每个表格下系统能力无差异的,同方法的写法:
<br/>
**系统能力**
:SystemCapability.xxx.xxx
<br/>
2)有差异的:在每一个表格项里进行描述。 |
| 11 | @system api | 1. 如果某个模块全部接口均为system api,则在模块开头的版本说明下一行,增加:
<br/>
- 本模块接口为系统接口。
<br/>
2. 如果某个接口为system api,仅供OEM厂商使用,则需要在描述中增加:
<br/>
**系统接口:**
此接口为系统接口。 |
| 12 | @FAModelOnly
<br/>@StageModelOnly | 1. 如果某个模块均只针对某模型实现,则在模块开头的版本说明下一行,增加:<br/> - 本模块接口仅可在FA模型/Stage模型下使用。<br/>2. 如果某个接口只针对某模型实现,则需要在描述中增加:<br/>
**模型约束:**
此接口仅可在FA模型/Stage模型下使用。 |
| 13 | 异步接口说明(callback、Promise) | 对于callback、Promise在方法描述、参数说明、返回值说明的具体描述要求如下:
<br/>
**callback**
的固定句式:
<br/>
方法介绍:xxx(方法描述)。使用callback异步回调。
<br/>
参数说明:
<br/>
**callback\<boolean>**
:回调函数。返回true表示xxx;返回false表示xxx。
<br/>
**callback\<Object>**
:回调函数,返回xxx。例如”回调函数,返回音频采集器对象。“
<br/>
**AsyncCallback\<void>**
:回调函数。当具体的操作(视具体接口功能描述)成功,err为undefined,否则为错误对象。
<br/>
**AsyncCallback\<Object x>**
:回调函数。当具体的操作(视具体接口功能描述)成功,err为undefined,data为获取到的Object x;否则为错误对象。
<br/>
**Promise**
的固定句式:
<br/>
方法介绍:xxx(方法描述)。使用Promise异步回调。
<br/>
参数说明:
<br/>
**Promise\<boolean>**
:Promise对象。返回true表示xxx;返回false表示xxx。
<br/>
**Promise\<Object>**
:Promise对象,返回xxx。例如”Promise对象,返回音频采集器对象。“
<br/>
**Promise\<void>**
:Promise对象。无返回结果的Promise对象。 |
| 14 | 示例代码语言 | 所有的示例代码采用代码块的样式,并标记开发语言。
<br/>
JS和eTS通用的标注
`js`
;仅eTS可用的,标注
`ts`
。 |
| 15 | 链接写法 | 格式:[链接文字]
\(
链接内容)
<br/>
跨文件夹链接:[指南]
\(\.\.
/../xxx/xxx.md),一个
`../`
表示上移一层文件夹。
<br/>
页面内链接:[接口A
<sup>
7+
</sup>
]
\(
#xxxa7),页面内链接和需要链接到的标题保持一致,全小写无特殊符号无标签。 |
| 2 | 上传路径 | markdown文件:docs/zh-cn/application-dev/reference/apis
<br>
图片路径:docs/zh-cn/application-dev/reference/apis/figures,并在markdown文件中通过路径
`![](figures/xxx.jpg)`
或
`![](figures/xxx.png)`
引用。 |
| 3 | 文件命名 | 一个d.ts对应一个js api文档,文件名称应与模块名称保持一致,格式为:
**js-apis-模块名.md**
。
<br/>示例:<br/>媒体@ohos.multimedia.audio,文件命名为:js-apis-audio.md<br/>
电话@ohos.telephony.sms,文件命名为:js-apis-sms.md |
| 4 | 目录修改 | 新增文件,需要修改对应的Readme,即
`docs/zh-cn/application-dev/reference/apis/Readme-CN.md`
。 |
| 5 | 文档结构 | - 模块说明
<br/>
- 起始版本说明
<br/>
- 导入模块/使用说明
<br/>
- 接口(属性、方法、枚举、自定义类型)
<br/>
描述顺序和代码保持一致,如果某些接口具有逻辑顺序,请注意排列。 |
| 6 | 接口版本说明 | 1. 每个模块要有起始版本说明,使用引用语法“>”对接口的起始版本进行说明。接口没有标记的,默认与模块同一个起始版本。
<br/>
2. 已有模块新增接口使用
\<
sup>标签标记对应版本号。写法:
`<sup>版本号+</sup>`
<br/>
例如
`<sup>7+</sup>`
<br/>
示例:API 6已有的模块,在API 7新增了一个属性字段,则在属性后加标记,即newAttribute
<sup>
7+
</sup>
。
<br/>
如果新增了一个方法,则在方法标题后增加标记,即 sim.getSimIccId
<sup>
7+
</sup>
,interface、class、枚举等同理。 |
| 7 | 废弃接口说明 | 废弃内容不能直接删去,在废弃内容后面加标注deprecated,并使用“>”引用语法建议使用的替代方式,加上对应的链接。
<br/>
示例:abandonmentMethod
<sup>
(deprecated)
</sup><br/>
> 从API Version 7 开始不再维护,建议使用[newMethod]
\(
#newmethod)替代。 |
| 8 | 权限说明 | 与代码保持一致,下沉到各个方法、枚举、属性字段中。
<br/>
1. 如果仅系统应用可申请,格式:
<br/>
**需要权限:**
ohos.permission.xxxx,仅系统应用可用。
<br/>
2. 如果该权限所有应用可申请,格式:
<br/>
**需要权限:**
ohos.permission.xxxx
<br/>
3. 如果该接口涉及多个权限,则采用“和、或”进行分割,格式:
<br/>
**需要权限:**
ohos.permission.A 和 ohos.permission.B
<br/>
**需要权限:**
ohos.permission.A 或 ohos.permission.B |
| 9 | @syscap | 1. 每个方法都需要进行描述,格式:
<br/>
**系统能力**
:SystemCapability.xxx.xxx
<br/>
2. 每个表格(属性、枚举、常量、变量)可统一进行说明,分两种情况:
<br/>
1)每个表格下系统能力无差异的,同方法的写法:
<br/>
**系统能力**
:SystemCapability.xxx.xxx
<br/>
2)有差异的:在每一个表格项里进行描述。 |
| 10 | @system api | 1. 如果某个模块全部接口均为system api,则在模块开头的版本说明下一行,增加:
<br/>
- 本模块接口为系统接口。
<br/>
2. 如果某个接口为system api,仅供OEM厂商使用,则需要在描述中增加:
<br/>
**系统接口:**
此接口为系统接口。 |
| 11 | @FAModelOnly
<br/>@StageModelOnly | 1. 如果某个模块均只针对某模型实现,则在模块开头的版本说明下一行,增加:<br/> - 本模块接口仅可在FA模型/Stage模型下使用。<br/>2. 如果某个接口只针对某模型实现,则需要在描述中增加:<br/>
**模型约束:**
此接口仅可在FA模型/Stage模型下使用。 |
| 12 | 异步接口说明(callback、Promise) | 对于callback、Promise在方法描述、参数说明、返回值说明的具体描述要求如下:
<br/>
**callback**
的固定句式:
<br/>
方法介绍:xxx(方法描述)。使用callback异步回调。
<br/>
参数说明:
<br/>
**callback\<boolean>**
:回调函数。返回true表示xxx;返回false表示xxx。
<br/>
**callback\<Object>**
:回调函数,返回xxx。例如”回调函数,返回音频采集器对象。“
<br/>
**AsyncCallback\<void>**
:回调函数。当具体的操作(视具体接口功能描述)成功,err为undefined,否则为错误对象。
<br/>
**AsyncCallback\<Object x>**
:回调函数。当具体的操作(视具体接口功能描述)成功,err为undefined,data为获取到的Object x;否则为错误对象。
<br/>
**Promise**
的固定句式:
<br/>
方法介绍:xxx(方法描述)。使用Promise异步回调。
<br/>
参数说明:
<br/>
**Promise\<boolean>**
:Promise对象。返回true表示xxx;返回false表示xxx。
<br/>
**Promise\<Object>**
:Promise对象,返回xxx。例如”Promise对象,返回音频采集器对象。“
<br/>
**Promise\<void>**
:Promise对象。无返回结果的Promise对象。 |
| 13 | 示例代码语言 | 所有的示例代码采用代码块的样式,并标记开发语言。
<br/>
JS和eTS通用的标注
`js`
;仅eTS可用的,标注
`ts`
。 |
| 14 | 链接写法 | 格式:[链接文字]
\(
链接内容)
<br/>
跨文件夹链接:[指南]
\(\.\.
/../xxx/xxx.md),一个
`../`
表示上移一层文件夹。
<br/>
页面内链接:[接口A
<sup>
7+
</sup>
]
\(
#xxxa7),页面内链接和需要链接到的标题保持一致,全小写无特殊符号无标签。 |
下面进入具体每个API的写作。
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录