1# Accessibility 2 3You can set accessibility attributes and events for components to fully leverage accessibility features. 4 5> **NOTE** 6> 7> The initial 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 whether to enable accessibility grouping. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components. 14 15If accessibility grouping is enabled for a component that does not contain a universal text attribute or an [accessibility text](#accessibilitytext) attribute, the system will concatenate the universal text attributes of its child components to generate merged text for the component. Child components without universal text attributes will be ignored during concatenation, and their accessibility text (if any) won't be used in the merged text. 16 17**Widget capability**: This API can be used in ArkTS widgets since API version 12. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name| Type | Mandatory| Description | 26| ------ | ------- | ---- | ------------------------------------------------------------ | 27| value | boolean | Yes | Whether to enable accessibility grouping. The value **true** means to enable accessibility grouping, and **false** means the opposite. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components.<br>Default value: **false**| 28 29## accessibilityGroup<sup>14+</sup> 30 31accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions) 32 33Sets whether to enable accessibility grouping. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components. 34 35If accessibility grouping is enabled for a component that does not contain a universal text attribute or an [accessibility text](#accessibilitytext) attribute, the system will concatenate the universal text attributes of its child components to generate merged text for the component. Child components without universal text attributes will be ignored during concatenation. 36 37When **accessibilityPreferred** is set to **true**, the system will prioritize concatenating the accessibility text attributes of the child components. If a child component has no accessibility text set, its universal text attribute will be used instead. Components without either attribute will be excluded from concatenation. 38 39**Widget capability**: This API can be used in ArkTS widgets since API version 14. 40 41**Atomic service API**: This API can be used in atomic services since API version 14. 42 43**System capability**: SystemCapability.ArkUI.ArkUI.Full 44 45**Parameters** 46 47| Name | Type | Mandatory| Description | 48| -------------------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 49| isGroup | boolean | Yes | Whether to enable accessibility grouping. The value **true** means to enable accessibility grouping, and **false** means the opposite. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components.<br>Default value: **false**| 50| accessibilityOptions | [AccessibilityOptions](#accessibilityoptions14) | Yes | Options for accessibility grouping. When **accessibilityPreferred** is set to **true**, the system will prioritize concatenating accessibility text for screen readers. When **accessibilityPreferred** is set to **false**, accessibility text will not be prioritized.<br>Default value: **false** | 51 52## AccessibilityOptions<sup>14+</sup> 53 54**System capability**: SystemCapability.ArkUI.ArkUI.Full 55 56| Name | Type | Mandatory| Description | 57| ---------------------- | ------- | ---- | ------------------------------------------------------------ | 58| 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.<br>The value **false** means not to prioritize the accessibility text of child components.<br>Default value: **false**| 59 60## accessibilityText 61 62accessibilityText(value: string) 63 64Sets the accessibility text. When a component does not contain a text attribute, you can use this API to set an accessibility text attribute, so that accessibility services can announce the specified content for the component. 65 66**Widget capability**: This API can be used in ArkTS widgets since API version 12. 67 68**Atomic service API**: This API can be used in atomic services since API version 11. 69 70**System capability**: SystemCapability.ArkUI.ArkUI.Full 71 72**Parameters** 73 74| Name| Type | Mandatory| Description | 75| ------ | ------ | ---- | ------------------------------------------------------------ | 76| 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**.| 77 78## accessibilityText<sup>12+</sup> 79 80accessibilityText(text: Resource) 81 82Sets the accessibility text, with support for resource references using **Resource**. When a component does not contain a text attribute, you can use this API to set an accessibility text attribute, so that accessibility services can announce the specified content for the component. 83 84**Widget capability**: This API can be used in ArkTS widgets since API version 12. 85 86**Atomic service API**: This API can be used in atomic services since API version 12. 87 88**System capability**: SystemCapability.ArkUI.ArkUI.Full 89 90**Parameters** 91 92| Name| Type | Mandatory| Description | 93| ------ | ------ | ---- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 94| 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**.| 95 96 97## accessibilityDescription 98 99accessibilityDescription(value: string) 100 101Sets the accessibility description. This property provides additional context or explanation for the component, helping users understand the action or function it performs. 102 103**Widget capability**: This API can be used in ArkTS widgets since API version 12. 104 105**Atomic service API**: This API can be used in atomic services since API version 11. 106 107**System capability**: SystemCapability.ArkUI.ArkUI.Full 108 109**Parameters** 110 111| Name| Type | Mandatory| Description | 112| ------ | ------ | ---- | ------------------------------------------------------------ | 113| 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: **""**| 114 115## accessibilityDescription<sup>12+</sup> 116 117accessibilityDescription(description: Resource) 118 119Sets the accessibility description, with support for resource references using **Resource**. This property provides additional context or explanation for the component, helping users understand the action or function it performs. 120 121**Widget capability**: This API can be used in ArkTS widgets since API version 12. 122 123**Atomic service API**: This API can be used in atomic services since API version 12. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Parameters** 128 129| Name| Type | Mandatory| Description | 130| ------ | ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 131| 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.| 132 133## accessibilityLevel 134 135accessibilityLevel(value: string) 136 137Sets the accessibility level. This property determines whether the component can be recognized by accessibility services. 138 139**Widget capability**: This API can be used in ArkTS widgets since API version 12. 140 141**Atomic service API**: This API can be used in atomic services since API version 11. 142 143**System capability**: SystemCapability.ArkUI.ArkUI.Full 144 145**Parameters** 146 147| Name| Type | Mandatory| Description | 148| ------ | ------ | ---- | ------------------------------------------------------------ | 149| 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 component's recognizability is determined by the accessibility grouping service and ArkUI.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**NOTE**<br>When accessibilityLevel is set to **"auto"**, the component's recognizability depends on the following factors:<br>1. The accessibility service internally determines whether the component can be recognized.<br>2. If the parent component's **accessibilityGroup** property has **isGroup** set to **true**, the accessibility service will not focus on its child components, making them unrecognizable.<br>3. If the parent component's **accessibilityLevel** is set to **"no-hide-descendants"**, the component will not be recognized by accessibility services.| 150 151## accessibilityVirtualNode<sup>11+</sup> 152 153accessibilityVirtualNode(builder: CustomBuilder) 154 155Sets an accessibility virtual child node. For custom drawing components, a **CustomBuilder** is passed, which is used to provide accessibility information. The components within the **CustomBuilder** are only used for layout and not for display. When the accessibility service obtains node information, it returns the node information from the **CustomBuilder**. 156 157**Widget capability**: This API can be used in ArkTS widgets since API version 12. 158 159**Atomic service API**: This API can be used in atomic services since API version 11. 160 161**System capability**: SystemCapability.ArkUI.ArkUI.Full 162 163**Parameters** 164 165| Name| Type | Mandatory| Description | 166| ------ | ------ | ---- | ------------------------------------------------------------ | 167| 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.| 168 169## accessibilityChecked<sup>13+</sup> 170 171accessibilityChecked(isCheck: boolean) 172 173Sets the checked state of the accessibility component. This property is used in multiselect scenarios. 174 175**Widget capability**: This API can be used in ArkTS widgets since API version 13. 176 177**Atomic service API**: This API can be used in atomic services since API version 13. 178 179**System capability**: SystemCapability.ArkUI.ArkUI.Full 180 181**Parameters** 182 183| Name | Type | Mandatory| Description | 184| ------- | ------- | ---- | ------------------------------------------------------------ | 185| 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**.| 186 187## accessibilitySelected<sup>13+</sup> 188 189accessibilitySelected(isSelect: boolean) 190 191Sets the selected state of the accessibility component. This property is used in single-select scenarios. 192 193**Widget capability**: This API can be used in ArkTS widgets since API version 13. 194 195**Atomic service API**: This API can be used in atomic services since API version 13. 196 197**System capability**: SystemCapability.ArkUI.ArkUI.Full 198 199**Parameters** 200 201| Name | Type | Mandatory| Description | 202| -------- | ------- | ---- | ------------------------------------------------------------ | 203| 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**.| 204 205## accessibilityRole<sup>18+</sup> 206 207accessibilityRole(role: AccessibilityRoleType) 208 209Sets the role type of the accessibility component, which affects how the component is announced by screen readers. 210 211**Widget capability**: This API can be used in ArkTS widgets since API version 18. 212 213**Atomic service API**: This API can be used in atomic services since API version 18. 214 215**System capability**: SystemCapability.ArkUI.ArkUI.Full 216 217**Parameters** 218 219| Name | Type | Mandatory| Description | 220| -------- | ------- | ---- | ------------------------------------------------------------ | 221| role | [AccessibilityRoleType](ts-universal-attributes-accessibility.md#accessibilityroletype18) | Yes | Role of the component as announced by screen readers (for example, button or chart). You can define custom roles.| 222 223## AccessibilityRoleType<sup>18+</sup> 224 225Enumerates the component role types used by screen readers. 226 227**Atomic service API**: This API can be used in atomic services since API version 18. 228 229**System capability**: SystemCapability.ArkUI.ArkUI.Full 230 231| Name| Value | Description | 232| ---- | ---- | ------------------ | 233| ACTION_SHEET | 0 | Action sheet.| 234| ALERT_DIALOG | 1 | Alert dialog box.| 235| INDEXER_COMPONENT | 2 | Indexer component.| 236| BADGE_COMPONENT | 3 | Badge component.| 237| BLANK | 4 | Blank placeholder component.| 238| BUTTON | 5 | Button.| 239| BACK_BUTTON | 6 | Back button on a large image page.| 240| SHEET_DRAG_BAR | 7 | Drag bar for sheets.| 241| CALENDAR_PICKER | 8 | Calendar picker.| 242| CALENDAR | 9 | Calendar.| 243| CANVAS | 10 | Canvas component.| 244| CANVAS_GRADIENT | 11 | Gradient object.| 245| CANVAS_PATTERN | 12 | Pattern for image filling based on a specified source image and repetition mode.| 246| CHECKBOX | 13 | Check box component.| 247| CHECKBOX_GROUP | 14 | Check box group.| 248| CIRCLE | 15 | Component for drawing circles.| 249| COLUMN_SPLIT | 16 | Vertical layout of child components with horizontal dividers.| 250| COLUMN | 17 | Container that lays out child components vertically.| 251| CANVAS_RENDERING_CONTEXT_2D | 18 | 2D drawing object, which can be used to draw rectangles, images, and texts on the canvas component.| 252| CHART | 19 | Chart component.| 253| COUNTER | 20 | Counter component.| 254| CONTAINER_MODAL | 21 | Modal container.| 255| DATA_PANEL | 22 | Data panel component.| 256| DATE_PICKER | 23 | Date picker.| 257| DIALOG | 24 | Dialog box.| 258| DIVIDER | 25 | Divider component.| 259| DRAG_BAR | 26 | Drag bar.| 260| EFFECT_COMPONENT | 27 | Container component for special effects.| 261| ELLIPSE | 28 | Ellipse drawing component.| 262| FLEX | 29 | Container that allows for flexible layout of child components.| 263| FLOW_ITEM | 30 | Child component of a waterfall layout container.| 264| FORM_COMPONENT | 31 | Widget component.| 265| FORM_LINK | 32 | Static widget interaction component.| 266| GAUGE | 33 | Gauge component.| 267| GRID | 34 | Grid container.| 268| GRID_COL | 35 | Grid column component.| 269| GRID_CONTAINER | 36 | Grid container that lays out child components vertically.| 270| GRID_ITEM | 37 | Single-item container within a grid container.| 271| GRID_ROW | 38 | Grid row component.| 272| HYPERLINK | 39 | Hyperlink component.| 273| IMAGE | 40 | Image component| 274| IMAGE_ANIMATOR | 41 | Frame animation component.| 275| IMAGE_BITMAP | 42 | Pixel data for canvas rendering.| 276| IMAGE_DATA | 43 | Pixel data for canvas rendering.| 277| IMAGE_SPAN | 44 | Component used to display inline images.| 278| LABEL | 45 | Label.| 279| LINE | 46 | Line.| 280| LIST | 47 | List.| 281| LIST_ITEM | 48 | Specific item in a list.| 282| LIST_ITEM_GROUP | 49 | List item group.| 283| LOADING_PROGRESS | 50 | Component for display loading animations.| 284| MARQUEE | 51 | Marquee component.| 285| MATRIX2D | 52 | 2D matrix object.| 286| MENU | 53 | Menu.| 287| MENU_ITEM | 54 | Menu item.| 288| MENU_ITEM_GROUP | 55 | Menu item group.| 289| NAV_DESTINATION | 56 | Content area of the **Navigation** component.| 290| NAV_ROUTER | 57 | Navigation component.| 291| NAVIGATION | 58 | Root view container for navigation routing.| 292| NAVIGATION_BAR | 59 | Navigation bar.| 293| NAVIGATION_MENU | 60 | Navigation menu.| 294| NAVIGATOR | 61 | Navigation container component.| 295| OFFSCREEN_CANVAS | 62 | Canvas for custom drawing of graphics.| 296| OFFSCREEN_CANVAS_RENDERING_CONTEXT2D | 63 | 2D drawing object, which can be used to draw rectangles, images, and texts on a canvas component.| 297| OPTION | 64 | Specific item.| 298| PANEL | 65 | Slidable panel.| 299| PAPER_PAGE | 66 | Page.| 300| PATH | 67 | Path drawing component.| 301| PATH2D | 68 | Path object.| 302| PATTERN_LOCK | 69 | Pattern lock component.| 303| PICKER | 70 | Picker.| 304| PICKER_VIEW | 71 | Picker view.| 305| PLUGIN_COMPONENT | 72 | Plugin component.| 306| POLYGON | 73 | Component used to draw a polygon.| 307| POLYLINE | 74 | Component used to draw a polyline.| 308| POPUP | 75 | Popup with a specific style.| 309| PROGRESS | 76 | Text download button.| 310| QRCODE | 77 | QR code.| 311| RADIO | 78 | Radio button.| 312| RATING | 79 | Component for selecting a rating within a given range.| 313| RECT | 80 | Component used to draw a rectangle.| 314| REFRESH | 81 | Pull-to-refresh container component.| 315| RELATIVE_CONTAINER | 82 | Relative layout component.| 316| REMOTE_WINDOW | 83 | Remote control window component.| 317| RICH_EDITOR | 84 | Component that supports rich text editing and interactive text editing.| 318| RICH_TEXT | 85 | Rich text component.| 319| ROLE_PAGER | 86 | Pagination component.| 320| ROW | 87 | Container that lays out child components horizontally.| 321| ROW_SPLIT | 88 | Horizontal layout of child components with vertical dividers.| 322| SCROLL | 89 | Scrollable container component.| 323| SCROLL_BAR | 90 | Scrollbar.| 324| SEARCH | 91 | Search box component.| 325| SEARCH_FIELD | 92 | Search box.| 326| SELECT | 93 | Drop-down list component.| 327| SHAPE | 94 | Parent component of the drawing components.| 328| SIDEBAR_CONTAINER | 95 | Sidebar container that can show and hide the sidebar.| 329| SLIDER | 96 | Vertical slider.| 330| SPAN | 97 | Component used to display inline text.| 331| STACK | 98 | Stack container.| 332| STEPPER | 99 | Stepper component.| 333| STEPPER_ITEM | 100 | Page child component of the stepper component.| 334| SWIPER | 101 | Swiper view container.| 335| SWIPER_INDICATOR | 102 | Navigation indicator for the **Swiper** component.| 336| SWITCH | 103 | Switch.| 337| SYMBOL_GLYPH | 104 | Component for displaying a symbol glyph.| 338| TAB_CONTENT | 105 | Content view for a tab in the **Tabs** component.| 339| TAB_BAR | 106 | Tab bar.| 340| TABS | 107 | Container that allows users to switch between content views through tabs.| 341| TEXT | 108 | Text.| 342| TEXT_CLOCK | 109 | Text clock component.| 343| TEXT_ENTRY | 110 | Text input.| 344| TEXT_INPUT | 111 | Text box component.| 345| TEXT_PICKER | 112 | Text picker.| 346| TEXT_TIMER | 113 | Component that displays timing information and is controlled in text format.| 347| TEXT_AREA | 114 | Text area component.| 348| TEXT_FIELD | 115 | Text box.| 349| TIME_PICKER | 116 | Time picker.| 350| TITLE_BAR | 117 | Title bar.| 351| TOGGLER | 118 | Status component.| 352| UI_EXTENSION_COMPONENT | 119 | UI extension component.| 353| VIDEO | 120 | Component for playing video files and controlling playback.| 354| WATER_FLOW | 121 | Waterfall layout container.| 355| WEB | 122 | Component for loading web pages.| 356| XCOMPONENT | 123 | Custom rendering component.| 357| ROLE_NONE | 124 | Null.| 358 359## accessibilityNextFocusId<sup>18+</sup> 360 361accessibilityNextFocusId(nextId: string) 362 363Sets the next focus target for the component during focus traversal. 364 365**Widget capability**: This API can be used in ArkTS widgets since API version 18. 366 367**Atomic service API**: This API can be used in atomic services since API version 18. 368 369**System capability**: SystemCapability.ArkUI.ArkUI.Full 370 371**Parameters** 372 373| Name| Type | Mandatory| Description | 374| ------ | ------ | ---- | ------------------------------------------------------------ | 375| nextId | string | Yes | [Unique ID](ts-universal-attributes-component-id.md#id) of the next component to receive focus. If the ID does not correspond to any component, the setting is invalid.| 376 377## accessibilityDefaultFocus<sup>18+</sup> 378 379accessibilityDefaultFocus(focus: boolean) 380 381Sets whether the component is the default initial focus for screen readers on the current page. 382 383**Widget capability**: This API can be used in ArkTS widgets since API version 18. 384 385**Atomic service API**: This API can be used in atomic services since API version 18. 386 387**System capability**: SystemCapability.ArkUI.ArkUI.Full 388 389**Parameters** 390 391| Name| Type | Mandatory| Description | 392| ------ | ------- | ---- | ------------------------------------------------------------ | 393| focus | boolean | Yes | Whether the component is the default initial focus for screen readers on the current page. The value **true** means the component is the default initial focus for screen readers on the current page. Other values are invalid.| 394 395## accessibilityUseSamePage<sup>18+</sup> 396 397accessibilityUseSamePage(pageMode: AccessibilitySamePageMode) 398 399Solves focus jumping issues in sub-tree scenarios for cross-process embedded components, such as **UIExtensionComponent**. Focus jumping occurs when the timing of page events from the embedded component's process conflicts with those of the host application, causing focus to unexpectedly shift between components. 400 401**Widget capability**: This API can be used in ArkTS widgets since API version 18. 402 403**Atomic service API**: This API can be used in atomic services since API version 18. 404 405**System capability**: SystemCapability.ArkUI.ArkUI.Full 406 407**Parameters** 408 409| Name | Type | Mandatory| Description | 410| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ | 411| pageMode | [AccessibilitySamePageMode](#accessibilitysamepagemode18) | Yes | Same-page mode for the cross-process embedded component and the host application.| 412 413## AccessibilitySamePageMode<sup>18+</sup> 414 415Enumerates the same-page modes for cross-process embedded components and their host applications. 416 417**Atomic service API**: This API can be used in atomic services since API version 18. 418 419**System capability**: SystemCapability.ArkUI.ArkUI.Full 420 421| Name | Value | Description | 422| ----------- | ---- | ------------------------------------------------------------ | 423| SEMI_SILENT | 0 | Ignores initial page loading events and root node page events from the cross-process embedded component.| 424| FULL_SILENT | 1 | Ignores all page events from the cross-process embedded component. | 425 426## accessibilityScrollTriggerable<sup>18+</sup> 427 428accessibilityScrollTriggerable(isTriggerable: boolean) 429 430Sets whether to enable automatic scrolling for screen readers when the current page has no focusable components. 431 432**Widget capability**: This API can be used in ArkTS widgets since API version 18. 433 434**Atomic service API**: This API can be used in atomic services since API version 18. 435 436**System capability**: SystemCapability.ArkUI.ArkUI.Full 437 438**Parameters** 439 440| Name | Type | Mandatory| Description | 441| -------------- | ------- | ---- | ------------------------------------------------------------ | 442| isTriggerable | boolean | Yes | Whether the component supports automatic scrolling for screen readers when the current page has no focusable components.<br>The options are as follows:<br>**true**: The component triggers automatic scrolling for screen readers when the current page has no focusable components.<br>**false**: The component does not trigger automatic scrolling for screen readers when the current page has no focusable components.<br>**undefined**: The default settings are restored.<br>Default value: **true**<br>**NOTE**<br>1. This parameter does not affect the original **scrollable** attribute of the component.<br>2. The final scrolling behavior is determined by the screen reader based on this parameter and whether the component supports scrolling.<br>3. This API applies to all basic components. It is recommended for scrollable components, including **List**, **Grid**, **Scroll**, and **WaterFlow**.| 443 444## accessibilityTextHint<sup>12+</sup> 445 446accessibilityTextHint(value: string) 447 448Sets the text hint for the component, which can be queried by accessibility services. 449 450**Widget capability**: This API can be used in ArkTS widgets since API version 12. 451 452**Atomic service API**: This API can be used in atomic services since API version 12. 453 454**System capability**: SystemCapability.ArkUI.ArkUI.Full 455 456**Parameters** 457 458| Name | Type | Mandatory| Description | 459| -------------- | ------- | ---- | ------------------------------------------------------------ | 460| value | string | Yes | Text hint for the component, which can be queried by accessibility services.| 461 462## accessibilityFocusDrawLevel<sup>19+</sup> 463 464accessibilityFocusDrawLevel(drawLevel: FocusDrawLevel) 465 466Sets the drawing level for the accessibility focus highlight frame. 467 468> **NOTE** 469> 470> 1. By default, the accessibility focus highlight frame is drawn at the same level as the focused component. This can sometimes result in the frame being obscured or clipped by parent components or siblings with higher z-order. 471> 472> 2. Setting the drawing level to the topmost layer ensures that the accessibility focus highlight frame is not obscured by other components. This is useful when you want the highlight frame to be clearly visible at all times. However, this setting may not be suitable if you need to interact with components that should overlay the currently focused component and you do not want the accessibility highlight to be visible. 473 474 475**Widget capability**: This API can be used in ArkTS widgets since API version 19. 476 477**Atomic service API**: This API can be used in atomic services since API version 19. 478 479**System capability**: SystemCapability.ArkUI.ArkUI.Full 480 481**Parameters** 482 483| Name | Type | Mandatory| Description | 484| -------- | ------- | ---- | ------------------------------------------------------------ | 485| drawLevel | [FocusDrawLevel](ts-appendix-enums.md#focusdrawlevel19) | Yes | Drawing level for the accessibility focus highlight frame.| 486 487## Example 488 489### Example 1: Setting Accessibility Text and Description 490 491This example demonstrates how to use **accessibilityText** and **accessibilityDescription** to customize the content announced by screen readers. 492 493```ts 494// xxx.ets 495@Entry 496@Component 497struct Index { 498 499 @Builder customAccessibilityNode() { 500 Column() { 501 Text(`virtual node`) 502 } 503 .width(10) 504 .height(10) 505 } 506 507 build() { 508 Row() { 509 Column() { 510 Text("Text 1") 511 .fontSize(50) 512 .fontWeight(FontWeight.Bold) 513 Text("Text 2") 514 .fontSize(50) 515 .fontWeight(FontWeight.Bold) 516 } 517 .width('100%') 518 .accessibilityGroup(true) 519 .accessibilityLevel("yes") 520 .accessibilityText("Group") // If a component has both text content and accessibility text, only the accessibility text is announced. 521 .accessibilityDescription("The Column component can be selected, and the announced content is 'Group'") 522 .accessibilityVirtualNode(this.customAccessibilityNode) 523 .accessibilityChecked(true) 524 .accessibilitySelected(undefined) 525 } 526 .height('100%') 527 } 528} 529``` 530 531### Example 2: Setting the Accessibility Group 532 533This example shows how to use **accessibilityGroup** to prioritize reading the accessibility text of child components. 534 535```ts 536// xxx.ets 537@Entry 538@Component 539struct Focus { 540 build() { 541 Column({ space: 10 }) { 542 Text('123456') 543 .focusable(true) 544 .borderRadius(5) 545 .accessibilityText("Accessibility text is announced if both accessibility text and text content are present") 546 .accessibilityLevel("yes") 547 Button().accessibilityLevel("yes").accessibilityText("Accessibility text is announced if no text is present") 548 Button("Text content is announced if no accessibility text is present").accessibilityLevel("yes") 549 Button() 550 Button('btn123').accessibilityText("Button with both accessibility text and text").accessibilityLevel("yes") 551 Button('btn123').accessibilityLevel("yes") 552 } 553 .accessibilityGroup(true, { accessibilityPreferred: true }) 554 .borderWidth(5) 555 .width('100%') 556 .height('100%') 557 } 558} 559``` 560 561### Example 3: Setting the Initial Focus and the Next Focus of a Component 562 563This example demonstrates the use of **accessibilityDefaultFocus** to set the default initial focus for the screen reader on the current page and **accessibilityNextFocusId** to set the next focus for components during focus traversal. 564 565```ts 566// xxx.ets 567@Entry 568@Component 569struct Index { 570 build() { 571 Column({ space: 20 }) { 572 Text('Text Demo 1') 573 .fontSize(50) 574 .accessibilityLevel('yes') 575 .accessibilityNextFocusId('text3') 576 Text('Text Demo 2') 577 .id('text2') 578 .fontSize(50) 579 .accessibilityLevel('yes') 580 .accessibilityDefaultFocus(true) // Set the component as initial focus for the screen reader. 581 .accessibilityNextFocusId('text4') 582 Text('Text Demo 3') 583 .id('text3') 584 .fontSize(50) 585 .accessibilityLevel('yes') 586 .accessibilityNextFocusId('text2') 587 Text('Text Demo 4') 588 .id('text4') 589 .fontSize(50) 590 .accessibilityLevel('yes') 591 } 592 .height('100%') 593 .width('100%') 594 } 595} 596``` 597 598### Example 4: Setting the Accessibility Component Type and Text Hint 599 600This example demonstrates the use of **accessibilityRole** to set the accessibility component type and **accessibilityTextHint** to provide text hints for components that can be queried by assistive technologies. 601 602```ts 603// xxx.ets 604@Entry 605@Component 606struct Index { 607 @State isDownloading: boolean = false; 608 @State hintStr: string = 'Click to start download'; 609 610 build() { 611 Column({ space: 20 }) { 612 Button(this.isDownloading ? 'Downloading' : 'Click to download') 613 .accessibilityLevel('yes') 614 .accessibilityTextHint(this.hintStr) 615 .onClick(() => { 616 this.isDownloading = !this.isDownloading; 617 this.hintStr = this.isDownloading ? 'Status changed to downloading' : 'Status changed to paused'; 618 }) 619 TextInput({ placeholder: 'Enter phone number' }) 620 .accessibilityLevel('yes') 621 .accessibilityTextHint('Enter an 11-digit phone number') 622 .width('80%') 623 Text('Announced as button type') 624 .accessibilityLevel('yes') 625 .accessibilityRole(AccessibilityRoleType.BUTTON) 626 .accessibilityTextHint('The screen reader will announce this component as a button') 627 .fontSize(30) 628 } 629 .height('100%') 630 .width('100%') 631 } 632} 633``` 634 635### Example 5: Configuring Screen Reader Scrolling, Focus Highlight Frame, and Cross-Process Focus 636 637This example demonstrates the use of **accessibilityScrollTriggerable** to set whether an accessibility node supports screen reading scroll, **accessibilityFocusDrawLevel** to set the drawing level of the accessibility focus highlight frame, and **accessibilityUseSamePage** for cross-process embedded components like **EmbeddedComponent**. 638 639```ts 640// xxx.ets 641import { Want } from '@kit.AbilityKit'; 642 643@Entry 644@Component 645struct Index { 646 @State message: string = 'Message: '; 647 private want: Want = { 648 bundleName: 'com.example.embeddeddemo', 649 abilityName: 'ExampleEmbeddedAbility', 650 } 651 652 build() { 653 Row() { 654 List() { 655 ListItem() { 656 Column() { 657 Text(this.message) 658 .fontSize(18) 659 .fontColor('#2D2D2D') 660 .fontWeight(FontWeight.Medium) 661 Column() { 662 EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION) 663 .width('100%') 664 .height('90%') 665 .onTerminated((info) => { 666 this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want); 667 }) 668 .onError((error) => { 669 this.message = 'Error: code = ' + error.code; 670 }) 671 .accessibilityUseSamePage(AccessibilitySamePageMode.FULL_SILENT) 672 .width('90%') 673 .height('50%') 674 .backgroundColor('#F0F0F0') 675 .borderRadius(8) 676 .borderWidth(1) 677 .borderColor('#D9D9D9') 678 679 Stack() { 680 Column() { 681 Text('Text 1') 682 .fontSize(18) 683 .fontColor('#2D2D2D') 684 .fontWeight(FontWeight.Medium) 685 Text('Text 1') 686 .fontSize(18) 687 .fontColor('#2D2D2D') 688 .fontWeight(FontWeight.Medium) 689 .accessibilityFocusDrawLevel(FocusDrawLevel.TOP) 690 } 691 .padding({ top: 8, bottom: 8 }) 692 693 Column() { 694 Text('Text 2') 695 .fontSize(18) 696 .fontColor('#FFFFFF') 697 .fontWeight(FontWeight.Medium) 698 Text('Text 2') 699 .fontSize(18) 700 .fontColor('#FFFFFF') 701 .fontWeight(FontWeight.Medium) 702 } 703 .backgroundColor('#4A90E2') 704 .padding({ 705 left: 12, 706 right: 12, 707 top: 10, 708 bottom: 10 709 }) 710 .borderRadius(6) 711 } 712 .width('100%') 713 .margin({ top: 10, bottom: 10 }) 714 } 715 .width('100%') 716 .height('100%') 717 .margin({ top: 15 }) 718 .accessibilityText($r('app.string.app_name')) 719 .accessibilityDescription($r('app.string.module_desc')) 720 Column() { 721 Text('Text 4') 722 .fontSize(18) 723 .fontWeight(FontWeight.Medium) 724 } 725 .margin({ top: 15 }) 726 } 727 .width('100%') 728 } 729 } 730 .accessibilityScrollTriggerable(false) 731 .width('100%') 732 } 733 .height('100%') 734 .backgroundColor('#F7F9FC') 735 } 736} 737``` 738 739 740
