1# 无障碍属性 2 3组件可以设置相应的无障碍属性和事件来更好地使用无障碍能力。 4 5> **说明：** 6> 7> 从API Version 10 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## accessibilityGroup 10 11accessibilityGroup(value: boolean) 12 13无障碍组。 14 15**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21**参数：** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| ------ | ------- | ---- | ------------------------------------------------------------ | 25| value | boolean | 是 | 无障碍组，设置为true时表示该组件及其所有子组件为一整个可以选中的组件，无障碍服务将不再关注其子组件内容。<br/>默认值：false | 26 27## accessibilityText 28 29accessibilityText(value: string) 30 31无障碍文本。 32 33**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 34 35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39**参数：** 40 41| 参数名 | 类型 | 必填 | 说明 | 42| ------ | ------ | ---- | ------------------------------------------------------------ | 43| value | string | 是 | 无障碍文本，当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：“”<br/>**说明：**<br/>若组件既拥有文本属性，又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。<br/>若组件设置了无障碍分组属性为true，但是即没有无障碍文本属性，也没有文本属性，会对其子节点的组件进行文本拼接（深度优先）。 | 44 45## accessibilityText<sup>12+</sup> 46 47accessibilityText(text: Resource) 48 49无障碍文本，支持通过Resource引用资源文件。 50 51**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 52 53**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 54 55**系统能力：** SystemCapability.ArkUI.ArkUI.Full 56 57**参数：** 58 59| 参数名 | 类型 | 必填 | 说明 | 60| ------ | ------ | ---- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 61| text | [Resource](ts-types.md#resource) | 是 | 无障碍文本引用资源，当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>**说明：**<br/>若组件既拥有文本属性，又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。<br/>若组件设置了无障碍分组属性为true，但是即没有无障碍文本属性，也没有文本属性，会对其子节点的组件进行文本拼接（深度优先）。 | 62 63 64## accessibilityDescription 65 66accessibilityDescription(value: string) 67 68无障碍说明。 69 70**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ------ | ------ | ---- | ------------------------------------------------------------ | 80| value | string | 是 | 无障碍说明，用于为用户进一步说明当前组件，开发人员可为组件的该属性设置相对较详细的解释文本，帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果，尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性，则组件被选中时，先播报组件的文本属性，再播报无障碍说明属性的内容。<br/>默认值：“” | 81 82## accessibilityDescription<sup>12+</sup> 83 84accessibilityDescription(description: Resource) 85 86无障碍说明，支持通过Resource引用资源文件。 87 88**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 89 90**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 91 92**系统能力：** SystemCapability.ArkUI.ArkUI.Full 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------ | ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 98| description | [Resource](ts-types.md#resource) | 是 | 无障碍说明引用资源，用于为用户进一步说明当前组件，开发人员可为组件的该属性设置相对较详细的解释文本，帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果，尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性，则组件被选中时，先播报组件的文本属性，再播报无障碍说明属性的内容。 | 99 100## accessibilityLevel 101 102accessibilityLevel(value: string) 103 104无障碍重要性。 105 106**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 107 108**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| ------ | ------ | ---- | ------------------------------------------------------------ | 116| value | string | 是 | 无障碍重要性，用于控制某个组件是否可被无障碍辅助服务所识别。<br/>支持的值为:<br/>"auto"：根据组件不同会转换为“yes”或者“no”。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto"<br/>**说明：**<br/>以下组件当accessibilityLevel设置成"auto"时，当前组件可被无障碍辅助服务所识别：Checkbox, CheckboxGroup, Gauge, Marquee, MenuItem, MenuItemGroup, Menu, Navigation, DatePicker, Progress, Radio, Rating, ScrollBar, Select, Slider, Stepper, Text, TextClock, TextPicker, TextTimer, TimePicker, Toggle, Web. | 117 118## accessibilityVirtualNode<sup>11+</sup> 119 120accessibilityVirtualNode(builder: CustomBuilder) 121 122无障碍虚拟节点。 123 124**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 125 126**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| ------ | ------ | ---- | ------------------------------------------------------------ | 134| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 无障碍虚拟子节点，使开发者可以对自绘制组件传入一个自定义的CustomBuilder，该CustomBuilder中的组件在后端仅做布局不做显示，辅助应用获取无障碍节点信息时会返回CustomBuilder中的节点信息。 | 135 136## accessibilityChecked<sup>13+</sup> 137 138accessibilityChecked(isCheck: boolean) 139 140无障碍节点是否选中的状态维护，用于支持多选的情况使用。 141 142**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 143 144**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 145 146**系统能力：** SystemCapability.ArkUI.ArkUI.Full 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| ------- | ------- | ---- | ------------------------------------------------------------ | 152| isCheck | boolean | 是 | 用于表示组件是否被选中。<br/>支持的值为:<br/>true:当前组件被选中。<br/>false:当前组件未被选中。<br/>undefined:由组件自行确定选中状态。<br/>默认值:undefined。<br/>**说明：**<br/>1. 使用该接口设置true或false后，会默认修改该组件的checkable属性为true。<br/>2. 使用该接口设置true或false后，如果需要同时使用accessibilitySelected接口则需要将accessibilitySelected接口的参数设置为undefined。 | 153 154## accessibilitySelected<sup>13+</sup> 155 156accessibilitySelected(isSelect: boolean) 157 158无障碍节点是否选中的状态维护，用于支持单选的情况使用。 159 160**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 161 162**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**参数：** 167 168| 参数名 | 类型 | 必填 | 说明 | 169| -------- | ------- | ---- | ------------------------------------------------------------ | 170| isSelect | boolean | 是 | 用于表示组件是否被选中。<br/>支持的值为:<br/>true:当前组件被选中。<br/>false:当前组件未被选中。<br/>undefined:由组件自行确定选中状态。<br/>默认值:undefined。<br/>**说明：**<br/>1. 使用该接口设置true或false后，如果需要同时使用accessibilityChecked接口则需要将accessibilityChecked接口的参数设置为undefined。 | 171 172## 示例 173 174该示例主要演示accessibilityText无障碍文本和accessibilityDescription无障碍说明的播报内容。 175 176```ts 177// xxx.ets 178@Entry 179@Component 180struct Index { 181 182 @Builder customAccessibilityNode() { 183 Column() { 184 Text(`virtual node`) 185 } 186 .width(10) 187 .height(10) 188 } 189 190 build() { 191 Row() { 192 Column() { 193 Text("文本1") 194 .fontSize(50) 195 .fontWeight(FontWeight.Bold) 196 Text("文本2") 197 .fontSize(50) 198 .fontWeight(FontWeight.Bold) 199 } 200 .width('100%') 201 .accessibilityGroup(true) 202 .accessibilityLevel("yes") 203 .accessibilityText("分组") 204 .accessibilityDescription("Column组件可以被选中，播报的内容是“分组”") 205 .accessibilityVirtualNode(this.customAccessibilityNode) 206 .accessibilityChecked(true) 207 .accessibilitySelected(undefined) 208 } 209 .height('100%') 210 } 211} 212``` 213