Стандарти · ARIA

Роля Съставна контрола

listbox

Отбелязва елемент като списък от избираеми опции. Използвайте <select> за простия случай с единичен избор — той осигурява удобен за мобилни устройства selector и пълна поддръжка на клавиатура. Прибягвайте до role="listbox", когато се нуждаете от персонализиран стил, множествен избор или съчетаване с комбинирано поле.

Кога да се използва

Използвайте <select> (единичен избор) или <select multiple> винаги, когато е възможно. Нативният елемент осигурява целия модел на взаимодействие, включително правилна обработка на клавиатурата за съответната платформа.

role="listbox" е подходящ когато:

  • Списъкът е изскачащ прозорец на персонализирано комбинирано поле.
  • Необходимо е богато съдържание на опциите (икони, допълнителен текст), което <select> не може да рендира.
  • Необходим е множествен избор с персонализиран стил на отметките.
  • Изграждате списък за прехвърляне или selector с филтриране.

Дъщерните елементи трябва да са role="option" (допуска се role="group" като междинна обвивка за разделяне на секции). Задайте aria-multiselectable="true" за списъци с множествен избор.

Договор за клавиатура и фокус

Съгласно модела на APG за listbox:

  • Tab премества фокуса към списъка; Tab го премества извън него. В рамките на списъка фокусът остава върху контейнера, а „активната” опция се проследява чрез aria-activedescendant.
  • Стрелките нагоре/надолу преместват активната опция.
  • Home / End прескачат към първата / последната.
  • Единичен избор: всяко натискане на стрелка избира и активната опция.
  • Множествен избор: Space превключва избора на активната опция; Shift+стрелка разширява непрекъснат диапазон; Ctrl/Cmd+A избира всички.
  • Въвеждане на символ: натискането на буква прескача до следващата опция, започваща с тази буква.

Чести грешки

  • Преместване на DOM фокуса към всяка опция вместо използване на aria-activedescendant. Нарушава въвеждането на символи и интеграцията с комбинираното поле.
  • Дъщерни елементи role="option" без атрибути id — aria-activedescendant не може да ги реферира.
  • Списък с множествен избор без aria-multiselectable="true". Екранните четци го обявяват като единичен избор.
  • Списъкът притежава опции, намиращи се другаде в DOM, без използване на aria-owns за изричното обявяване на връзката.
  • Използване на role="listbox" за статичен списък с елементи само за четене. Това е role="list", а не listbox — listbox подразбира интерактивност.

Пример

<label id="topicsLabel">Pick your topics</label>
<ul
  role="listbox"
  aria-labelledby="topicsLabel"
  aria-multiselectable="true"
  tabindex="0"
  aria-activedescendant="topic-1"
>
  <li id="topic-1" role="option" aria-selected="true">Accessibility</li>
  <li id="topic-2" role="option" aria-selected="false">Assistive tech</li>
  <li id="topic-3" role="option" aria-selected="true">Standards</li>
</ul>