Overview
Declares the APIs for accessing Native Accessibility features, providing accessibility-related capabilities. It supports third-party frameworks in integrating their UI components into the ArkUI accessibility service system, including registering accessibility callbacks, setting and querying accessibility node information, proactively reporting accessibility events, and adapting to multi-instance scenarios. This enables the system accessibility service to recognize and operate UI components of third-party frameworks, making it suitable for scenarios where third-party UI frameworks need to interact with system accessibility capabilities.
File to include: <arkui/native_interface_accessibility.h>
Library: libace_ndk.z.so
System capability: SystemCapability.ArkUI.ArkUI.Full
Since: 13
Related module: ArkUI_Accessibility
Sample: AccessibilityCapi
[h2]Structs
| Name | typedef Keyword | Description |
|---|---|---|
| ArkUI_AccessibleAction | ArkUI_AccessibleAction | Defines accessible action content. This struct is used to describe the action types supported by an accessibility node and their description information. It enables the accessibility service to present executable actions (such as click, long press, and scroll) to users, and provides text description of the actions to help users understand their meanings. |
| ArkUI_AccessibleRect | ArkUI_AccessibleRect | Defines rectangular area coordinates of a node on the screen. This struct is used to describe the bounding rectangle of an accessibility node, defining the visible area of the node on the screen through the coordinates of the top-left and bottom-right corners. It enables the accessibility service to obtain the position and size information of the node. |
| ArkUI_AccessibleRangeInfo | ArkUI_AccessibleRangeInfo | Represents the range value information of a specific component (such as Slider, Rating, and Progress), including the current value, maximum value, and minimum value, for the accessibility service to read and announce to users. |
| ArkUI_AccessibleGridInfo | ArkUI_AccessibleGridInfo | Describes the overall layout attributes of a grid component. This struct is used to provide information such as the row count, column count, and selection mode of the grid component to the accessibility service, enabling the accessibility service to obtain the overall layout information of the grid. |
| ArkUI_AccessibleGridItemInfo | ArkUI_AccessibleGridItemInfo | Describes the accessibility attributes of a grid item in a grid component. This struct provides information such as the position, span, and selected state of a grid item to the accessibility service, enabling the accessibility service to obtain the layout information of the grid item. |
| ArkUI_AccessibilityProviderCallbacks | ArkUI_AccessibilityProviderCallbacks | Defines callback functions of a third-party provider. The functions that need to be implemented by the third-party platform are registered with the system through OH_ArkUI_AccessibilityProviderRegisterCallback. This struct is applicable to accessibility scenarios such as screen readers, voice control, and switch control. The third-party platform responds to the system's accessibility query and action requests by implementing these callbacks. All callback functions are executed on the IPC thread, not the UI thread. |
| ArkUI_AccessibilityProviderCallbacksWithInstance | ArkUI_AccessibilityProviderCallbacksWithInstance | Defines callback functions of a third-party action provider in multi-instance scenarios, including node information query, focus search and clearing, action execution, and cursor position obtaining. The functions that need to be implemented by the third-party platform are registered with the system through OH_ArkUI_AccessibilityProviderRegisterCallbackWithInstance to support the third-party platform in integrating with the system accessibility service. All callback functions are executed on the IPC thread, not the UI thread. |
| ArkUI_AccessibilityElementInfo | ArkUI_AccessibilityElementInfo | Defines accessibility node information, which is used to transfer element attributes, actions, positions, text, and other information to the accessibility service and assistive applications (such as screen readers). It is applicable to assistance scenarios where the accessibility service obtains and operates UI elements. |
| ArkUI_AccessibilityEventInfo | ArkUI_AccessibilityEventInfo | Describes the accessibility event information. After a component completes an action requested by an accessibility service or application, it needs to send a success event to confirm the action. This applies to scenarios where feedback on the action execution status needs to be provided to the accessibility service. |
| ArkUI_AccessibilityProvider | ArkUI_AccessibilityProvider | Defines a provider for third-party accessibility actions, which is used to implement callback functions. You can register and manage accessibility-related callbacks through this struct to implement custom accessibility interaction logic. It is suitable for scenarios where ArkUI accessibility capabilities need to be extended or customized. |
| ArkUI_AccessibilityActionArguments | ArkUI_AccessibilityActionArguments | Sets the arguments of accessibility actions. When an accessibility action is performed, this struct is used to transfer additional context information required by the action to the accessibility service. It is suitable for scenarios where you need to precisely describe the details of an accessibility action to the accessibility service, such as screen reader announcements in custom components, operation parameter transfer in assistant services, and interactions triggered by voice assistants. |
| ArkUI_AccessibilityElementInfoList | ArkUI_AccessibilityElementInfoList | Provides a List instance of encapsulated ArkUI_AccessibilityElementInfo, which is used to store and manage accessibility element information in batches. It is suitable for scenarios where information of multiple accessibility elements needs to be obtained at once. |
| ArkUI_Node* | ArkUI_NodeHandle | Defines the pointer to an ArkUI native component object, which is used to identify and pass component instances in ArkUI native APIs, for example, creating, mounting, removing, or destroying component nodes. Since: 23 |
[h2]Enums
| Name | typedef Keyword | Description |
|---|---|---|
| ArkUI_Accessibility_ActionType | ArkUI_Accessibility_ActionType | Enumerates accessibility action types. |
| ArkUI_AccessibilityEventType | ArkUI_AccessibilityEventType | Enumerates accessibility event types. |
| ArkUI_AcessbilityErrorCode | ArkUI_AcessbilityErrorCode | Enumerates accessibility error codes. |
| ArkUI_AccessibilitySearchMode | ArkUI_AccessibilitySearchMode | Enumerates accessibility search modes. |
| ArkUI_AccessibilityFocusType | ArkUI_AccessibilityFocusType | Enumerates accessibility focus types. |
| ArkUI_AccessibilityFocusMoveDirection | ArkUI_AccessibilityFocusMoveDirection | Enumerates accessibility focus movement directions. |
[h2]Functions
[h2]ArkUI_Accessibility_ActionType
enum ArkUI_Accessibility_ActionType
Description
Enumerates accessibility action types.
Since: 13
| Value | Description |
|---|---|
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_INVALID = 0 | Invalid value. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CLICK = 0x00000010 | Triggers the component's click event handling. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_LONG_CLICK = 0x00000020 | Triggers the component's long-press event handling. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_GAIN_ACCESSIBILITY_FOCUS = 0x00000040 | Gains accessibility focus for the component. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CLEAR_ACCESSIBILITY_FOCUS = 0x00000080 | Clears accessibility focus from the component. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_FORWARD = 0x00000100 | Initiates forward scrolling in scrollable containers. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_BACKWARD = 0x00000200 | Initiates backward scrolling in scrollable containers. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_COPY = 0x00000400 | Copies the current text selection. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_PASTE = 0x00000800 | Pastes content to the text component. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CUT = 0x00001000 | Cuts the current text selection to the pasteboard. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SELECT_TEXT = 0x00002000 | Selects a range of text within an editable area in a text component by using ArkUI_AccessibilityActionArguments and setting selectTextBegin (indicates the start position of the selection), selectTextEnd (indicates the end position of the selection), and selectTextInForward (true indicates to select text forward, and false indicates to select text backward). |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SET_TEXT = 0x00004000 | Sets the text content of the text component. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SET_CURSOR_POSITION = 0x00100000 | Sets the cursor position where the text can be entered for the text component. This enumerated value is used together with ArkUI_AccessibilityActionArguments. |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_NEXT_HTML_ITEM = 0x02000000 | Moves focus to the next focusable component. Note: "HTML" indicates the web-like navigation capability, not actual web elements. This attribute is available only when the findNextFocusAccessibilityNode capability is implemented. Since: 15 |
| ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_PREVIOUS_HTML_ITEM = 0x04000000 | Moves focus to the previous focusable component. Note: "HTML" indicates the web-like navigation capability, not actual web elements. This attribute is available only when the findNextFocusAccessibilityNode capability is implemented. Since: 15 |
[h2]ArkUI_AccessibilityEventType
enum ArkUI_AccessibilityEventType
Description
Enumerates accessibility event types.
Since: 13
| Value | Description |
|---|---|
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_INVALID = 0 | Invalid value. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_CLICKED = 0x00000001 | Event about content being clicked, sent after the UI component responds. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_LONG_CLICKED = 0x00000002 | Event about content being long-pressed, sent after the UI component responds. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_SELECTED = 0x00000004 | Event about content being selected, sent after the UI component responds. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_TEXT_UPDATE = 0x00000010 | Text update event, sent when text is updated. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_STATE_UPDATE = 0x00000020 | Page state update event, sent on page navigation, switching, resizing, or movement. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_CONTENT_UPDATE = 0x00000800 | Page content update event, sent when the page content changes. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_SCROLLED = 0x000001000 | Event about content being scrolled, sent when scrolling occurs on scrollable components. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_ACCESSIBILITY_FOCUSED = 0x00008000 | Accessibility focus event, sent after the UI component receives focus. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_ACCESSIBILITY_FOCUS_CLEARED = 0x00010000 | Accessibility focus cleared event, sent after the UI component loses focus. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_REQUEST_ACCESSIBILITY_FOCUS = 0x02000000 | Event to actively request focus for the specified node. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_OPEN = 0x20000000 | Page open event reported by the UI component. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_CLOSE = 0x08000000 | Page close event reported by the UI component. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_ANNOUNCE_FOR_ACCESSIBILITY = 0x10000000 | Announcement event, indicating a request to proactively announce specified content. |
| ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_FOCUS_NODE_UPDATE = 0x10000001 | Focus update event, used in the focus update scenarios. |
[h2]ArkUI_AcessbilityErrorCode
enum ArkUI_AcessbilityErrorCode
Description
Enumerates accessibility error codes.
Since: 13
| Value | Description |
|---|---|
| ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL = 0 | The operation is successful. |
| ARKUI_ACCESSIBILITY_NATIVE_RESULT_FAILED = -1 | The operation failed. Possible cause: An internal error occurred during API execution. Solution: Verify that the call flow is correct. If the issue persists, check the system status. |
| ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER = -2 | Invalid parameter. Possible cause: The input parameter is a null pointer or does not meet API requirements. Solution: Check whether the input parameter is valid, and ensure that the pointer is not null and the parameter value is within the valid range. |
| ARKUI_ACCESSIBILITY_NATIVE_RESULT_OUT_OF_MEMORY = -3 | Insufficient memory. Possible cause: The system memory resources are insufficient to complete the operation. Solution: Check the system memory usage, release unnecessary resources, and try again. |
[h2]ArkUI_AccessibilitySearchMode
enum ArkUI_AccessibilitySearchMode
Description
Enumerates accessibility search modes.
Since: 13
| Value | Description |
|---|---|
| ARKUI_ACCESSIBILITY_NATIVE_SEARCH_MODE_PREFETCH_CURRENT = 0 | Searches the current node. |
| ARKUI_ACCESSIBILITY_NATIVE_SEARCH_MODE_PREFETCH_PREDECESSORS = 1 << 0 | Searches parent nodes. |
| ARKUI_ACCESSIBILITY_NATIVE_SEARCH_MODE_PREFETCH_SIBLINGS = 1 << 1 | Searches sibling nodes. |
| ARKUI_ACCESSIBILITY_NATIVE_SEARCH_MODE_PREFETCH_CHILDREN = 1 << 2 | Searches immediate child nodes. |
| ARKUI_ACCESSIBILITY_NATIVE_SEARCH_MODE_PREFETCH_RECURSIVE_CHILDREN = 1 << 3 | Searches all child nodes. |
[h2]ArkUI_AccessibilityFocusType
enum ArkUI_AccessibilityFocusType
Description
Enumerates accessibility focus types.
Since: 13
| Value | Description |
|---|---|
| ARKUI_ACCESSIBILITY_NATIVE_FOCUS_TYPE_INVALID = -1 | Invalid value. |
| ARKUI_ACCESSIBILITY_NATIVE_FOCUS_TYPE_INPUT = 1 << 0 | Input focus type. |
| ARKUI_ACCESSIBILITY_NATIVE_FOCUS_TYPE_ACCESSIBILITY = 1 << 1 | Accessibility focus type. |
[h2]ArkUI_AccessibilityFocusMoveDirection
enum ArkUI_AccessibilityFocusMoveDirection
Description
Enumerates accessibility focus movement directions.
Since: 13
| Value | Description |
|---|---|
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_INVALID = 0 | Invalid value. |
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_UP = 0x00000001 | Moves focus up. |
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_DOWN = 0x00000002 | Moves focus down. |
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_LEFT = 0x00000004 | Moves focus left. |
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_RIGHT = 0x00000008 | Moves focus right. |
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_FORWARD = 0x00000010 | Moves focus to the next focusable node (relative to the reference node in query). |
| ARKUI_ACCESSIBILITY_NATIVE_DIRECTION_BACKWARD = 0x00000020 | Moves focus to the previous focusable node (relative to the reference node in query). |
[h2]OH_ArkUI_AccessibilityProviderRegisterCallback()
int32_t OH_ArkUI_AccessibilityProviderRegisterCallback(ArkUI_AccessibilityProvider* provider, ArkUI_AccessibilityProviderCallbacks* callbacks)
Description
Registers the callback functions of a third-party operation provider with the system. These functions are implemented by the third-party platform.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityProvider* provider | Pointer to the ArkUI_AccessibilityProvider instance. |
| ArkUI_AccessibilityProviderCallbacks* callbacks | Pointer to the ArkUI_AccessibilityProviderCallbacks instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityProviderRegisterCallbackWithInstance()
int32_t OH_ArkUI_AccessibilityProviderRegisterCallbackWithInstance(const char* instanceId, ArkUI_AccessibilityProvider* provider, ArkUI_AccessibilityProviderCallbacksWithInstance* callbacks)
Description
Registers callback functions with the system for third-party platforms in accessibility multi-instance scenarios.
Since: 15
Parameters
| Name | Description |
|---|---|
| const char* instanceId | Pointer to the instance ID for third-party platform integration, used to distinguish between different instances in multi-instance scenarios. The ID is assigned and maintained by the third-party platform. |
| ArkUI_AccessibilityProvider* provider | Handle to the third-party platform provider. |
| ArkUI_AccessibilityProviderCallbacksWithInstance* callbacks | Pointer to the ArkUI_AccessibilityProviderCallbacksWithInstance instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_SendAccessibilityAsyncEvent()
void OH_ArkUI_SendAccessibilityAsyncEvent(ArkUI_AccessibilityProvider* provider, ArkUI_AccessibilityEventInfo* eventInfo, void (*callback)(int32_t errorCode))
Description
Proactively sends an event to notify the accessibility service.
Usage flow:
- Create an event information object using OH_ArkUI_CreateAccessibilityEventInfo.
- Configure the event type and related information using APIs such as OH_ArkUI_AccessibilityEventSetEventType and OH_ArkUI_AccessibilityEventSetTextAnnouncedForAccessibility.
- Call this API to send the event.
- After sending, release the event information object using OH_ArkUI_DestoryAccessibilityEventInfo.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityProvider* provider | Handle to the third-party platform provider. |
| ArkUI_AccessibilityEventInfo* eventInfo | Pointer to the accessibility event information. |
| void (*callback)(int32_t errorCode) | Pointer to the callback invoked after the event is sent. The value 0 of errorCode indicates successful sending, and a non-zero value indicates the error code for failed sending. |
[h2]OH_ArkUI_AddAndGetAccessibilityElementInfo()
ArkUI_AccessibilityElementInfo* OH_ArkUI_AddAndGetAccessibilityElementInfo(ArkUI_AccessibilityElementInfoList* list)
Description
Adds an ArkUI_AccessibilityElementInfo member to the specified list and returns the ArkUI_AccessibilityElementInfo struct.
The ArkUI_AccessibilityElementInfo object returned by this API is uniformly managed by the passed-in ArkUI_AccessibilityElementInfoList, and its lifecycle is bound to the list. There is no need to call OH_ArkUI_DestoryAccessibilityElementInfo separately to release the object.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfoList* list | Pointer to the ArkUI_AccessibilityElementInfoList struct. After the newly created ElementInfo member is added to the list, the list is returned to the function caller. |
Returns
| Type | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* | Pointer to the created ArkUI_AccessibilityElementInfo struct. If the creation fails, NULL is returned. |
[h2]OH_ArkUI_AccessibilityElementInfoSetElementId()
int32_t OH_ArkUI_AccessibilityElementInfoSetElementId(ArkUI_AccessibilityElementInfo* elementInfo, int32_t elementId)
Description
Sets the unique ID (elementId) of an accessibility element for ArkUI_AccessibilityElementInfo.
- elementId indicates the unique identifier of a node in the accessibility component tree, which is used by the accessibility service to locate and reference the specific node. The accessibility service relies on this identifier when searching for node information, performing operations, and moving focus.
- A third-party framework must ensure that elementId of each node in the same component tree is globally unique. Otherwise, the accessibility service may fail to find the node.
- The value of elementId is allocated and maintained by the third-party framework. You are advised to use an incremental integer or a stable component ID.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t elementId | ID of an accessibility element, which must be unique in the current component tree. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetParentId()
int32_t OH_ArkUI_AccessibilityElementInfoSetParentId(ArkUI_AccessibilityElementInfo* elementInfo, int32_t parentId)
Description
Sets the accessibility ID (parentId) of the parent element for ArkUI_AccessibilityElementInfo.
- parentId is used to build a hierarchical relationship for an accessibility component tree and identify the parent node of the current node. The accessibility service depends on the parent-child relationship when traversing the node tree and searching for sibling nodes.
- If the current node is the root node, you are advised to set parentId to -1 or 0 (different from elementId of the root node).
- The parent node's elementId pointed to by parentId must exist in the component tree. Otherwise, an exception may occur when the accessibility service performs upward traversal.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t parentId | Accessibility ID of the element's parent component. The value must point to the existing elementId of the parent node. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetComponentType()
int32_t OH_ArkUI_AccessibilityElementInfoSetComponentType(ArkUI_AccessibilityElementInfo* elementInfo, const char* componentType)
Description
Sets the component type for ArkUI_AccessibilityElementInfo.
- componentType is used to identify the component type of an accessibility node, such as Button, Text, Image, and List.
- The accessibility service (such as an accessibility application) determines how to describe and interact with the node for users based on the component type. For example, the Button type is read as a button, and the Text type is read as text. A third-party framework can use its own component type name. You are advised to use the character string that is the same as the ArkUI component name to achieve the best reading effect.
- The recommended component type names include: Button, Text, Image, List, TextInput, Slider, Rating, Progress, CheckBox, Toggle, Grid, Swiper, Select, and Tab.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* componentType | Pointer to the component type string of the element. This parameter cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetContents()
int32_t OH_ArkUI_AccessibilityElementInfoSetContents(ArkUI_AccessibilityElementInfo* elementInfo, const char* contents)
Description
Sets the component text for ArkUI_AccessibilityElementInfo.
- contents specifies the main text content of a component, which will be read by accessibility applications to users.
- For text components (such as Text and TextInput), contents is usually set to the text displayed on the component.
- For non-text components (such as Button and Image), if accessibilityText is set, the accessibility applications preferentially use it.
- Call OH_ArkUI_AccessibilityElementInfoSetAccessibilityText to set accessibilityText. Otherwise, contents is used as the content to be read.
- If both contents and accessibilityText are set for the component, the accessibility application preferentially uses accessibilityText.
- A null pointer cannot be passed to contents. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* contents | Pointer to the text content recognized by the accessibility service for the element. This parameter cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetHintText()
int32_t OH_ArkUI_AccessibilityElementInfoSetHintText(ArkUI_AccessibilityElementInfo* elementInfo, const char* hintText)
Description
Sets the hint text for ArkUI_AccessibilityElementInfo.
- hintText is used as the placeholder hint text for editable components (for example, the text box) to provide auxiliary description for the components. When a component is in the hint state (isHint is set to true), accessibility applications read the value of hintText instead of contents. For example, the placeholder text "Please enter username" displayed when the text box is empty should be passed through hintText.
- hintText is used together with isHint: When isHint is set to true, accessibility applications read the value of hintText. When isHint is set to false, accessibility applications read the value of contents. You can set isHint by calling OH_ArkUI_AccessibilityElementInfoSetIsHint and set contents by calling OH_ArkUI_AccessibilityElementInfoSetContents.
- A null pointer cannot be passed to hintText. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* hintText | Pointer to the hint text. The value cannot be a null pointer. The default value is "". |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityText()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityText(ArkUI_AccessibilityElementInfo* elementInfo, const char* accessibilityText)
Description
Sets the accessibility-specific alternative text for ArkUI_AccessibilityElementInfo.
- accessibilityText indicates accessibility-specific alternative text, which is used to overwrite the content specified by contents for accessibility applications.
- If accessibilityText is set for a component and is not empty, accessibility applications preferentially announce the content specified by accessibilityText instead of contents. This attribute is applicable to scenarios where additional description is required for visual content. For example, accessibilityText can be set to "a sea photo" for the image component. In this case, even if the image does not have text content, accessibility applications can describe the meaning of the image to users.
- If accessibilityText is an empty string, accessibility applications use contents.
- A null pointer cannot be passed to accessibilityText. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* accessibilityText | Pointer to the accessibility text. The value cannot be a null pointer. The default value is "". |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityDescription()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityDescription(ArkUI_AccessibilityElementInfo* elementInfo, const char* accessibilityDescription)
Description
Sets the accessibility description for ArkUI_AccessibilityElementInfo.
- accessibilityDescription provides additional accessibility description for a component.
- After announcing the main content (specified by accessibilityText or contents) of a component, accessibility applications continue to announce the content specified by accessibilityDescription. For example, if contents of a button is set to "Submit", you can set accessibilityDescription to "Tap to submit form data". In this case, accessibility applications will read "Submit. Tap to submit form data." This attribute is applicable to scenarios where additional operation prompts or status descriptions need to be provided for users.
- A null pointer cannot be passed to accessibilityDescription. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* accessibilityDescription | Pointer to the accessibility description. The value cannot be a null pointer. The default value is "". |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetChildNodeIds()
int32_t OH_ArkUI_AccessibilityElementInfoSetChildNodeIds(ArkUI_AccessibilityElementInfo* elementInfo, int32_t childCount, int64_t* childNodeIds)
Description
Sets the number of child nodes and the child node ID array for ArkUI_AccessibilityElementInfo.
- childNodeIds is used to build a parent-child relationship for an accessibility component tree and identify all direct child nodes of the current node. The accessibility service traverses child nodes through childNodeIds to obtain a complete accessibility tree structure.
- Each time this API is called, all previously configured child node information is cleared and replaced with the child node array passed this time (update in overwriting instead of appending mode). Each value in childNodeIds corresponds to an existing elementId of a child node.
- The value of childCount must be greater than 0, and the childNodeIds array must contain at least childCount valid elements.
- A null pointer cannot be passed to childNodeIds and elementInfo, and the value of childCount cannot be less than or equal to 0. Otherwise, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t childCount | Number of child nodes, which must be greater than 0. |
| int64_t* childNodeIds | Pointer to the child node ID array. Each ID must point to an existing elementId of a child node. The value cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetOperationActions()
int32_t OH_ArkUI_AccessibilityElementInfoSetOperationActions(ArkUI_AccessibilityElementInfo* elementInfo,int32_t operationCount, ArkUI_AccessibleAction* operationActions)
Description
Sets the list of accessibility actions supported by the component for ArkUI_AccessibilityElementInfo.
operationActions is used to configure the set of accessibility operations supported by the component. Each call to this API replaces all previously set operation actions (update by overwriting but not appending). The value of operationCount must be greater than 0, and the operationActions array must contain at least operationCount valid elements. It is recommended to register the corresponding action types based on the interaction attributes of the component: clickable components should include ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CLICK, and long-pressable components should include ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_LONG_CLICK.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t operationCount | Number of actions supported by the component. The value must be greater than 0. When 0 or a negative number is passed in, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned. |
| ArkUI_AccessibleAction* operationActions | Pointer to the array of actions supported by the component. The array must contain at least operationCount valid elements and cannot be a null pointer. For details about the supported action types, see ArkUI_Accessibility_ActionType. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetScreenRect()
int32_t OH_ArkUI_AccessibilityElementInfoSetScreenRect(ArkUI_AccessibilityElementInfo* elementInfo, ArkUI_AccessibleRect* screenRect)
Description
Sets the rectangle area of the component on the screen for ArkUI_AccessibilityElementInfo.
- screenRect defines the position and size of the component on the screen, in pixels. The accessibility service uses screenRect to highlight the focus, locate the touch target, and determine the element visibility.
- Auxiliary applications, such as accessibility applications, leverage screenRect to determine the display position of the focus box, helping users understand the position of the current focused element on the screen.
- If the area specified by screenRect is 0 or is not within the visible range of the screen, the node may not be focused by auxiliary applications.
- A null pointer cannot be passed to screenRect and elementInfo. Otherwise, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| ArkUI_AccessibleRect* screenRect | Pointer to the screen area, including the coordinates of the upper left corner and lower right corner. The value cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetCheckable()
int32_t OH_ArkUI_AccessibilityElementInfoSetCheckable(ArkUI_AccessibilityElementInfo* elementInfo, bool checkable)
Description
Sets whether the component is checkable for ArkUI_AccessibilityElementInfo.
- This API applies to components that have checkable semantics, such as CheckBox, Toggle, and Radio in ArkUI.
- Accessibility applications will announce the "checkable" prompt to users based on the checkable state and inform the users that they can perform an operation to change the checkable state.
- When setting checkable to true, you need to use OH_ArkUI_AccessibilityElementInfoSetChecked to set checked to indicate the current checked state.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool checkable | Whether the element is checkable. The value true indicates that the element is checkable, and false indicates the opposite. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetChecked()
int32_t OH_ArkUI_AccessibilityElementInfoSetChecked(ArkUI_AccessibilityElementInfo* elementInfo, bool checked)
Description
Sets the current checked state for the component for ArkUI_AccessibilityElementInfo.
- Accessibility applications will announce "checked" or "unchecked" based on the checked state. This API only sets the checked state and does not automatically set the checkable attribute.
- If the component needs to be identified as checkable, call OH_ArkUI_AccessibilityElementInfoSetCheckable to set the checkable attribute to true.
- If only checked is set and the checkable attribute is not set to true, the checked state will not be displayed in accessibility applications.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool checked | Whether the component is checked. The value true indicates that the component is checked, and false indicates the opposite. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetFocusable()
int32_t OH_ArkUI_AccessibilityElementInfoSetFocusable(ArkUI_AccessibilityElementInfo* elementInfo, bool focusable)
Description
Sets whether the component is focusable for ArkUI_AccessibilityElementInfo.
- This API is applicable to focusable interactive components (such as TextInput and Button in ArkUI).
- When traversing focusable nodes, auxiliary applications such as accessibility applications will skip nodes whose focusable is set to false.
- For components whose focusable is set to true, you also need to set clickable to true using OH_ArkUI_AccessibilityElementInfoSetClickable and register the corresponding action. Otherwise, users may not be able to perform post-focus interaction operations on the component through auxiliary applications.
- The difference between focusable and accessibilityFocused lies in: focusable indicates the input focus capability, and accessibilityFocused indicates the current status of the accessibility focus.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool focusable | Whether the object is focusable. true: focusable; false: not focusable. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetFocused()
int32_t OH_ArkUI_AccessibilityElementInfoSetFocused(ArkUI_AccessibilityElementInfo* elementInfo, bool isFocused)
Description
Sets whether the component has been focused for ArkUI_AccessibilityElementInfo.
- When gaining focus, accessibility applications will announce the information about the focused element.
- When setting isFocused to true, you need to set focusable to true using OH_ArkUI_AccessibilityElementInfoSetFocusable. Otherwise, the meaning of the focus state is incomplete.
- The difference between isFocused and accessibilityFocused lies in: isFocused indicates the input focus state, while accessibilityFocused (set by OH_ArkUI_AccessibilityElementInfoSetAccessibilityFocused) indicates the accessibility focus state.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool isFocused | Whether the object is focused. true: focused; false: not focused. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetVisible()
int32_t OH_ArkUI_AccessibilityElementInfoSetVisible(ArkUI_AccessibilityElementInfo* elementInfo, bool isVisible)
Description
Sets whether the component is visible on the screen for ArkUI_AccessibilityElementInfo.
- When auxiliary applications, such as accessibility applications, traverse nodes, they will skip nodes whose isVisible is set to false by default and do not focus on or announce these nodes. For components that are not in the visible area due to scrolling, you are advised to set isVisible to false.
- If an interactive component is incorrectly set to be invisible, users will not be able to access it through an auxiliary application.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool isVisible | Whether the element is visible. true: visible; false: not visible. The default value is false. isVisible must be explicitly set to true for all components that need to be identified by auxiliary applications. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityFocused()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityFocused(ArkUI_AccessibilityElementInfo* elementInfo, bool accessibilityFocused)
Description
Sets the current accessibility focus status for ArkUI_AccessibilityElementInfo.
- When users browse UIs by focus movement of accessibility applications, the value of accessibilityFocused for the focused nodes should be true.
- Accessibility applications announce the content of the nodes whose accessibilityFocused is set to true and draw focus highlight boxes on the screen.
- When the accessibility service performs the ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_GAIN_ACCESSIBILITY_FOCUS and ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CLEAR_ACCESSIBILITY_FOCUS actions, a third-party framework should update the status accordingly and notify the system by sending the ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_ACCESSIBILITY_FOCUSED or ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_ACCESSIBILITY_FOCUS_CLEARED event.
- The difference between accessibilityFocused and isFocused lies in: accessibilityFocused indicates the accessibility focus state, and isFocused indicates the input focus (keyboard focus) state.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool accessibilityFocused | Accessibility focus state. true: Accessibility focus is set. false: Accessibility focus is not set. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetSelected()
int32_t OH_ArkUI_AccessibilityElementInfoSetSelected(ArkUI_AccessibilityElementInfo* elementInfo, bool selected)
Description
Sets whether the component is selected for ArkUI_AccessibilityElementInfo.
- This API applies to components that have the selected semantics, such as Tab and ListItem in ArkUI.
- Accessibility applications will announce "selected" or "deselected" based on the selected state. For Tab, the tab whose selected is set to true will be announced as the current active tab.
- In list scenarios, selected can be used together with accessibilityGroup (set by OH_ArkUI_AccessibilityElementInfoSetAccessibilityGroup) to mark the currently activated list item.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool selected | Whether the object is selected. true: selected; false: not selected. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetClickable()
int32_t OH_ArkUI_AccessibilityElementInfoSetClickable(ArkUI_AccessibilityElementInfo* elementInfo, bool clickable)
Description
Sets whether the component is clickable for ArkUI_AccessibilityElementInfo.
- Accessibility applications will notify users that the component is clickable. When the users perform click actions through the accessibility applications, the system will use the executeAccessibilityAction callback in ArkUI_AccessibilityProviderCallbacks to notify third-party frameworks.
- When setting clickable to true, you need to add ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CLICK to operationActions through OH_ArkUI_AccessibilityElementInfoSetOperationActions. Otherwise, users cannot click the component through accessibility applications.
- clickable must be used together with enabled (set by OH_ArkUI_AccessibilityElementInfoSetEnabled). When clickable is set to true but enabled is set to false, accessibility applications will announce "disabled", indicating that the component is clickable but currently unavailable.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool clickable | Whether the object is clickable. true: supported; false: not supported. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetLongClickable()
int32_t OH_ArkUI_AccessibilityElementInfoSetLongClickable(ArkUI_AccessibilityElementInfo* elementInfo, bool longClickable)
Description
Sets whether the component can be long-pressed for ArkUI_AccessibilityElementInfo.
- Accessibility applications will notify users that the component can be long-pressed. When the users perform long-pressing actions through the accessibility applications, the system will use the executeAccessibilityAction callback in ArkUI_AccessibilityProviderCallbacks to notify third-party frameworks.
- When setting longClickable to true, you need to add ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_LONG_CLICK to operationActions through OH_ArkUI_AccessibilityElementInfoSetOperationActions.
- Otherwise, users cannot long-press the component through accessibility applications.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool longClickable | Whether long-press gestures are supported. true: supported; false: not supported. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetEnabled()
int32_t OH_ArkUI_AccessibilityElementInfoSetEnabled(ArkUI_AccessibilityElementInfo* elementInfo, bool isEnabled)
Description
Sets whether the component is in the enabled state for ArkUI_AccessibilityElementInfo.
- When isEnabled is set to false, accessibility applications will announce "disabled" or "unavailable," indicating that the component is not currently interactive.
- For disabled components (such as a dimmed button), you need to set isEnabled to false and set clickable to true through OH_ArkUI_AccessibilityElementInfoSetClickable. In this way, accessibility applications will prompt users that the component exists but is currently unavailable.
- If both isEnabled and clickable are set to false, accessibility applications may skip the component completely.
- isEnabled must be explicitly set to true for all components with which users need to interact.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool isEnabled | Whether the object is enabled. true: enabled; false: not enabled. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetIsPassword()
int32_t OH_ArkUI_AccessibilityElementInfoSetIsPassword(ArkUI_AccessibilityElementInfo* elementInfo, bool isPassword)
Description
Sets whether the component is a password text box for ArkUI_AccessibilityElementInfo.
- When isPassword is set to true, accessibility applications will not read the specific password characters. Instead, they announce alternative prompts such as "password text box" or "password entered" to prevent password disclosure.
- If text components such as TextInput are used for password input, isPassword must be set to true.
- If this attribute is not set or is set to false, accessibility applications may directly read the password content, posing a security risk.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool isPassword | Whether the object is a password. true: The object is a password. false: The object is not a password. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetScrollable()
int32_t OH_ArkUI_AccessibilityElementInfoSetScrollable(ArkUI_AccessibilityElementInfo* elementInfo, bool scrollable)
Description
Sets whether the component is scrollable for ArkUI_AccessibilityElementInfo.
- This API applies to container components that support content scrolling, such as List, Grid, Scroll, and Swiper in ArkUI.
- Auxiliary applications, such as accessibility applications, provide scrolling action prompts to users based on the scrollable state. Users can use auxiliary applications to perform forward scrolling (ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_FORWARD) or backward scrolling (ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_BACKWARD).
- When setting scrollable to true, you need to add scrolling actions to operationActions through OH_ArkUI_AccessibilityElementInfoSetOperationActions, including ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_FORWARD and ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_BACKWARD. Otherwise, users cannot scroll the content of the component through the auxiliary applications.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool scrollable | Whether scrolling is supported. true: supported; false: not supported. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetEditable()
int32_t OH_ArkUI_AccessibilityElementInfoSetEditable(ArkUI_AccessibilityElementInfo* elementInfo, bool editable)
Description
Sets whether the text content is editable for ArkUI_AccessibilityElementInfo.
- editable indicates whether the text content of the component can be edited by users. This attribute applies to editable text components such as TextInput and TextArea.
- Accessibility applications will announce the "editable" prompt to users based on the editable state and allow users to enter or modify the text through the accessibility applications.
- For components with editable set to true, you need to register corresponding accessibility actions, such as ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SET_TEXT, ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_COPY, ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_PASTE, and ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_CUT, through OH_ArkUI_AccessibilityElementInfoSetOperationActions to allow users to perform editing actions through accessibility applications.
- If both editable and isPassword (set by OH_ArkUI_AccessibilityElementInfoSetIsPassword) are set to true, accessibility applications will announce "password edit box". The default value is false.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool editable | Whether editing is supported. true: supported; false: not supported. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetIsHint()
int32_t OH_ArkUI_AccessibilityElementInfoSetIsHint(ArkUI_AccessibilityElementInfo* elementInfo, bool isHint)
Description
Sets whether the component is in the hint text state for ArkUI_AccessibilityElementInfo.
- When isHint is set to true, accessibility applications will read the content specified by hintText (set by OH_ArkUI_AccessibilityElementInfoSetHintText) instead of contents (set by OH_ArkUI_AccessibilityElementInfoSetContents).
- This attribute is mainly used to display placeholder hint text for editable text components (such as TextInput) when users have not entered any content.
- For example, when a text box displays "Enter your username", set isHint to true and hintText to "Enter your username". After a user enters content, set isHint to false and contents to the text entered by the user.
- If isHint is set to true but hintText is not set, accessibility applications may announce empty content.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool isHint | Whether the component is in the hint text state. The value true indicates the component is in the hint text state, and false indicates the opposite. In hint text state, accessibility applications announce the content specified by hintText; otherwise, it announces the content specified by contents. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetRangeInfo()
int32_t OH_ArkUI_AccessibilityElementInfoSetRangeInfo(ArkUI_AccessibilityElementInfo* elementInfo, ArkUI_AccessibleRangeInfo* rangeInfo)
Description
Sets the range information for ArkUI_AccessibilityElementInfo.
- rangeInfo is used to set the current value, minimum value, and maximum value for a component that has a continuous range of values, such as Slider, Rating, and Progress.
- Accessibility applications will announce the current value and range based on rangeInfo, for example, "50% progress, range 0 to 100".
- In rangeInfo, current indicates the current value, min indicates the minimum value, and max indicates the maximum value.
- When setting rangeInfo, ensure that the value of min is less than or equal to that of max and the value of current is from min to max.
- A null pointer cannot be passed to rangeInfo or elementInfo. Otherwise, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| ArkUI_AccessibleRangeInfo* rangeInfo | Pointer to the current value, maximum value, and minimum value of a specific component. The value cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetGridInfo()
int32_t OH_ArkUI_AccessibilityElementInfoSetGridInfo(ArkUI_AccessibilityElementInfo* elementInfo, ArkUI_AccessibleGridInfo* gridInfo)
Description
Sets the grid information for ArkUI_AccessibilityElementInfo.
- gridInfo is used to set the number of rows, number of columns, and selection mode for a grid container, such as Grid, List, Flex, Select, and Swiper.
- Accessibility applications will announce the grid structure based on gridInfo, for example, "row 2, 5 rows and 3 columns in total".
- rowCount indicates the number of rows, columnCount indicates the number of columns, and selectionMode indicates the selection mode (the value 0 indicates that a single row is selected, and other values indicate that multiple rows are selected).
- A null pointer cannot be passed to gridInfo and elementInfo. Otherwise, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| ArkUI_AccessibleGridInfo* gridInfo | Pointer to the number of rows, number of columns, and selection mode of the specific component. The value cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetGridItemInfo()
int32_t OH_ArkUI_AccessibilityElementInfoSetGridItemInfo(ArkUI_AccessibilityElementInfo* elementInfo, ArkUI_AccessibleGridItemInfo* gridItem)
Description
Sets the attribute information of subitems in the grid container for ArkUI_AccessibilityElementInfo.
- gridItem is used to set the attributes of each subitem in Grid, including whether the subitem is a title, whether it is selected, and its row and column subscript and span information. This attribute applies to subitems of grid or list containers, such as Grid, List, Flex, Select, and Swiper in ArkUI.
- Accessibility applications will announce the position of the subitem based on rowIndex and columnIndex in gridItem, for example, "row 2, column 3".
- If heading in ArkUI_AccessibleGridItemInfo is set to true, accessibility applications will announce "title".
- A null pointer cannot be passed to gridItem and elementInfo. Otherwise, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| ArkUI_AccessibleGridItemInfo* gridItem | Pointer to the attribute value of the grid subitem. The value cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetSelectedTextStart()
int32_t OH_ArkUI_AccessibilityElementInfoSetSelectedTextStart(ArkUI_AccessibilityElementInfo* elementInfo, int32_t selectedTextStart)
Description
Sets the start position of the selected text for ArkUI_AccessibilityElementInfo.
- selectedTextStart is used for editable text components to mark the start character index position (counting from 0) of the currently selected text.
- Auxiliary applications, such as accessibility applications, announce the currently selected text range based on selectedTextStart and selectedTextEnd.
- When a user performs an ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SELECT_TEXT action through an accessibility application, a third-party framework should obtain the start position.
- You can obtain the start position through selectTextBegin in ArkUI_AccessibilityActionArguments.
- selectedTextStart must be used together with selectedTextEnd (set by OH_ArkUI_AccessibilityElementInfoSetSelectedTextEnd), and the value of selectedTextStart must not be greater than that of selectedTextEnd.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t selectedTextStart | Start position index of the selected text (starting from 0), which is applicable to text components. This parameter must be used together with selectedTextEnd. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetSelectedTextEnd()
int32_t OH_ArkUI_AccessibilityElementInfoSetSelectedTextEnd(ArkUI_AccessibilityElementInfo* elementInfo, int32_t selectedTextEnd)
Description
Sets the end position of the selected text for ArkUI_AccessibilityElementInfo.
- selectedTextEnd is used for editable text components to mark the end character index position (counting from 0) of the currently selected text.
- Auxiliary applications, such as accessibility applications, calculate and announce the selected text content based on selectedTextStart and selectedTextEnd.
- selectedTextEnd must be used together with selectedTextStart, and the value of selectedTextEnd must be greater than or equal to that of selectedTextStart. You can set selectedTextStart by OH_ArkUI_AccessibilityElementInfoSetSelectedTextStart.
- When no text is selected, selectedTextStart and selectedTextEnd can be set to the same value (that is, the cursor position).
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t selectedTextEnd | End position index of the selected text (starting from 0), which is applicable to text components. This parameter must be used together with selectedTextStart. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetCurrentItemIndex()
int32_t OH_ArkUI_AccessibilityElementInfoSetCurrentItemIndex(ArkUI_AccessibilityElementInfo* elementInfo, int32_t currentItemIndex)
Description
Sets the position index of the currently focused or highlighted subitem for ArkUI_AccessibilityElementInfo.
- currentItemIndex is used for container components, such as List, Select, Swiper, and Tab, and it indicates the position index (starting from 0) of the currently focused or active subitem in the container.
- Accessibility applications will announce the position of the current item, for example, "item 3 of 10".
- currentItemIndex must be used together with itemCount (set by OH_ArkUI_AccessibilityElementInfoSetItemCount) so that accessibility applications can announce the complete information, that is, "item X of Y".
- The value of currentItemIndex must be within the range of 0 to itemCount – 1.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t currentItemIndex | Position index (starting from 0) of the currently focused component, with a value range of [0, itemCount - 1]. It must be used together with itemCount. This parameter is applicable to container components such as List, Select, Swiper, and Tab. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetStartItemIndex()
int32_t OH_ArkUI_AccessibilityElementInfoSetStartItemIndex(ArkUI_AccessibilityElementInfo* elementInfo, int32_t startItemIndex)
Description
Sets the position index of the first element in the visible area of the current screen for ArkUI_AccessibilityElementInfo.
- startItemIndex is used for scrollable container components, such as List, Select, Swiper, and Tab, and it indicates the position index (starting from 0) of the first subitem in the visible area of the current screen.
- Auxiliary applications, such as accessibility applications, determine the visible area based on startItemIndex and endItemIndex (set by OH_ArkUI_AccessibilityElementInfoSetEndItemIndex) to optimize focus movement and announcement.
- The value of startItemIndex must be less than or equal to that of endItemIndex, and both values must be within the range of 0 to itemCount – 1.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t startItemIndex | Position index (starting from 0) of the first element in the visible area of the current screen. This parameter is used for container components such as List, Select, Swiper, and Tab. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetEndItemIndex()
int32_t OH_ArkUI_AccessibilityElementInfoSetEndItemIndex(ArkUI_AccessibilityElementInfo* elementInfo, int32_t endItemIndex)
Description
Sets the position index of the last element in the visible area of the current screen for ArkUI_AccessibilityElementInfo.
- endItemIndex is used for scrollable container components, such as List, Select, Swiper, and Tab, and it indicates the position index (starting from 0) of the last subitem in the visible area of the current screen.
- Auxiliary applications, such as accessibility applications, determine the visible area based on startItemIndex (set by OH_ArkUI_AccessibilityElementInfoSetStartItemIndex) and endItemIndex, so that the applications can announce scrolling progress based on these values when users perform scrolling actions.
- The value of endItemIndex must be greater than or equal to that of startItemIndex, and both values must be within the range of 0 to itemCount – 1.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t endItemIndex | Position index (starting from 0) of the last element in the visible area on the current screen. The value range is [0, itemCount - 1], and the value must be greater than or equal to that of startItemIndex. This parameter is used for container components such as List, Select, Swiper, and Tab. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetItemCount()
int32_t OH_ArkUI_AccessibilityElementInfoSetItemCount(ArkUI_AccessibilityElementInfo* elementInfo, int32_t itemCount)
Description
Sets the total number of subitems in the container for ArkUI_AccessibilityElementInfo.
- itemCount is used for container components, such as List, Select, Swiper, and Tab, and it indicates the total number of subitems in the container.
- Auxiliary applications, such as accessibility applications, will announce the position of the current item based on currentItemIndex (set by OH_ArkUI_AccessibilityElementInfoSetCurrentItemIndex) and itemCount, for example, "item 3 of 10".
- The value of itemCount should be the total number of subitems in the container (including both visible and invisible items), not just the number of subitems currently visible on the screen.
- The value of itemCount must be a non-negative integer. The value 0 indicates that the container is empty.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t itemCount | Total number of subitems (including visible and invisible ones) in the container. The value must be a non-negative integer, with 0 indicating an empty container. It is used by auxiliary applications to announce "item X of Y". This parameter is used for container components such as List, Select, Swiper, and Tab. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityOffset()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityOffset(ArkUI_AccessibilityElementInfo* elementInfo, int32_t offset)
Description
Sets the scroll offset for ArkUI_AccessibilityElementInfo.
- offset is used for scrollable container components, such as List, Grid, and Scroll, and it indicates the scrolling pixel offset of the content area relative to the top coordinates of the element.
- The accessibility service uses offset to determine the scrolling position, and auxiliary applications use it to announce the scrolling progress.
- After a user performs an ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_FORWARD or ARKUI_ACCESSIBILITY_NATIVE_ACTION_TYPE_SCROLL_BACKWARD action, a third-party framework should update the offset value in the updated node information.
- If the value of offset is 0, the content area is not scrolled (at the initial position). A positive value indicates the pixel distance for scrolling down or right.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t offset | Scroll offset in pixels of the content area relative to the top coordinates of the element for scrollable container components such as List and Grid. The value 0 indicates no scrolling, and a positive value indicates the scrolled distance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityGroup()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityGroup(ArkUI_AccessibilityElementInfo* elementInfo, bool accessibilityGroup)
Description
Sets the accessibility group for ArkUI_AccessibilityElementInfo.
- accessibilityGroup indicates whether to treat the component and all its child components as a whole.
- When accessibilityGroup is set to true, accessibility applications consider the node as a whole and do not focus on or announce the information about its child nodes separately, but combine the text content of its child nodes and announce the content together.
- This attribute is applicable to scenarios where a group of related content (for example, a list item containing an icon and text) is treated as an accessibility unit. For example, a list item contains a product image and name. After accessibilityGroup is set to true, accessibility applications will treat the entire list item as a node to announce instead of announcing the image and text separately.
- If accessibilityGroup is set to false, accessibility applications traverse child nodes one by one.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| bool accessibilityGroup | Whether to enable accessibility group behavior for the object. The value true indicates that the component and its child components are announced as a whole. The value false indicates that child nodes are traversed one by one. The default value is false. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityLevel()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityLevel(ArkUI_AccessibilityElementInfo* elementInfo, const char* accessibilityLevel)
Description
Sets the accessibility importance level for ArkUI_AccessibilityElementInfo.
- accessibilityLevel is used to control whether a component can be identified by the accessibility service, which affects the visibility of the node in the accessibility node tree.
- Auxiliary applications, such as accessibility applications, determine whether to display the node to users based on accessibilityLevel.
- The values and their meanings are as follows:
- auto: The system automatically determines whether the component is important based on its attributes and whether to allow the accessibility service to identify the component. Generally, components with interactive attributes (such as clickable) or text content are automatically identified as important.
- yes: The component is important and can be identified by the accessibility service. The accessibility service identifies the component regardless of the component attributes.
- no: The component is not important and cannot be identified by the accessibility service. The accessibility service skips this node, but its child nodes can still be identified.
- no-hide-descendants: The component and all its descendant components are not important and cannot be identified by the accessibility service. This value is applicable to containers that are only used for decoration, to prevent the accessibility service from announcing meaningless content.
- A null pointer cannot be passed to accessibilityLevel. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* accessibilityLevel | Pointer to the accessibility importance level of the component. The value can be "auto", "yes", "no", or "no-hide-descendants", but cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetZIndex()
int32_t OH_ArkUI_AccessibilityElementInfoSetZIndex(ArkUI_AccessibilityElementInfo* elementInfo, int32_t zIndex)
Description
Sets the component Z-index for ArkUI_AccessibilityElementInfo.
- zIndex is used to control the position of an element along the z-axis perpendicular to the screen. When multiple components overlap on the screen, the component with a larger zIndex value will cover the component with a smaller zIndex value.
- This attribute is mainly used by the UiTest automation framework to identify the stacking order of components.
- The accessibility service may also use zIndex to determine the focus movement direction.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| int32_t zIndex | Z-index of the component, used to control the position of the component along the z-axis perpendicular to the screen. This parameter is required for UiTest. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetAccessibilityOpacity()
int32_t OH_ArkUI_AccessibilityElementInfoSetAccessibilityOpacity(ArkUI_AccessibilityElementInfo* elementInfo, float opacity)
Description
Sets the opacity for ArkUI_AccessibilityElementInfo.
- opacity indicates the opacity of a component. This attribute is mainly used by the UiTest automation framework to identify the visual opacity status of a component. The value ranges from 0 to 1, where 1 indicates opaque and 0 indicates completely transparent.
- Note: If NaN is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned. However, values outside the range of 0 to 1 (such as a negative number or a value greater than 1) will not be automatically corrected. It is recommended that you always pass a valid value from 0 to 1.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| float opacity | Opacity. The value range is [0, 1], where 1 indicates fully opaque and 0 indicates fully transparent. Values out of range are truncated to the boundary values. This parameter is required for UiTest. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetBackgroundColor()
int32_t OH_ArkUI_AccessibilityElementInfoSetBackgroundColor(ArkUI_AccessibilityElementInfo* elementInfo, const char* backgroundColor)
Description
Sets the background color for ArkUI_AccessibilityElementInfo.
- backgroundColor indicates the background color of a component. This attribute is mainly used by the UiTest automation framework to identify the visual background color of a component.
- This attribute is in the format of #ARGB. For example, #FFFFFFFF indicates non-transparent white and #80FF0000 indicates semi-transparent red.
- A null pointer cannot be passed to backgroundColor. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* backgroundColor | Pointer to the background color. The value is in the #ARGB format. For example, the value for non-transparent white is #FFFFFFFF. The value cannot be a null pointer. This parameter is required for UiTest. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetBackgroundImage()
int32_t OH_ArkUI_AccessibilityElementInfoSetBackgroundImage(ArkUI_AccessibilityElementInfo* elementInfo, const char* backgroundImage)
Description
Sets the background image for ArkUI_AccessibilityElementInfo.
- backgroundImage indicates the background image resource of a component. This attribute is mainly used by the UiTest automation framework to identify the visual background image of a component.
- A null pointer cannot be passed to backgroundImage. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* backgroundImage | Pointer to the resource path string of the background image. It cannot be a null pointer. This parameter is required for UiTest. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetBlur()
int32_t OH_ArkUI_AccessibilityElementInfoSetBlur(ArkUI_AccessibilityElementInfo* elementInfo, const char* blur)
Description
Sets the blur effect for ArkUI_AccessibilityElementInfo.
- blur indicates the blur effect parameter of a component. This attribute is mainly used by the UiTest automation framework to identify the visual blur status of a component.
- A null pointer cannot be passed to blur. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* blur | Pointer to the blur parameter string. For the value format, refer to the value specification of the corresponding blur attribute of ArkUI components. The value must not be a null pointer. This parameter is required for UiTest. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetHitTestBehavior()
int32_t OH_ArkUI_AccessibilityElementInfoSetHitTestBehavior(ArkUI_AccessibilityElementInfo* elementInfo, const char* hitTestBehavior)
Description
Sets the response logic and node blocking rule for the hit test for ArkUI_AccessibilityElementInfo.
- hitTestBehavior is used to control the response behavior of a component during the hit test and determine whether the touch event can pass through the component.
- This attribute is mainly used by the UiTest automation framework. For details about the value range, see HitTestMode. The options are as follows:
- Default: The default behavior is used, which does not block the touch event.
- Block: The touch event of the component and its child components is blocked.
- Transparent: The component does not respond to the touch event, but its child components can respond.
- None: Neither the component nor its child components respond to the touch event.
- A null pointer cannot be passed to hitTestBehavior. If a null pointer is passed, ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* hitTestBehavior | Pointer to the response mode for hit testing. The value can be "Default" (default behavior, indicating no blocking), "Block" (blocks touch events of the component itself and its child components), "Transparent" (the component itself does not respond to the touch event, but its child components can respond to), or "None" (neither the component itself nor its child components respond to the touch event). The value cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityElementInfoSetComponentIdentifier()
int32_t OH_ArkUI_AccessibilityElementInfoSetComponentIdentifier(ArkUI_AccessibilityElementInfo* elementInfo, const char* identifier)
Description
Sets the component identifier for ArkUI_AccessibilityElementInfo, which can be used to identify a specific component during automated testing.
Since: 24
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
| const char* identifier | Pointer to the unique identifier string of the component. It cannot be a null pointer. The component identifier in the reported component tree must be unique, and the string length must not exceed 1024. If it exceeds 1024, it will be truncated. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_CreateAccessibilityElementInfo()
ArkUI_AccessibilityElementInfo* OH_ArkUI_CreateAccessibilityElementInfo(void)
Description
Creates an ArkUI_AccessibilityElementInfo object. After the object is created, call OH_ArkUI_DestoryAccessibilityElementInfo to destroy it.
Since: 13
Returns
| Type | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* | Pointer to the newly created ArkUI_AccessibilityElementInfo object, used to carry accessibility node information. If creation fails, NULL is returned. |
[h2]OH_ArkUI_DestoryAccessibilityElementInfo()
void OH_ArkUI_DestoryAccessibilityElementInfo(ArkUI_AccessibilityElementInfo* elementInfo)
Description
Destroys an ArkUI_AccessibilityElementInfo object.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to ArkUI_AccessibilityElementInfo. |
[h2]OH_ArkUI_CreateAccessibilityEventInfo()
ArkUI_AccessibilityEventInfo* OH_ArkUI_CreateAccessibilityEventInfo(void)
Description
Creates an ArkUI_AccessibilityEventInfo object. After the object is created, call OH_ArkUI_DestoryAccessibilityEventInfo to destroy it.
Since: 13
Returns
| Type | Description |
|---|---|
| ArkUI_AccessibilityEventInfo* | Pointer to the newly created ArkUI_AccessibilityEventInfo object, used to carry accessibility event information. If creation fails, NULL is returned. |
[h2]OH_ArkUI_DestoryAccessibilityEventInfo()
void OH_ArkUI_DestoryAccessibilityEventInfo(ArkUI_AccessibilityEventInfo* eventInfo)
Description
Destroys an ArkUI_AccessibilityEventInfo object.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityEventInfo* eventInfo | Pointer to the ArkUI_AccessibilityEventInfo object to be destroyed. |
[h2]OH_ArkUI_AccessibilityEventSetEventType()
int32_t OH_ArkUI_AccessibilityEventSetEventType(ArkUI_AccessibilityEventInfo* eventInfo, ArkUI_AccessibilityEventType eventType)
Description
Sets the event type for ArkUI_AccessibilityEventInfo.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityEventInfo* eventInfo | Pointer to ArkUI_AccessibilityEventInfo. |
| ArkUI_AccessibilityEventType eventType | Event type (such as tap event, long press event, text update event, focus event, and page update event). For details about the available options, see ArkUI_AccessibilityEventType. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityEventSetTextAnnouncedForAccessibility()
int32_t OH_ArkUI_AccessibilityEventSetTextAnnouncedForAccessibility(ArkUI_AccessibilityEventInfo* eventInfo, const char* textAnnouncedForAccessibility)
Description
Sets the content to be proactively announced for ArkUI_AccessibilityEventInfo.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityEventInfo* eventInfo | Pointer to an ArkUI_AccessibilityEventInfo object. |
| const char* textAnnouncedForAccessibility | Pointer to the content to be proactively announced. It cannot be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityEventSetRequestFocusId()
int32_t OH_ArkUI_AccessibilityEventSetRequestFocusId(ArkUI_AccessibilityEventInfo* eventInfo, int32_t requestFocusId)
Description
Sets the focus request ID for ArkUI_AccessibilityEventInfo.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityEventInfo* eventInfo | Pointer to an ArkUI_AccessibilityEventInfo object. |
| int32_t requestFocusId | ID of the accessibility element that requests focus. It must be consistent with the value of elementId set in ArkUI_AccessibilityElementInfo, and is used to notify the accessibility service to focus on the specified node. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_AccessibilityEventSetElementInfo()
int32_t OH_ArkUI_AccessibilityEventSetElementInfo(ArkUI_AccessibilityEventInfo* eventInfo, ArkUI_AccessibilityElementInfo* elementInfo)
Description
Sets elementInfo for ArkUI_AccessibilityEventInfo.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityEventInfo* eventInfo | Pointer to an ArkUI_AccessibilityEventInfo object. |
| ArkUI_AccessibilityElementInfo* elementInfo | Pointer to the ArkUI_AccessibilityElementInfo element information. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_FindAccessibilityActionArgumentByKey()
int32_t OH_ArkUI_FindAccessibilityActionArgumentByKey(ArkUI_AccessibilityActionArguments* arguments, const char* key, char** value)
Description
Obtains the value of a specified key in ArkUI_AccessibilityActionArguments.
Since: 13
Parameters
| Name | Description |
|---|---|
| ArkUI_AccessibilityActionArguments* arguments | Pointer to ArkUI_AccessibilityActionArguments. |
| const char* key | Pointer to the key of the parameter to search for. The value of key must be consistent with the key set in ArkUI_AccessibilityActionArguments. |
| char** value | Double pointer to the value found (as an output parameter). |
Returns
| Type | Description |
|---|---|
| int32_t | Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_SUCCESSFUL if the operation is successful. Returns ARKUI_ACCESSIBILITY_NATIVE_RESULT_BAD_PARAMETER if a parameter error occurs. |
[h2]OH_ArkUI_NativeModule_GetNativeAccessibilityProvider()
int32_t OH_ArkUI_NativeModule_GetNativeAccessibilityProvider(ArkUI_NodeHandle* node, ArkUI_AccessibilityProvider** provider)
Description
Obtains the level-2 pointer variable of the pointer to the ArkUI_AccessibilityProvider object.
The ArkUI_AccessibilityProvider object corresponds to the ArkUI_NodeHandle instance passed.
A third-party framework maps its UI components as RenderNode of the ARKUI_NODE_CUSTOM type to obtain ArkUI_NodeHandle.
Then, it calls OH_ArkUI_NativeModule_GetNativeAccessibilityProvider to obtain the ArkUI_AccessibilityProvider pointer and register an accessibility callback.
Finally, the ArkUI accessibility service can identify the UI of the third-party framework and trigger events.
This API takes effect only when the third-party framework maps its UI components as RenderNode of the ARKUI_NODE_CUSTOM type. Otherwise, an error code will be reported.
This API uses RenderNode to implement the access of the third-party framework. Only ARKUI_NODE_CUSTOM can access the accessibility service to obtain the accessibility control tree.
Multi-thread concurrency is not supported. The third-party framework ensures thread safety during the API calling.
Since: 23
Parameters
| Name | Description |
|---|---|
| ArkUI_NodeHandle* node | Pointer to an ArkUI_NodeHandle object. |
| ArkUI_AccessibilityProvider** provider | Double pointer to the ArkUI_AccessibilityProvider pointer (as an output parameter). It is used to receive the pointer to the ArkUI_AccessibilityProvider object for registering accessibility callbacks. It must not be a null pointer. |
Returns
| Type | Description |
|---|---|
| int32_t | Status code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. Parameter error: 1. The input parameter node or provider is a null pointer. 2. The ArkUI_NodeHandle type corresponding to node is not ARKUI_NODE_CUSTOM. |