diff --git a/index.html b/index.html index b887e641d..735388ea4 100644 --- a/index.html +++ b/index.html @@ -4551,6 +4551,277 @@

Definition of Roles

+
+ listview +
+

+ A composite widget containing a collection of interactive elements that can also contain interactive elements where some or all items in the collection are focusable by using methods of directional navigation, such as directional arrow keys. + See related grid and treegrid. +

+

+ A listview contains listviewitem elements. + Authors can use the listviewitem elements in a listview to present a wide variety of collections. + For example, each item in a collection might contain: +

+ +

+ A listview can be used to present a hierarchical collection. + a listviewitem can contain a group that contains other listviewitem elements. + As described in the definition of listviewitem, authors MAY use aria-expanded on a listviewitem to indicate that a nested collection can be expanded or collapsed. +

+

+ The primary purpose of a listview is to make a collection navigable and interactive. + Elements in A listview can also be selectable, but they are not selectable by default. + Authors MAY specify either aria-selected or aria-checked for items in a listview to indicate selection (see listviewitem). + If a listview allows multiple listviewitem elements to be selected, authors SHOULD set aria-multiselectable to true on the element with role listview. +

+

+ To be keyboard accessible, authors SHOULD manage focus of descendants of a listview as described in Managing Focus. + When users are moving focus among items in a listview, authors SHOULD set focus as follows: +

+ +

Authors SHOULD provide a mechanism for moving focus into and out of a listviewitem that allows users to navigate and interact with content contained by the listviewitem if the listviewitem contains any of the following:

+ +

+ Depending on the implementation, pressing Enter, Space, or another key would move focus from the listviewitem to a focusable element inside the listviewitem. + Then, pressing Enter again, Tab, Escape, or another key would place focus back on the parent listviewitem element so users can continue navigating the listview. + For example, if an item in a list of video preview cards contains a video player, the Enter key might be used to move focus from the listviewitem to the play button of the contained player. + The card might then trap focus so users can easily use the Tab key to navigate among the player's controls and then use the Esc key or a dynamically rendered close button to return focus to the card. +

+

+ The listview role does not assume any particular form of visual presentation. + A listview can scroll in any direction as users move focus. + Items can be arranged in a single column, a single row, or in multiple columns or rows. + Authors SHOULD indicate whether the order of the collection is presented horizontally or vertically with aria-orientation. + For example, if a set of twenty cards is presented in a vertical list that is wrapped into five columns that contain four cards, authors SHOULD set aria-orientation to vertical. + This would inform assistive technology users that moving focus with the down arrow key would move focus from the first card to the second card whereas pressing the right arrow key (if supported) would move focus from the first card to the fifth card. +

+

+ Since WAI-ARIA can augment an element of the host language, a listview can reuse the elements and attributes of a native list, such as an HTML ul element. + For example, if an author applies the listview role to an HTML ul element, the author does not need to apply the listviewitem role to the descendant HTML li elements because the user agent will automatically make the appropriate translations. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Characteristics:
CharacteristicValue
Is Abstract:
Superclass Role: +
    +
  • composite
    • +
  • list
    • +
+
Subclass Roles:Placeholder
Base Concept:<[^ul^]> in HTML
Related Concepts:
Required Accessibility Parent Roles:
Allowed Accessibility Child Roles:listviewitem
Required States and Properties:
Supported States and Properties: +
    +
  • aria-multiselectable
    • +
  • aria-orientation
    • +
+
Inherited States and Properties:Placeholder
Name From:author
Accessible Name Required:True
Inherits Name Required:
Children Presentational:
Inherits Presentational:
+ +
+ listviewitem +
+

An item in a listview.

+

+ A listviewitem can be focusable and selectable. + As described in the definition of listview, if a listviewitem contains a single interactive element, authors SHOULD set focus on the contained element in lieu of focusing the listviewitem. + Otherwise, authors SHOULD ensure a listviewitem is focusable. +

+

+ If a listviewitem is focusable, authors MUST specify an accessible name. + For simple items, authors MAY simply specify a label that contains all the item's content, e.g., specify an id for the item and reference it with aria-labelledby. + However, for more complex rich content where authors have provided a method for moving focus inside of the listviewitem as described in listview, authors can provide assistive technology users with a more efficient navigation experience by providing a concise accessible name and description. + In such implementations, authors MAY use aria-labelledby or aria-label to specify a sufficiently distinct and concise name. + In addition, authors MAY apply aria-describedby to listviewitem elements in a listview to suggest to screen readers which elements contained by the listviewitem to announce after its label when users navigate by listviewitem. + This enables authors to create a navigation experience that filters out repetitive or less important elements, such as embedded interaction widgets that appear in every item. +

+

+ A listviewitem element can contain a nested collection of listviewitem elements. + A nested collection of listviewitem elements is enclosed in an element with the group role. + Authors can enable users to control the visibility and focusability of a nested collection, i.e., make it expandable and collapsable. + If the nested group of listviewitem elements can be expanded and collapsed, authors MUST specify a value for aria-expanded on the listviewitem +

Authors MUST ensure [=elements=] with role listviewitem are accessibility children of an element with role listview or an element with role group that is the accessibility child of an element with role listviewitem.

+

+ Authors MAY indicate selection for listviewitem elements using either aria-selected or aria-checked. + Some user interfaces indicate selection with aria-selected in single-select listviews and with aria-checked in multi-select listviews. + Authors SHOULD NOT specify both aria-selected and aria-checked on listviewitem elements contained by the same listview except in the extremely rare circumstances where all the following conditions are met: +

+ +

User agents MUST NOT provide an implicit value for aria-selected for listviewitem elements.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Characteristics:
CharacteristicValue
Is Abstract:
Superclass Role: +
    +
  • listitem
    • +
  • widget
    • +
+
Subclass Roles:Placeholder
Base Concept:<[^li^]> in HTML
Related Concepts:
Required Accessibility Parent Roles: + +
Allowed Accessibility Child Roles:
Required States and Properties:
Supported States and Properties: +
    +
  • aria-checked
    • +
  • aria-disabled
    • +
  • aria-expanded
    • +
  • aria-level
    • +
  • aria-selected
    • +
+
Inherited States and Properties:Placeholder
Name From:author
Accessible Name Required:When Focusable
Inherits Name Required:
Children Presentational:
Inherits Presentational:
+
log