1# Accessibility 2 3You can set accessibility attributes and events for components. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 8 9## accessibilityGroup 10 11accessibilityGroup(value: boolean) 12 13Sets the accessibility group. 14 15**Widget capability**: This API can be used in ArkTS widgets since API version 12. 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21**Parameters** 22 23| Name| Type | Mandatory| Description | 24| ------ | ------- | ---- | ------------------------------------------------------------ | 25| value | boolean | Yes | Accessibility group. If this attribute is set to **true**, the component and all its child components form an entire selectable component, and the accessibility service will no longer be available for the content of its child components.<br>Default value: **false**| 26 27## accessibilityGroup<sup>14+</sup> 28 29accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions) 30 31Groups components for accessibility purposes, allowing the accessibility service to read out concatenated text. 32 33**Widget capability**: This API can be used in ArkTS widgets since API version 14. 34 35**Atomic service API**: This API can be used in atomic services since API version 14. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39**Parameters** 40 41| Name | Type | Mandatory| Description | 42| -------------------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 43| isGroup | boolean | Yes | Whether to group the current component and its children. If this parameter is set to **true**, the component and all its children are treated as a single selectable unit. The accessibility service will not focus on individual child components.<br>Default value: **false**| 44| accessibilityOptions | [AccessibilityOptions](#accessibilityoptions14) | No | Options to customize accessibility behavior, such as prioritizing concatenated text for reading. | 45 46## AccessibilityOptions<sup>14+</sup> 47 48**System capability**: SystemCapability.ArkUI.ArkUI.Full 49 50| Name | Type | Mandatory| Description | 51| ---------------------- | ------- | ---- | ------------------------------------------------------------ | 52| accessibilityPreferred | boolean | No | Whether to prioritize the accessibility text of child components during a deep traversal. The value **true** means to prioritize the accessibility text of child components.<br>If a child component's accessibility text is empty, the accessibility service uses the component's own text content. The concatenated text is then assigned to the parent node if both its accessibility text and text content are empty.| 53 54## accessibilityText 55 56accessibilityText(value: string) 57 58Sets the accessibility text. 59 60**Widget capability**: This API can be used in ArkTS widgets since API version 12. 61 62**Atomic service API**: This API can be used in atomic services since API version 11. 63 64**System capability**: SystemCapability.ArkUI.ArkUI.Full 65 66**Parameters** 67 68| Name| Type | Mandatory| Description | 69| ------ | ------ | ---- | ------------------------------------------------------------ | 70| value | string | Yes | Accessibility text. If a component does not contain text information, it will not be announced by the screen reader when selected. In this case, the screen reader user cannot know which component is selected. To solve this problem, you can set accessibility text for components without text information. When such a component is selected, the screen reader announces the specified accessibility text, informing the user which component is selected.<br>Default value: **""**<br>**NOTE**<br>If a component has both text content and accessibility text, only the accessibility text is announced.<br>If a component is grouped for accessibility purposes but lacks both text content and accessibility text, the screen reader will concatenate text from its child components (depth-first traversal).<br>To prioritize accessibility text concatenation, set **accessibilityPreferred** in **accessibilityGroup**.| 71 72## accessibilityText<sup>12+</sup> 73 74accessibilityText(text: Resource) 75 76Sets the accessibility text, which supports referencing resource files through **Resource**. 77 78**Widget capability**: This API can be used in ArkTS widgets since API version 12. 79 80**Atomic service API**: This API can be used in atomic services since API version 12. 81 82**System capability**: SystemCapability.ArkUI.ArkUI.Full 83 84**Parameters** 85 86| Name| Type | Mandatory| Description | 87| ------ | ------ | ---- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 88| text | [Resource](ts-types.md#resource) | Yes | Reference resource of accessibility text. If a component does not contain text information, it will not be announced by the screen reader when selected. In this case, the screen reader user cannot know which component is selected. To solve this problem, you can set accessibility text for components without text information. When such a component is selected, the screen reader announces the specified accessibility text, informing the user which component is selected.<br>**NOTE**<br>If a component has both text content and accessibility text, only the accessibility text is announced.<br>If a component is grouped for accessibility purposes but lacks both text content and accessibility text, the screen reader will concatenate text from its child components (depth-first traversal).<br>To prioritize accessibility text concatenation, set **accessibilityPreferred** in **accessibilityGroup**.| 89 90 91## accessibilityDescription 92 93accessibilityDescription(value: string) 94 95Sets the accessibility description. 96 97**Widget capability**: This API can be used in ArkTS widgets since API version 12. 98 99**Atomic service API**: This API can be used in atomic services since API version 11. 100 101**System capability**: SystemCapability.ArkUI.ArkUI.Full 102 103**Parameters** 104 105| Name| Type | Mandatory| Description | 106| ------ | ------ | ---- | ------------------------------------------------------------ | 107| value | string | Yes | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.<br>Default value: **""**| 108 109## accessibilityDescription<sup>12+</sup> 110 111accessibilityDescription(description: Resource) 112 113Sets the accessibility description, which supports referencing resource files through **Resource**. 114 115**Widget capability**: This API can be used in ArkTS widgets since API version 12. 116 117**Atomic service API**: This API can be used in atomic services since API version 12. 118 119**System capability**: SystemCapability.ArkUI.ArkUI.Full 120 121**Parameters** 122 123| Name| Type | Mandatory| Description | 124| ------ | ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 125| description | [Resource](ts-types.md#resource) | Yes | Reference resource of the accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.| 126 127## accessibilityLevel 128 129accessibilityLevel(value: string) 130 131Sets the accessibility level. 132 133**Widget capability**: This API can be used in ArkTS widgets since API version 12. 134 135**Atomic service API**: This API can be used in atomic services since API version 11. 136 137**System capability**: SystemCapability.ArkUI.ArkUI.Full 138 139**Parameters** 140 141| Name| Type | Mandatory| Description | 142| ------ | ------ | ---- | ------------------------------------------------------------ | 143| value | string | Yes | Accessibility level, which is used to decide whether a component can be identified by the accessibility service.<br>The options are as follows:<br>**"auto"**: The value is converted to **"yes"** or **"no"** based on the component.<br>**"yes"**: The current component is selectable for the accessibility service.<br>**"no"**: The current component is not selectable for the accessibility service.<br>**"no-hide-descendants"**: The current component and all its child components are not selectable for the accessibility service.<br>**Default value**: **"auto"**<br>**NOTE**<br>When the **accessibilityLevel** attribute of the following components is set to **"auto"**, they are selectable for the accessibility service: Checkbox, CheckboxGroup, Gauge, Marquee, MenuItem, MenuItemGroup, Menu, Navigation, DatePicker, Progress, Radio, Rating, ScrollBar, Select, Slider, Stepper, Text, TextClock, TextPicker, TextTimer, TimePicker, Toggle, Web.| 144 145## accessibilityVirtualNode<sup>11+</sup> 146 147accessibilityVirtualNode(builder: CustomBuilder) 148 149Sets the accessibility virtual node. 150 151**Widget capability**: This API can be used in ArkTS widgets since API version 12. 152 153**Atomic service API**: This API can be used in atomic services since API version 11. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ------ | ---- | ------------------------------------------------------------ | 161| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Accessibility virtual node, which enables you to pass in a custom builder to the self-drawing component. The components in the custom builder are only laid out but not displayed at the backend. When the accessibility application obtains the accessibility node information, the node information in the custom builder is returned.| 162 163## accessibilityChecked<sup>13+</sup> 164 165accessibilityChecked(isCheck: boolean) 166 167Sets the checked (selected) state of the accessibility node. It can be used to support multi-select scenarios. 168 169**Widget capability**: This API can be used in ArkTS widgets since API version 13. 170 171**Atomic service API**: This API can be used in atomic services since API version 13. 172 173**System capability**: SystemCapability.ArkUI.ArkUI.Full 174 175**Parameters** 176 177| Name | Type | Mandatory| Description | 178| ------- | ------- | ---- | ------------------------------------------------------------ | 179| isCheck | boolean | Yes | Whether the current component is selected.<br>The options are as follows:<br>**true**: The component is selected.<br>**false**: The component is not selected.<br>**undefined**: The component determines its own selected state.<br>Default value: **undefined**<br>**NOTE**<br>1. Setting this parameter to **true** or **false** will automatically set the component's **checkable** attribute to **true**.<br>2. When this parameter is set to **true** or **false**, to use it with **accessibilitySelected**, set the **accessibilitySelected** parameter to **undefined**.| 180 181## accessibilitySelected<sup>13+</sup> 182 183accessibilitySelected(isSelect: boolean) 184 185Sets the selected state of the accessibility node. It can be used to support single-select scenarios. 186 187**Widget capability**: This API can be used in ArkTS widgets since API version 13. 188 189**Atomic service API**: This API can be used in atomic services since API version 13. 190 191**System capability**: SystemCapability.ArkUI.ArkUI.Full 192 193**Parameters** 194 195| Name | Type | Mandatory| Description | 196| -------- | ------- | ---- | ------------------------------------------------------------ | 197| isSelect | boolean | Yes | Whether the current component is selected.<br>The options are as follows:<br>**true**: The component is selected.<br>**false**: The component is not selected.<br>**undefined**: The component determines its own selected state.<br>Default value: **undefined**<br>**NOTE**<br>1. When this parameter is set to **true** or **false**, to use it with **accessibilityChecked**, set the **accessibilityChecked** parameter to **undefined**.| 198 199 200## Example 1: Setting Accessibility Text and Description 201 202This example demonstrates how to use **accessibilityText** and **accessibilityDescription** to customize the content announced by screen readers. 203 204``` 205// xxx.ets 206@Entry 207@Component 208struct Index { 209 210 @Builder customAccessibilityNode() { 211 Column() { 212 Text(`virtual node`) 213 } 214 .width(10) 215 .height(10) 216 } 217 218 build() { 219 Row() { 220 Column() { 221 Text("Text 1") 222 .fontSize(50) 223 .fontWeight(FontWeight.Bold) 224 Text("Text 2") 225 .fontSize(50) 226 .fontWeight(FontWeight.Bold) 227 } 228 .width('100%') 229 .accessibilityGroup(true) 230 .accessibilityLevel("yes") 231 .accessibilityText("Group") // If a component has both text content and accessibility text, only the accessibility text is announced. 232 .accessibilityDescription("The <Column> component is selectable , and the text to be read out is "Group".) 233 .accessibilityVirtualNode(this.customAccessibilityNode) 234 .accessibilityChecked(true) 235 .accessibilitySelected(undefined) 236 } 237 .height('100%') 238 } 239} 240``` 241 242## Example 2: Setting the Accessibility Group 243 244This example shows how to use **accessibilityGroup** to prioritize reading the accessibility text of child components. 245 246``` 247// xxx.ets 248@Entry 249@Component 250struct Focus { 251 build() { 252 Column({ space: 10 }) { 253 Text('123456') 254 .focusable(true) 255 .borderRadius(5) 256 .accessibilityText("Accessibility text is announced if both accessibility text and text content are present") 257 .accessibilityLevel("yes") 258 Button().accessibilityLevel("yes").accessibilityText("Accessibility text is announced if no text is present") 259 Button("Text content is announced if no accessibility text is present").accessibilityLevel("yes") 260 Button() 261 Button('btnl23').accessibilityText("Button with both accessibility text and text").accessibilityLevel("yes") 262 Button('btn123').accessibilityLevel("yes") 263 } 264 .accessibilityGroup(true, { accessibilityPreferred: true }) 265 //.accessibilityGroup(true) 266 .borderWidth(5) 267 .width('100%') 268 .height('100%') 269 } 270} 271``` 272 273