ArkTS组件接口说明模板

总体写作说明

d.ts标签与文档字段的对应关系

以下字段，除版本说明外，均需下沉到每一个接口中。

如果是属性、interface表格，字段全表统一无差异，可统一写在表格上方；如果有一个不一致，需全部拆开，写到每一行的“说明”里。

下面进入具体每个组件接口的写作。

文档标题

写作说明

1. 文档标题：作为文档标题，要求使用中文短语概括本组件功能；但如果部分概念使用英文更便于开发者理解，可以直接使用。如Button、Slider等。
2. 标题层级：文档标题为一级标题，使用#；其他字段如function、class、interface、enum、type为二级标题，使用##；class下的属性、function为三级标题，使用###。
3. 起始版本说明：使用markdown的引用语法“>”对接口的起始版本进行说明，说明后需要换行。
   版本说明统一放在模块描述之后。一个模块只会有一个起始版本。
   采用标准句式：“本模块首批接口从API version x开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。”x需要修改为对应的版本号。

模块描述。此处对该模块的定义、功能、使用场景、使用建议进行描述，采用如下固定句式。

（模块介绍，可选）xxx是xxx。

（功能描述，必选）提供xxx能力，包括xxx、xxx等。——当模块名不够语义化时，推荐此句式。

或 xxx组件/方法，用于xxx、xxx。——当模块名已经表达了清晰的语义时，推荐此句式。

（使用场景，可选）当需要xxx时，使用本模块xxx方法/本组件。

（使用建议或注意事项，可选）本模块可与xxx联合使用，以提升开发效率……。

举例1：Marquee

跑马灯组件，用于滚动展示一段单行文本，仅当文本内容宽度超过跑马灯组件宽度时滚动。

举例2：SideBarContainer

提供侧边栏可以显示和隐藏的侧边栏容器，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。

说明：

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

导入模块

写作说明

1. 可选，若该模块为组件和通用方法，则删除此项。
2. 若该模块为需要导入的API接口，必选。
3. 根据实际情况填写导入模块。采用代码段的样式，给出import语句。

import { font } from '@kit.ArkUI';

子组件

写作说明

1. 若该模块为系统内置组件，且组件包含子组件，必选。
2. 若子组件在使用时存在约束限制，需在此说明。

示例：可以包含子组件。

接口

写作说明

1. 若该模块为系统内置组件，则必选，如果没有接口可删除此二级标题。
2. 方法具体的调用形式和d.ts保持一致，需要包括参数名和参数类型。
3. 参数描述需要包括：参数的含义与用途、什么场景下使用该参数、选取建议、参数间关联关系等。
4. 参数取值说明需要包括：取值范围、单位、默认值、取值原则或建议值；边界值涉及限制/异常时，需讲明具体场景；如果有固定格式，需要给出格式样例，尤其是URI。
5. 若该参数为可选，则在参数名后添加问号（？）做以标识。
6. 方法调用涉及到的符号均为英文符号，注意在冒号（：）后添加空格。
7. 删除方法调用描述后的分号（；）。
8. 参数类型如果为自定义类型（对象、枚举等），若该类型首次出现，以二级标题的形式在此描述。若该类型在其他模块已做说明，则建立相对链接。
9. 注意：尖括号<>可能会被识别为标签，导致界面显示失效，可增加一个\，以保证界面正常显示，如“<>”或使用转义字符&lt; &gt; 。
10. 注意：组件接口中的方法无返回值，不以三级/二级标题形式体现，其余要求同方法。
11. 注意：默认值/单位/取值范围需要在描述中换行体现。

如果接口有两个及以上的创建方法，此处给出接口不同创建方式的差异说明。

此处给出该接口方法的具体调用形式。为：方法名称(参数1名称：参数1类型，参数2名称：参数2类型，……)。
如果接口涉及多个方法，则顺次描写，并将方法名称置为3级标题。

示例：

Column(value?:&nbsp;{space?: string&nbsp;|&nbsp;number})

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

属性

写作说明

1. 可选，如果没有属性可删除此二级标题。
2. 属性方法具体的调用形式和d.ts保持一致，需要包括参数名、参数类型。
3. 将属性方法的名称置为三级标题。
4. 类型如果为自定义类型（对象、枚举等）需要建立链接到对应的interface或enum中。
5. 注意：默认值/单位/取值范围需要在描述中换行说明。

若该模块为系统内置组件，则此处需说明该组件是否支持通用属性。

示例：

grayscale(value: number)

为组件添加灰度效果。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

事件

写作说明

1. 可选，如果没有事件可删除此二级标题。
2. 事件方法具体的调用形式和d.ts保持一致，需要包括参数名、参数类型。
3. 类型如果为自定义类型（对象、枚举等）需要建立链接到对应的interface或enum中。若该类型首次出现，以二级标题的形式，在该事件下方描述。若该类型在其他模块已做说明，则建立相对链接。

若该模块为系统内置组件，则此处需说明该组件是否支持通用事件。

示例：

除支持通用事件（通用事件需添加相对链接）外，还支持如下事件：

onSubmit(callback: (value: string) => void)

点击搜索图标、搜索按钮或者按下软键盘搜索按钮时触发。

参数：

方法

写作说明

1. 可选，如果没有可删除。写作要求同API接口中方法说明。
2. 无需体现示例代码。

Class

写作说明

1. 可选，如果没有可删除。如果有多个，请分多个二级内容描述，并使用“##”自行新建二级标题。
2. 二级标题名为class、interface的名称。
3. 如果该API中，既有属性，又有方法，需要先进行属性的写作，并使用“###”三级标题。 如果该API中，只有属性，那么不需要新建三级标题，直接使用表格陈列属性。

属性

写作说明

1. 可选，如果没有可删除。写作要求同API接口中属性说明。

Class中的方法

写作说明

1. 可选，如果没有可删除。写作要求同API接口中方法说明。

枚举

写作说明

1. 可选，如果没有可删除。写作要求同API接口中枚举说明。

Type

写作说明

1. 可选，如果没有可删除。写作要求同API接口中Type说明。

示例

此处说明该示例的应用效果。

写作说明

1. 必选，以二级/三级标题的形式体现，需要示例代码和示例图。
2. 若该组件/模块功能复杂，则按照功能点划分，按照三级标题的形式分块呈现示例代码和示例图。

> // 必选项。
> 
> // 所有的示例代码需要进行自检。
> // 不能出现缺符号、变量前后不一致等低错。
> // 所有的使用到的变量要进行声明。
> // 所有示例代码均需要添加语言标记。
> 
> // 不允许直接写参数名，必须是可使用、易替代的实际用例。如果非用户自定义填写，需通过注释进行说明。
> // 例如：var result = xxx.createExample(parameterOne); // parameterOne由扫描自动获取
> 
> // 示例图布局清晰，配色简洁大方，图片有版权。
> 
> // 注释要精简、突出要点。需提供注释的典型场景还有：
> // 1. 当代码不能说明变量命名的具体含义，或不能说明代码逻辑时，必须提供注释。
> // 2. 涉及到复杂算法或特殊语法时，必须提供注释。
> ```

示例：

```ts
// xxx.ets
@Entry
@Component
struct CheckboxExample {
  build() {
    Row() {
      // 生成一个多选框，默认选中，点击可显示多选框状态
      Checkbox({name: 'checkbox1',  group: 'checkboxGroup'})
        .select(true)
        .selectedColor(0xed6f21)
        .onChange((value: boolean) => {
          console.info('Checkbox1 change is'+ value)
        })
      // 生成一个多选框，默认不选中，点击可显示多选框状态
      Checkbox({name: 'checkbox2',  group: 'checkboxGroup'})
        .select(false)
        .selectedColor(0x39a2db)
        .onChange((value: boolean) => {
          console.info('Checkbox2 change is'+ value)
        })
    }
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙xxx子系统/部件

harmony 鸿蒙高级组件接口说明模板

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙xxx（模块名，与API参考title保持一致）错误码

harmony 鸿蒙FAQ写作模板

harmony 鸿蒙开发指南写作模板

harmony 鸿蒙API接口说明模板

harmony 鸿蒙Native接口文档注释

harmony 鸿蒙调试工具写作模板

harmony 鸿蒙教程：标题（对应的任务名称）