AccessibilityRole

Description

Options for defining the role of an AccessibilityNode to assistive technologies.

You can use values from this enum to set the AccessibilityNode.role. This property helps inform assistive technologies how to interact with your AccessibilityNode. Setting accurate roles improves the usability and user experience of your UI by enabling assistive technologies to set clear expectations for users. A missing role can block a user from interacting with your UI, and an incorrect role can cause confusion and frustration. You can use the default value, AccessibilityRole.None, for nodes whose role is not described by any of the enum options. Some examples are container elements and highly customized controls.

Additional resources: mobile-accessibility.

The following example demonstrates assigning an AccessibilityRole to a UI element based on its VisualElement type.

// Attach this script to a UIDocument GameObject.
// This script demonstrates creating an AccessibilityNode for each child of a
// UIDocument's rootVisualElement and assigning an appropriate
// AccessibilityRole based on its VisualElement type.
// It also shows how to create custom controls to support AccessibilityRoles
// that don't have a corresponding VisualElement type. These can be used in
// UXML files and the UI Builder.
// To view the properties of the AccessibilityNodes in Playmode, go to
// Window > Accessibility > Hierarchy Viewer.

using System;
using UnityEngine;
using UnityEngine.Accessibility;
using UnityEngine.UIElements;

public class AccessibilityManager : MonoBehaviour
{
    // The active accessibility hierarchy.
    AccessibilityHierarchy m_Hierarchy;

    void OnEnable()
    {
        // Create an accessibility hierarchy and set it as the active
        // hierarchy.
        m_Hierarchy = new AccessibilityHierarchy();
        AssistiveSupport.activeHierarchy = m_Hierarchy;

        // Add accessibility nodes to each child of the root VisualElement.
        AddNodesToChildren();
    }

    void AddNodesToChildren()
    {
        UIDocument document = GetComponent<UIDocument>();
        if (document == null)
        {
            Debug.LogError("UIDocument is not attached to this GameObject.");
            return;
        }

        // Loop through each child of the rootVisualElement of the UIDocument.
        foreach (var child in document.rootVisualElement.Children())
        {
            // Create a node in the active hierarchy to represent the element.
            AccessibilityNode node = m_Hierarchy.AddNode();

            // Set the node's label to the name of the VisualElement for clarity in
            // the Hierarchy Viewer.
            node.label = $"{child.name}";

            // Assign an appropriate AccessibilityRole to the node based on the
            // type of VisualElement.
            AssignNodeRole(node, child);
        }
    }

    void AssignNodeRole(AccessibilityNode node, VisualElement element)
    {
        // Match the VisualElement type to an AccessibilityRole using the "is"
        // operator to include subclasses. We check KeyboardKey before Button
        // because it's a subclass of Button with a distinct AccessibilityRole.
        if (element is KeyboardKey) node.role = AccessibilityRole.KeyboardKey;
        else if (element is Button) node.role = AccessibilityRole.Button;
        else if (element is Image) node.role = AccessibilityRole.Image;
        else if (element is Label) node.role = AccessibilityRole.StaticText;
        else if (element is SearchField) node.role = AccessibilityRole.SearchField;
        else if (element is Header) node.role = AccessibilityRole.Header;
        else if (element is TabView) node.role = AccessibilityRole.TabBar;
        else if (element is SliderInt || element is Slider) node.role = AccessibilityRole.Slider;
        else if (element is Toggle) node.role = AccessibilityRole.Toggle;

        // The default value AccessibilityRole.None is used for elements that
        // don't have a corresponding role.
    }
}

// The following classes define custom controls. They can be extended with
// additional properties and methods as needed.

[UxmlElement]
public partial class SearchField : TextField {}

[UxmlElement]
public partial class KeyboardKey : Button {}

[UxmlElement]
public partial class Header : VisualElement {}

Properties