1# 无障碍属性 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zhanghangkai10241--> 5<!--Designer: @lmleon--> 6<!--Tester: @fredyuan0912--> 7<!--Adviser: @HelloCrease--> 8 9设置组件的无障碍属性和事件，以充分利用无障碍功能。 10 11> **说明：** 12> 13> 从API version 10 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## accessibilityGroup 16 17accessibilityGroup(value: boolean):T 18 19设置是否启用无障碍分组。启用无障碍分组后，组件及其子组件作为一整个可选组件，无障碍服务不再关注子组件内容。 20 21若组件启用无障碍分组，当组件不包含通用文本属性，同时未设置[无障碍文本](#accessibilitytext)时，将默认拼接其子组件的通用文本属性作为组件的合并文本。若某一子组件没有通用文本属性，则忽略该子组件不进行拼接，此时合并文本不使用子组件的无障碍文本。 22 23**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------ | ------- | ---- | ------------------------------------------------------------ | 33| value | boolean | 是 | 无障碍分组，设置为true时表示该组件及其所有子组件为一整个可以选中的组件，无障碍服务将不再关注其子组件内容；设置为false表示不启用无障碍分组。<br/>默认值：false | 34 35**返回值：** 36 37| 类型 | 说明 | 38| -------- | -------- | 39| T | 返回当前对象。 | 40 41## accessibilityGroup<sup>14+</sup> 42 43accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions):T 44 45设置是否启用无障碍分组。启用无障碍分组后，组件及其子组件作为一整个可选组件，无障碍服务不再关注子组件内容。 46 47若组件启用无障碍分组，当组件不包含通用文本属性，同时未设置[无障碍文本](#accessibilitytext)时，将默认拼接其子组件的通用文本属性作为组件的合并文本。若某一子组件没有通用文本属性，则忽略该子组件不进行拼接。 48 49通过accessibilityPreferred启用优先拼接无障碍文本进行朗读后，将优先拼接其子组件的无障碍文本属性作为组件的合并文本。若某一子组件未设置无障碍文本，则继续拼接该子组件的通用文本属性，若该子组件没有通用文本属性，则忽略该子组件不进行拼接。 50 51**卡片能力：** 从API version 14开始，该接口支持在ArkTS卡片中使用。 52 53**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 54 55**系统能力：** SystemCapability.ArkUI.ArkUI.Full 56 57**参数：** 58 59| 参数名 | 类型 | 必填 | 说明 | 60| -------------------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 61| isGroup | boolean | 是 | 无障碍分组，设置为true时表示该组件及其所有子组件为一整个可以选中的组件，无障碍服务将不再关注其子组件内容；设置为false表示不启用无障碍分组。<br/>默认值：false | 62| accessibilityOptions | [AccessibilityOptions](ts-types.md#accessibilityoptions14对象说明) | 是 | accessibilityPreferred设置为true时，使应用优先拼接无障碍文本进行朗读；设置为false时，应用进行屏幕朗读时不会优先使用无障碍文本。<br/>默认值：false | 63 64**返回值：** 65 66| 类型 | 说明 | 67| -------- | -------- | 68| T | 返回当前对象。 | 69 70## accessibilityText 71 72accessibilityText(value: string):T 73 74设置无障碍文本。当组件不包含文本属性时，开发人员可通过设置无障碍文本属性，使不包含文字信息的组件能够播报无障碍文本的内容。 75 76**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 77 78**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 79 80**系统能力：** SystemCapability.ArkUI.ArkUI.Full 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| ------ | ------ | ---- | ------------------------------------------------------------ | 86| value | string | 是 | 无障碍文本，当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：“”<br/>**说明：**<br/>若组件既拥有文本属性，又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。<br/>若组件设置了无障碍分组属性为true，但是既没有无障碍文本属性，也没有文本属性，会对其子节点的组件进行文本拼接（深度优先）。<br/>不对无障碍文本属性进行拼接，如需优先拼接无障碍文本，则需设置accessibilityGroup的accessibilityPreferred。 | 87 88**返回值：** 89 90| 类型 | 说明 | 91| -------- | -------- | 92| T | 返回当前对象。 | 93 94## accessibilityText<sup>12+</sup> 95 96accessibilityText(text: Resource):T 97 98设置无障碍文本，支持通过Resource引用资源文件。当组件不包含文本属性时，开发人员可通过设置无障碍文本属性，使不包含文字信息的组件能够播报无障碍文本的内容。 99 100**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 101 102**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| ------ | ------ | ---- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 110| text | [Resource](ts-types.md#resource) | 是 | 无障碍文本引用资源，当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>**说明：**<br/>若组件既拥有文本属性，又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。<br/>若组件设置了无障碍分组属性为true，但是既没有无障碍文本属性，也没有文本属性，会对其子节点的组件进行文本拼接（深度优先）。<br/>不对无障碍文本属性进行拼接，如需优先拼接无障碍文本，则需设置accessibilityGroup的accessibilityPreferred。 | 111 112**返回值：** 113 114| 类型 | 说明 | 115| -------- | -------- | 116| T | 返回当前对象。 | 117 118 119## accessibilityDescription 120 121accessibilityDescription(value: string):T 122 123设置无障碍说明。该属性用于为用户进一步说明当前组件，开发人员可为组件设置相对较详细的解释文本，帮助用户理解将要执行的操作。 124 125**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 126 127**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| ------ | ------ | ---- | ------------------------------------------------------------ | 135| value | string | 是 | 无障碍说明，用于为用户进一步说明当前组件，开发人员可为组件的该属性设置相对较详细的解释文本，帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果，尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性，则组件被选中时，先播报组件的文本属性，再播报无障碍说明属性的内容。<br/>默认值：“” | 136 137**返回值：** 138 139| 类型 | 说明 | 140| -------- | -------- | 141| T | 返回当前对象。 | 142 143## accessibilityDescription<sup>12+</sup> 144 145accessibilityDescription(description: Resource):T 146 147设置无障碍说明，支持通过Resource引用资源文件。该属性用于为用户进一步说明当前组件，开发人员可为组件设置相对较详细的解释文本，帮助用户理解将要执行的操作。 148 149**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 150 151**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 152 153**系统能力：** SystemCapability.ArkUI.ArkUI.Full 154 155**参数：** 156 157| 参数名 | 类型 | 必填 | 说明 | 158| ------ | ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 159| description | [Resource](ts-types.md#resource) | 是 | 无障碍说明引用资源，用于为用户进一步说明当前组件，开发人员可为组件的该属性设置相对较详细的解释文本，帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果，尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性，则组件被选中时，先播报组件的文本属性，再播报无障碍说明属性的内容。 | 160 161**返回值：** 162 163| 类型 | 说明 | 164| -------- | -------- | 165| T | 返回当前对象。 | 166 167## accessibilityLevel 168 169accessibilityLevel(value: string):T 170 171设置无障碍重要性。该属性用于控制某个组件是否可被无障碍辅助服务所识别。 172 173**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 174 175**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 176 177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| ------ | ------ | ---- | ------------------------------------------------------------ | 183| value | string | 是 | 无障碍重要性，用于控制某个组件是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件由无障碍分组服务和ArkUl进行综合判断组件是否可被无障碍辅助服务所识别。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto"<br/>**说明：**<br/>当accessibilityLevel设置成"auto"时，组件是否可被无障碍辅助服务所识别取决于以下多方面因素：<br/>1. 组件是否可被识别由无障碍辅助服务内部判断，自行选择。<br/>2. 若组件的父组件accessibilityGroup属性中isGroup设置为true，无障碍服务将不再关注其子组件内容，组件不可被无障碍辅助服务所识别。<br/>3. 若组件的父组件accessibilityLevel属性设置为"no-hide-descendants"，组件不可被无障碍辅助服务所识别。 | 184 185**返回值：** 186 187| 类型 | 说明 | 188| -------- | -------- | 189| T | 返回当前对象。 | 190 191## accessibilityVirtualNode<sup>11+</sup> 192 193accessibilityVirtualNode(builder: CustomBuilder):T 194 195设置无障碍虚拟子节点。对自绘制组件传入一个自定义的CustomBuilder，该CustomBuilder中的组件在后端仅做布局不做显示，辅助应用获取无障碍节点信息时会返回CustomBuilder中的节点信息。 196 197**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 198 199**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------ | ------ | ---- | ------------------------------------------------------------ | 207| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 无障碍虚拟子节点，使开发者可以对自绘制组件传入一个自定义的CustomBuilder，该CustomBuilder中的组件在后端仅做布局不做显示，辅助应用获取无障碍节点信息时会返回CustomBuilder中的节点信息。 | 208 209**返回值：** 210 211| 类型 | 说明 | 212| -------- | -------- | 213| T | 返回当前对象。 | 214 215## accessibilityChecked<sup>13+</sup> 216 217accessibilityChecked(isCheck: boolean):T 218 219无障碍节点是否选中的状态维护，用于支持多选的情况使用，表示组件是否被选中。 220 221**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 222 223**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 224 225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| ------- | ------- | ---- | ------------------------------------------------------------ | 231| isCheck | boolean | 是 | 用于表示组件是否被选中。<br/>支持的值为：<br/>true：当前组件被选中。<br/>false：当前组件未被选中。<br/>undefined：由组件自行确定选中状态。<br/>默认值：undefined <br/>**说明：**<br/>1. 使用该接口设置true或false后，会默认修改该组件的checkable属性为true。<br/>2. accessibilityChecked属性代表组件是多选模式，而[accessibilitySelected](ts-universal-attributes-accessibility.md#accessibilityselected13)属性代表组件是单选模式，组件不能同时存在两种选择模式，会造成无障碍状态冲突，导致屏幕朗读等无障碍辅助应用无法正确识别选中状态。如使用当前接口设置组件为多选模式（设置为true、false），则需要保证未使用accessibilitySelected函数设置属性为true或者false，如果已设置，需使用accessibilitySelected函数设置accessibilitySelected属性为undefined模式。 | 232 233**返回值：** 234 235| 类型 | 说明 | 236| -------- | -------- | 237| T | 返回当前对象。 | 238 239## accessibilitySelected<sup>13+</sup> 240 241accessibilitySelected(isSelect: boolean):T 242 243无障碍节点是否选中的状态维护，用于支持单选的情况使用，表示组件是否被选中。 244 245**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 246 247**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 248 249**系统能力：** SystemCapability.ArkUI.ArkUI.Full 250 251**参数：** 252 253| 参数名 | 类型 | 必填 | 说明 | 254| -------- | ------- | ---- | ------------------------------------------------------------ | 255| isSelect | boolean | 是 | 用于表示组件是否被选中。<br/>支持的值为：<br/>true：当前组件被选中。<br/>false：当前组件未被选中。<br/>undefined：由组件自行确定选中状态。<br/>默认值：undefined <br/>**说明：**<br/>1. [accessibilityChecked](ts-universal-attributes-accessibility.md#accessibilitychecked13)属性代表组件是多选模式，而accessibilitySelected属性代表组件是单选模式，组件不能同时存在两种选择模式，会造成无障碍状态冲突，导致屏幕朗读等无障碍辅助应用无法正确识别选中状态。如使用当前接口设置组件为单选模式（true、false），则需要保证未使用accessibilityChecked函数设置属性为true或者false，如果已设置，需使用accessibilityChecked函数设置accessibilityChecked属性为undefined模式。 | 256 257**返回值：** 258 259| 类型 | 说明 | 260| -------- | -------- | 261| T | 返回当前对象。 | 262 263## accessibilityRole<sup>18+</sup> 264 265accessibilityRole(role: AccessibilityRoleType):T 266 267设置无障碍组件类型，特定组件类型有特定的朗读方式，可以根据应用诉求，修改组件类型，用于控制无障碍模式下对组件的朗读方式和朗读内容。 268 269**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 270 271**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 272 273**系统能力：** SystemCapability.ArkUI.ArkUI.Full 274 275**参数：** 276 277| 参数名 | 类型 | 必填 | 说明 | 278| -------- | ------- | ---- | ------------------------------------------------------------ | 279| role | [AccessibilityRoleType](ts-universal-attributes-accessibility.md#accessibilityroletype18枚举说明) | 是 | 屏幕朗读播报的组件类型，如按钮、图表。具体类型可由开发者自定义。 | 280 281**返回值：** 282 283| 类型 | 说明 | 284| -------- | -------- | 285| T | 返回当前对象。 | 286 287## AccessibilityRoleType<sup>18+</sup>枚举说明 288 289定义组件的屏幕朗读功能角色类型。 290 291**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 292 293**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 294 295**系统能力：** SystemCapability.ArkUI.ArkUI.Full 296 297| 名称 | 值 | 说明 | 298| ---- | ---- | ------------------ | 299| ACTION_SHEET | 0 | 列表弹窗。 | 300| ALERT_DIALOG | 1 | 显示警告弹窗组件。 | 301| INDEXER_COMPONENT | 2 | 索引器组件。 | 302| BADGE_COMPONENT | 3 | 信息标记组件。 | 303| BLANK | 4 | 空白填充组件。 | 304| BUTTON | 5 | 按钮。 | 305| BACK_BUTTON | 6 | 大图页返回按钮。 | 306| SHEET_DRAG_BAR | 7 | 滑动条。 | 307| CALENDAR_PICKER | 8 | 日历选择器组件。 | 308| CALENDAR | 9 | 日历。 | 309| CANVAS | 10 | 提供画布组件。 | 310| CANVAS_GRADIENT | 11 | 渐变对象。 | 311| CANVAS_PATTERN | 12 | 通过指定图像和重复方式创建图片填充的模板。 | 312| CHECKBOX | 13 | 提供多选框组件。 | 313| CHECKBOX_GROUP | 14 | 多选框群组。 | 314| CIRCLE | 15 | 用于绘制圆形的组件。| 315| COLUMN_SPLIT | 16 | 将子组件纵向布局，并在每个子组件之间插入一根横向的分割线。 | 316| COLUMN | 17 | 沿垂直方向布局的容器。 | 317| CANVAS_RENDERING_CONTEXT_2D | 18 | 用于在画布组件上绘制矩形、文本、图片等。 | 318| CHART | 19 | 图表组件。 | 319| COUNTER | 20 | 计数器组件。 | 320| CONTAINER_MODAL | 21 | 模态容器。 | 321| DATA_PANEL | 22 | 数据面板组件。 | 322| DATE_PICKER | 23 | 选择日期的滑动选择器组件。 | 323| DIALOG | 24 | 弹出框。 | 324| DIVIDER | 25 | 提供分隔器组件。 | 325| DRAG_BAR | 26 | 拖拽条。 | 326| EFFECT_COMPONENT | 27 | 特效合并容器组件。 | 327| ELLIPSE | 28 | 椭圆绘制组件。 | 328| FLEX | 29 | 以弹性方式布局子组件的容器组件。 | 329| FLOW_ITEM | 30 | 瀑布流组件的子组件。 | 330| FORM_COMPONENT | 31 | 提供卡片组件。 | 331| FORM_LINK | 32 | 静态卡片交互组件。 | 332| GAUGE | 33 | 数据量规图表组件。 | 333| GRID | 34 | 网格容器。 | 334| GRID_COL | 35 | 栅格子组件。 | 335| GRID_CONTAINER | 36 | 纵向排布栅格布局容器。 | 336| GRID_ITEM | 37 | 网格容器中单项内容容器。 | 337| GRID_ROW | 38 | 栅格容器组件。 | 338| HYPERLINK | 39 | 超链接组件。 | 339| IMAGE | 40 | 图片组件。 | 340| IMAGE_ANIMATOR | 41 | 提供帧动画组件。 | 341| IMAGE_BITMAP | 42 | 存储canvas渲染的像素数据。 | 342| IMAGE_DATA | 43 | 存储canvas渲染的像素数据。 | 343| IMAGE_SPAN | 44 | 用于显示行内图片。 | 344| LABEL | 45 | 标签。 | 345| LINE | 46 | 线型。 | 346| LIST | 47 | 列表。| 347| LIST_ITEM | 48 | 用来展示列表具体item。 | 348| LIST_ITEM_GROUP | 49 | 用来展示列表item分组。 | 349| LOADING_PROGRESS | 50 | 用于显示加载动效的组件。 | 350| MARQUEE | 51 | 跑马灯组件。 | 351| MATRIX2D | 52 | 矩阵对象。 | 352| MENU | 53 | 菜单。 | 353| MENU_ITEM | 54 | 菜单项。 | 354| MENU_ITEM_GROUP | 55 | 菜单项分组。 | 355| NAV_DESTINATION | 56 | 显示Navigation的内容区。 | 356| NAV_ROUTER | 57 | 导航组件。 | 357| NAVIGATION | 58 | 路由导航的根视图容器。 | 358| NAVIGATION_BAR | 59 | 导航栏。 | 359| NAVIGATION_MENU | 60 | 导航菜单。 | 360| NAVIGATOR | 61 | 路由容器组件。 | 361| OFFSCREEN_CANVAS | 62 | 用于自定义绘制图形。 | 362| OFFSCREEN_CANVAS_RENDERING_CONTEXT2D | 63 | 2D绘制对象，用于在画布组件上绘制矩形、文本、图片等。 | 363| OPTION | 64 | 具体项目。 | 364| PANEL | 65 | 可滑动面板。 | 365| PAPER_PAGE | 66 | 页面。 | 366| PATH | 67 | 路径绘制组件。 | 367| PATH2D | 68 | 路径对象。 | 368| PATTERN_LOCK | 69 | 图案密码锁组件。 | 369| PICKER | 70 | 选择器。 | 370| PICKER_VIEW | 71 | 选择器视图。 | 371| PLUGIN_COMPONENT | 72 | 新增插件组件。 | 372| POLYGON | 73 | 多边形绘制组件。 | 373| POLYLINE | 74 | 折线绘制组件。 | 374| POPUP | 75 | 显示特定样式气泡。 | 375| PROGRESS | 76 | 文本下载按钮。 | 376| QRCODE | 77 | 二维码。 | 377| RADIO | 78 | 单选框。 | 378| RATING | 79 | 提供在给定范围内选择评分的组件。 | 379| RECT | 80 | 矩形绘制组件。 | 380| REFRESH | 81 | 下拉刷新容器组件。 | 381| RELATIVE_CONTAINER | 82 | 相对布局组件。 | 382| REMOTE_WINDOW | 83 | 远程控制窗口组件。 | 383| RICH_EDITOR | 84 | 支持图文混排和文本交互式编辑的组件。 | 384| RICH_TEXT | 85 | 富文本组件。 | 385| ROLE_PAGER | 86 | 分页。 | 386| ROW | 87 | 沿水平方向布局容器。 | 387| ROW_SPLIT | 88 | 将子组件横向布局，并在每个子组件之间插入一根纵向的分割线。 | 388| SCROLL | 89 | 可滚动的容器组件。 | 389| SCROLL_BAR | 90 | 滚动条。 | 390| SEARCH | 91 | 搜索框组件。 | 391| SEARCH_FIELD | 92 | 搜索框。 | 392| SELECT | 93 | 下拉选择菜单组件。 | 393| SHAPE | 94 | 绘制组件的父组件。 | 394| SIDEBAR_CONTAINER | 95 | 提供侧边栏可以显示和隐藏的侧边栏容器。 | 395| SLIDER | 96 | 垂直方向的滑动条。 | 396| SPAN | 97 | 用于显示行内文本的组件。 | 397| STACK | 98 | 堆叠容器。 | 398| STEPPER | 99 | 步骤导航器组件。 | 399| STEPPER_ITEM | 100 | 用作Stepper组件的页面子组件。 | 400| SWIPER | 101 | 滑块视图容器。 | 401| SWIPER_INDICATOR | 102 | 定义 Swiper 组件的导航指示器。 | 402| SWITCH | 103 | 开关。 | 403| SYMBOL_GLYPH | 104 | 显示图标小符号的组件。 | 404| TAB_CONTENT | 105 | 仅在Tabs中使用，对应一个切换页签的内容视图。 | 405| TAB_BAR | 106 | 页签栏。 | 406| TABS | 107 | 通过页签进行内容视图切换的容器组件。 | 407| TEXT | 108 | 文本。 | 408| TEXT_CLOCK | 109 | 文本时钟组件。 | 409| TEXT_ENTRY | 110 | 文本输入。 | 410| TEXT_INPUT | 111 | 输入框组件。 | 411| TEXT_PICKER | 112 | 文本类滑动选择器组件。 | 412| TEXT_TIMER | 113 | 通过文本显示计时信息并控制其计时器状态的组件。 | 413| TEXT_AREA | 114 | 输入区域组件。 | 414| TEXT_FIELD | 115 | 文本框。 | 415| TIME_PICKER | 116 | 时间选择组件。 | 416| TITLE_BAR | 117 | 标题栏。 | 417| TOGGLER | 118 | 状态组件。 | 418| UI_EXTENSION_COMPONENT | 119 | 用户界面扩展组件。 | 419| VIDEO | 120 | 用于播放视频文件并控制其播放状态的组件。 | 420| WATER_FLOW | 121 | 瀑布流容器。 | 421| WEB | 122 | 加载网页组件。 | 422| XCOMPONENT | 123 | 自定义渲染。 | 423| ROLE_NONE | 124 | NULL。 | 424 425## accessibilityNextFocusId<sup>18+</sup> 426 427accessibilityNextFocusId(nextId: string):T 428 429指定走焦过程中组件的下一个焦点。 430 431**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 432 433**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 434 435**系统能力：** SystemCapability.ArkUI.ArkUI.Full 436 437**参数：** 438 439| 参数名 | 类型 | 必填 | 说明 | 440| ------ | ------ | ---- | ------------------------------------------------------------ | 441| nextId | string | 是 | 下一个被指定聚焦组件的[唯一标识id](ts-universal-attributes-component-id.md#id)。若唯一标识id无对应组件，则设置的accessibilityNextFocusId不存在，设置无效。 | 442 443**返回值：** 444 445| 类型 | 说明 | 446| -------- | -------- | 447| T | 返回当前对象。 | 448 449## accessibilityDefaultFocus<sup>18+</sup> 450 451accessibilityDefaultFocus(focus: boolean):T 452 453设置屏幕朗读当前页默认首焦点。 454 455**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 456 457**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 458 459**系统能力：** SystemCapability.ArkUI.ArkUI.Full 460 461**参数：** 462 463| 参数名 | 类型 | 必填 | 说明 | 464| ------ | ------- | ---- | ------------------------------------------------------------ | 465| focus | boolean | 是 | 设置屏幕朗读当前页默认首焦点。值为true则表示该组件为当前页默认首焦点，值为false或其他值无效。 | 466 467**返回值：** 468 469| 类型 | 说明 | 470| -------- | -------- | 471| T | 返回当前对象。 | 472 473## accessibilityUseSamePage<sup>18+</sup> 474 475accessibilityUseSamePage(pageMode: AccessibilitySamePageMode):T 476 477针对跨进程嵌入式显示的组件，例如[EmbeddedComponent](ts-container-embedded-component.md)，其子树场景中出现的跳焦问题，可通过设置accessibilityUseSamePage属性解决。因跨进程嵌入式显示的组件启动进程的page事件与宿主page事件发送时序不一致，可能导致焦点从当前组件移至另一组件，此现象称为“跳焦”。 478 479**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 480 481**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 482 483**系统能力：** SystemCapability.ArkUI.ArkUI.Full 484 485**参数：** 486 487| 参数名 | 类型 | 必填 | 说明 | 488| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ | 489| pageMode | [AccessibilitySamePageMode](#accessibilitysamepagemode18枚举说明) | 是 | 当前跨进程嵌入式显示的组件和宿主应用的同page模式。 | 490 491**返回值：** 492 493| 类型 | 说明 | 494| -------- | -------- | 495| T | 返回当前对象。 | 496 497## AccessibilitySamePageMode<sup>18+</sup>枚举说明 498 499当前跨进程嵌入式显示的组件和宿主应用的同page模式。 500 501**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 502 503**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 504 505**系统能力：** SystemCapability.ArkUI.ArkUI.Full 506 507| 名称 | 值 | 说明 | 508| ----------- | ---- | ------------------------------------------------------------ | 509| SEMI_SILENT | 0 | 跨进程嵌入式显示的组件拉起来的进程的page事件中如果是首次加载页面或者该事件页面的根节点发送的page事件会被忽略。 | 510| FULL_SILENT | 1 | 跨进程嵌入式显示的组件将忽略所有的page事件。 | 511 512## accessibilityScrollTriggerable<sup>18+</sup> 513 514accessibilityScrollTriggerable(isTriggerable: boolean):T 515 516设置无障碍节点是否支持屏幕朗读滚动操作。当屏幕朗读在焦点切换时，若容器内当前页面无可聚焦的组件，会发起一次自动滚动操作。 517 518**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 519 520**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 521 522**系统能力：** SystemCapability.ArkUI.ArkUI.Full 523 524**参数：** 525 526| 参数名 | 类型 | 必填 | 说明 | 527| -------------- | ------- | ---- | ------------------------------------------------------------ | 528| isTriggerable | boolean | 是 | 用于表示组件是否支持该能力。<br/>支持的值为：<br/>true：屏幕朗读焦点切换而容器内当前页面无可聚焦的组件时，需要自动滚动操作。<br/>false：屏幕朗读焦点切换而容器内当前页面无可聚焦的组件时，不需要自动滚动操作。<br/>undefined：还原默认值。<br/>默认值：true。<br/>**说明：**<br/>1. 该属性不影响原先无障碍节点属性中的scrollable。<br/>2. 组件最终在屏幕朗读下的滚动逻辑由屏幕朗读最终根据该属性和组件是否支持scroll来决定。<br/>3. 该属性为通用属性，所有基础组件均可配置。建议配置的滚动组件类型，如List，Grid，Scroll，WaterFlow等。| 529 530**返回值：** 531 532| 类型 | 说明 | 533| -------- | -------- | 534| T | 返回当前对象。 | 535 536## accessibilityTextHint<sup>12+</sup> 537 538accessibilityTextHint(value: string):T 539 540设置组件的文本提示信息，供无障碍辅助应用查询。 541 542**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 543 544**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 545 546**系统能力：** SystemCapability.ArkUI.ArkUI.Full 547 548**参数：** 549 550| 参数名 | 类型 | 必填 | 说明 | 551| -------------- | ------- | ---- | ------------------------------------------------------------ | 552| value | string | 是 | 组件的文本提示信息，供无障碍辅助应用查询。 | 553 554**返回值：** 555 556| 类型 | 说明 | 557| -------- | -------- | 558| T | 返回当前对象。 | 559 560## accessibilityFocusDrawLevel<sup>19+</sup> 561 562accessibilityFocusDrawLevel(drawLevel: FocusDrawLevel):T 563 564无障碍焦点绿框的绘制层级设置功能。 565 566> **说明：** 567> 568> 1. 在聚焦节点层级绘制获焦无障碍绿框，默认使用该层级绘制，由于绘制组件数顺序以及图形绘制顺序，绘制绿框会被父组件或者z序更高的兄弟组件遮挡裁切。 569> 570> 2. 在Z序顶层绘制绿框情况下，可以避免由于组件遮挡、裁切导致无障碍绿框被裁切遮挡。但由于具备较高的绘制层级，如果需要交互过程中，需要遮挡当前获焦的组件，并且不希望显示无障碍绿框则不适合使用这种配置。 571 572 573**卡片能力：** 从API version 19开始，该接口支持在ArkTS卡片中使用。 574 575**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 576 577**系统能力：** SystemCapability.ArkUI.ArkUI.Full 578 579**参数：** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| -------- | ------- | ---- | ------------------------------------------------------------ | 583| drawLevel | [FocusDrawLevel](ts-appendix-enums.md#focusdrawlevel19) | 是 | 无障碍绘制能力，默认情况下绘制聚焦节点本身。 | 584 585**返回值：** 586 587| 类型 | 说明 | 588| -------- | -------- | 589| T | 返回当前对象。 | 590 591## 示例 592 593### 示例1（设置无障碍文本和无障碍说明） 594 595该示例主要演示accessibilityText无障碍文本和accessibilityDescription无障碍说明的播报内容。 596 597```ts 598// xxx.ets 599@Entry 600@Component 601struct Index { 602 603 @Builder customAccessibilityNode() { 604 Column() { 605 Text(`virtual node`) 606 } 607 .width(10) 608 .height(10) 609 } 610 611 build() { 612 Row() { 613 Column() { 614 Text("文本1") 615 .fontSize(50) 616 .fontWeight(FontWeight.Bold) 617 Text("文本2") 618 .fontSize(50) 619 .fontWeight(FontWeight.Bold) 620 } 621 .width('100%') 622 .accessibilityGroup(true) 623 .accessibilityLevel("yes") 624 .accessibilityText("分组") // 无障碍文本的内容，若组件既拥有文本属性又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。 625 .accessibilityDescription("Column组件可以被选中，播报的内容是“分组”") 626 .accessibilityVirtualNode(this.customAccessibilityNode) 627 .accessibilityChecked(true) 628 .accessibilitySelected(undefined) 629 } 630 .height('100%') 631 } 632} 633``` 634 635### 示例2（设置无障碍组） 636 637该示例主要演示优先使用子组件的无障碍文本进行朗读。 638 639```ts 640// xxx.ets 641@Entry 642@Component 643struct Focus { 644 build() { 645 Column({ space: 10 }) { 646 Text('123456') 647 .focusable(true) 648 .borderRadius(5) 649 .accessibilityText("有accessibility有text优先读accessibility") 650 .accessibilityLevel("yes") 651 Button().accessibilityLevel("yes").accessibilityText("accessibility无text 读accessibility") 652 Button("无accessibility有text 读text").accessibilityLevel("yes") 653 Button() 654 Button('btn123').accessibilityText("有accessibility有text btn123").accessibilityLevel("yes") 655 Button('btn123').accessibilityLevel("yes") 656 } 657 .accessibilityGroup(true, { accessibilityPreferred: true }) 658 .borderWidth(5) 659 .width('100%') 660 .height('100%') 661 } 662} 663``` 664 665### 示例3（设置首焦点和组件的下一个焦点） 666 667该示例主要演示accessibilityDefaultFocus屏幕朗读当前页默认首焦点和accessibilityNextFocusId走焦过程中组件的下一个焦点。 668 669```ts 670// xxx.ets 671@Entry 672@Component 673struct Index { 674 build() { 675 Column({ space: 20 }) { 676 Text('Text Demo 1') 677 .fontSize(50) 678 .accessibilityLevel('yes') 679 .accessibilityNextFocusId('text3') 680 Text('Text Demo 2') 681 .id('text2') 682 .fontSize(50) 683 .accessibilityLevel('yes') 684 .accessibilityDefaultFocus(true) // 设置该组件为屏幕朗读当前页默认首焦点 685 .accessibilityNextFocusId('text4') 686 Text('Text Demo 3') 687 .id('text3') 688 .fontSize(50) 689 .accessibilityLevel('yes') 690 .accessibilityNextFocusId('text2') 691 Text('Text Demo 4') 692 .id('text4') 693 .fontSize(50) 694 .accessibilityLevel('yes') 695 } 696 .height('100%') 697 .width('100%') 698 } 699} 700``` 701 702### 示例4（设置无障碍组件类型和文本提示信息） 703 704该示例主要演示accessibilityRole无障碍组件类型和accessibilityTextHint供无障碍辅助应用查询的组件的文本提示信息。 705 706```ts 707// xxx.ets 708@Entry 709@Component 710struct Index { 711 @State isDownloading: boolean = false; 712 @State hintStr: string = '点击开始下载'; 713 714 build() { 715 Column({ space: 20 }) { 716 Button(this.isDownloading ? '下载中' : '点击下载') 717 .accessibilityLevel('yes') 718 .accessibilityTextHint(this.hintStr) 719 .onClick(() => { 720 this.isDownloading = !this.isDownloading; 721 this.hintStr = this.isDownloading ? '状态变为下载中' : '状态变为暂停下载'; 722 }) 723 TextInput({ placeholder: '请输入手机号码' }) 724 .accessibilityLevel('yes') 725 .accessibilityTextHint('请输入11位手机号码') 726 .width('80%') 727 Text('按照按钮类型播报') 728 .accessibilityLevel('yes') 729 .accessibilityRole(AccessibilityRoleType.BUTTON) 730 .accessibilityTextHint('屏幕朗读播报时，该组件将按照按钮类型进行播报') 731 .fontSize(30) 732 } 733 .height('100%') 734 .width('100%') 735 } 736} 737``` 738 739### 示例5（设置无障碍屏幕朗读滚动和焦点绿框绘制） 740 741该示例主要演示accessibilityScrollTriggerable设置无障碍节点是否支持屏幕朗读滚动、accessibilityFocusDrawLevel设置无障碍焦点绿框的绘制层级和accessibilityUseSamePage设置跨进程嵌入式显示的组件,如[EmbeddedComponent](ts-container-embedded-component.md)的accessibilityUseSamePage属性。 742 743```ts 744// xxx.ets 745import { Want } from '@kit.AbilityKit'; 746 747@Entry 748@Component 749struct Index { 750 @State message: string = 'Message: '; 751 private want: Want = { 752 // EmbeddedComponent提供方的bunldename，根据实际情况配置。 753 bundleName: 'com.example.embeddeddemo', 754 // EmbeddedComponent提供方的abilityName，根据实际情况配置。 755 abilityName: 'ExampleEmbeddedAbility', 756 } 757 758 build() { 759 Row() { 760 List() { 761 ListItem() { 762 Column() { 763 Text(this.message) 764 .fontSize(18) 765 .fontColor('#2D2D2D') 766 .fontWeight(FontWeight.Medium) 767 Column() { 768 EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION) 769 .width('100%') 770 .height('90%') 771 .onTerminated((info) => { 772 this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want); 773 }) 774 .onError((error) => { 775 this.message = 'Error: code = ' + error.code; 776 }) 777 .accessibilityUseSamePage(AccessibilitySamePageMode.FULL_SILENT) 778 .width('90%') 779 .height('50%') 780 .backgroundColor('#F0F0F0') 781 .borderRadius(8) 782 .borderWidth(1) 783 .borderColor('#D9D9D9') 784 785 Stack() { 786 Column() { 787 Text('文本1') 788 .fontSize(18) 789 .fontColor('#2D2D2D') 790 .fontWeight(FontWeight.Medium) 791 Text('文本1') 792 .fontSize(18) 793 .fontColor('#2D2D2D') 794 .fontWeight(FontWeight.Medium) 795 .accessibilityFocusDrawLevel(FocusDrawLevel.TOP) 796 } 797 .padding({ top: 8, bottom: 8 }) 798 799 Column() { 800 Text('文本2') 801 .fontSize(18) 802 .fontColor('#FFFFFF') 803 .fontWeight(FontWeight.Medium) 804 Text('文本2') 805 .fontSize(18) 806 .fontColor('#FFFFFF') 807 .fontWeight(FontWeight.Medium) 808 } 809 .backgroundColor('#4A90E2') 810 .padding({ 811 left: 12, 812 right: 12, 813 top: 10, 814 bottom: 10 815 }) 816 .borderRadius(6) 817 } 818 .width('100%') 819 .margin({ top: 10, bottom: 10 }) 820 } 821 .width('100%') 822 .height('100%') 823 .margin({ top: 15 }) 824 .accessibilityText($r('app.string.app_name')) 825 .accessibilityDescription($r('app.string.module_desc')) 826 Column() { 827 Text('文本4') 828 .fontSize(18) 829 .fontWeight(FontWeight.Medium) 830 } 831 .margin({ top: 15 }) 832 } 833 .width('100%') 834 } 835 } 836 .accessibilityScrollTriggerable(false) 837 .width('100%') 838 } 839 .height('100%') 840 .backgroundColor('#F7F9FC') 841 } 842} 843``` 844 845 846
