Angular Aria

Что такое Angular Aria?

Создание доступных компонентов кажется простым, но реализация по W3C Accessibility Guidelines требует значительных усилий и экспертизы в accessibility.

Angular Aria — набор headless, доступных директив, реализующих распространённые паттерны WAI-ARIA. Директивы обрабатывают клавиатурные взаимодействия, ARIA-атрибуты, управление фокусом и поддержку screen reader. Вам остаётся предоставить HTML-структуру, CSS-стили и бизнес-логику!

Установка

Showcase

Например, возьмём toolbar menu. На вид это «простой» ряд кнопок со связанной логикой, но клавиатурная навигация и screen reader добавляют много неожиданной сложности для тех, кто мало знаком с accessibility.

app.ts

import {Component} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
})
export class App {}

app.html

<div ngToolbar aria-label="Text Formatting Tools">
  <div class="group">
    <button
      ngToolbarWidget
      value="undo"
      type="button"
      aria-label="undo"
      class="material-symbols-outlined"
      translate="no"
    >
      undo
    </button>

    <button
      ngToolbarWidget
      value="redo"
      type="button"
      aria-label="redo"
      class="material-symbols-outlined"
      translate="no"
    >
      redo
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div class="group">
    <button
      ngToolbarWidget
      value="bold"
      type="button"
      aria-label="bold"
      #bold="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="bold.selected()"
      translate="no"
    >
      format_bold
    </button>

    <button
      ngToolbarWidget
      value="italic"
      type="button"
      aria-label="italic"
      #italic="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="italic.selected()"
      translate="no"
    >
      format_italic
    </button>

    <button
      ngToolbarWidget
      value="underlined"
      type="button"
      aria-label="underlined"
      #underlined="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="underlined.selected()"
      translate="no"
    >
      format_underlined
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment options">
    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align left"
      aria-label="align left"
      #leftAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="leftAlign.selected()"
      translate="no"
    >
      format_align_left
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align center"
      aria-label="align center"
      #centerAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="centerAlign.selected()"
      translate="no"
    >
      format_align_center
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align right"
      aria-label="align right"
      #rightAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="rightAlign.selected()"
      translate="no"
    >
      format_align_right
    </button>
  </div>
</div>

app.css

@import url('https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined');

:host {
  display: flex;
  justify-content: center;
}

[ngToolbar] {
  gap: 1.5rem;
  display: flex;
  padding: 0.5rem 1rem;
  border-radius: 0.5rem;
  background-color: var(--septenary-contrast);
}

.group {
  gap: 0.5rem;
  display: flex;
}

.separator {
  width: 1px;
  align-self: center;
  height: calc(100% - 1rem);
  background-color: var(--quinary-contrast);
}

[ngToolbarWidget] {
  border: none;
  cursor: pointer;
  padding: 0.5rem;
  border-radius: 4px;
  font-size: 1.25rem;
  background-color: transparent;
  color: var(--primary-contrast);
}

[ngToolbarWidget]:hover {
  background-color: color-mix(in srgb, var(--primary-contrast) 10%, transparent);
}

[ngToolbarWidget]:active {
  background-color: color-mix(in srgb, var(--primary-contrast) 15%, transparent);
}

[ngToolbarWidget]:focus {
  outline-offset: -1px;
  outline: 1px solid color-mix(in srgb, var(--hot-pink) 60%, transparent);
}

[ngToolbarWidget][aria-pressed="true"],
[ngToolbarWidget][aria-checked="true"] {
  color: color-mix(in srgb, var(--hot-pink) 80%, var(--primary-contrast));
  background-color: color-mix(in srgb, var(--hot-pink) 10%, transparent);
}

app.ts

import {Component} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
})
export class App {}

app.html

<div ngToolbar class="material-toolbar" aria-label="Text Formatting Tools">
  <div class="group">
    <button
      ngToolbarWidget
      value="undo"
      type="button"
      aria-label="undo"
      class="material-symbols-outlined"
      translate="no"
    >
      undo
    </button>

    <button
      ngToolbarWidget
      value="redo"
      type="button"
      aria-label="redo"
      class="material-symbols-outlined"
      translate="no"
    >
      redo
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div class="group">
    <button
      ngToolbarWidget
      value="bold"
      type="button"
      aria-label="bold"
      #bold="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="bold.selected()"
      translate="no"
    >
      format_bold
    </button>

    <button
      ngToolbarWidget
      value="italic"
      type="button"
      aria-label="italic"
      #italic="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="italic.selected()"
      translate="no"
    >
      format_italic
    </button>

    <button
      ngToolbarWidget
      value="underlined"
      type="button"
      aria-label="underlined"
      #underlined="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="underlined.selected()"
      translate="no"
    >
      format_underlined
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment options">
    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align left"
      aria-label="align left"
      #leftAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="leftAlign.selected()"
      translate="no"
    >
      format_align_left
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align center"
      aria-label="align center"
      #centerAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="centerAlign.selected()"
      translate="no"
    >
      format_align_center
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align right"
      aria-label="align right"
      #rightAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="rightAlign.selected()"
      translate="no"
    >
      format_align_right
    </button>
  </div>
</div>

app.css

@import url('https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined');

:host {
  display: flex;
  justify-content: center;
}

[ngToolbar] {
  display: flex;
}

[ngToolbarWidget] {
  border: none;
  outline: none;
  cursor: pointer;
  width: 3rem;
  height: 3rem;
  font-size: 1.25rem;
  border-radius: 2rem;
  color: color-mix(in srgb, var(--vivid-pink) 70%, var(--full-contrast));
  background-color: color-mix(in srgb, var(--vivid-pink) 20%, transparent);
  transition:
    width 0.2s ease-in-out,
    background-color 0.15s ease-in-out,
    color 0.15s ease-in-out;
}

[ngToolbarWidget]:focus {
  outline-offset: 2px;
  outline: 2px solid var(--vivid-pink);
}

[ngToolbarWidget]:active,
[ngToolbarWidget][aria-pressed='true'],
[ngToolbarWidget][aria-checked='true'] {
  background-color: color-mix(in srgb, var(--vivid-pink) 80%, var(--full-contrast));
  color: var(--page-background);
}

[ngToolbarWidget][aria-checked='true'] {
  width: 4.5rem;
}

.group {
  display: flex;
  gap: 0.5rem;
}

.separator {
  width: 1px;
  margin: 0 1rem;
  height: calc(100% - 2rem);
  background-color: var(--quinary-contrast);
}

app.ts

import {Component} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
})
export class App {}

app.html

<div ngToolbar class="retro-toolbar" aria-label="Text Formatting Tools">
  <div class="group">
    <button
      ngToolbarWidget
      value="undo"
      type="button"
      aria-label="undo"
      class="material-symbols-outlined"
      translate="no"
    >
      undo
    </button>

    <button
      ngToolbarWidget
      value="redo"
      type="button"
      aria-label="redo"
      class="material-symbols-outlined"
      translate="no"
    >
      redo
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div class="group">
    <button
      ngToolbarWidget
      value="bold"
      type="button"
      aria-label="bold"
      #bold="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="bold.selected()"
      translate="no"
    >
      format_bold
    </button>

    <button
      ngToolbarWidget
      value="italic"
      type="button"
      aria-label="italic"
      #italic="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="italic.selected()"
      translate="no"
    >
      format_italic
    </button>

    <button
      ngToolbarWidget
      value="underlined"
      type="button"
      aria-label="underlined"
      #underlined="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-pressed]="underlined.selected()"
      translate="no"
    >
      format_underlined
    </button>
  </div>

  <div class="separator" role="separator"></div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment options">
    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align left"
      aria-label="align left"
      #leftAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="leftAlign.selected()"
      translate="no"
    >
      format_align_left
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align center"
      aria-label="align center"
      #centerAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="centerAlign.selected()"
      translate="no"
    >
      format_align_center
    </button>

    <button
      ngToolbarWidget
      role="radio"
      type="button"
      value="align right"
      aria-label="align right"
      #rightAlign="ngToolbarWidget"
      class="material-symbols-outlined"
      [aria-checked]="rightAlign.selected()"
      translate="no"
    >
      format_align_right
    </button>
  </div>
</div>

app.css

@import url('https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined');

:host {
  display: flex;
  justify-content: center;

  font-family: 'Press Start 2P';
  --retro-button-color: color-mix(in srgb, var(--vivid-pink) 80%, var(--page-background));
  --retro-shadow-light: color-mix(in srgb, var(--retro-button-color) 90%, #fff);
  --retro-shadow-dark: color-mix(in srgb, var(--retro-button-color) 90%, #000);
  --retro-elevated-shadow:
    inset 4px 4px 0px 0px var(--retro-shadow-light),
    inset -4px -4px 0px 0px var(--retro-shadow-dark), 4px 0px 0px 0px var(--tertiary-contrast),
    0px 4px 0px 0px var(--tertiary-contrast), -4px 0px 0px 0px var(--tertiary-contrast),
    0px -4px 0px 0px var(--tertiary-contrast);
  --retro-flat-shadow:
    4px 0px 0px 0px var(--tertiary-contrast), 0px 4px 0px 0px var(--tertiary-contrast),
    -4px 0px 0px 0px var(--tertiary-contrast), 0px -4px 0px 0px var(--tertiary-contrast);
  --retro-clickable-shadow:
    inset 4px 4px 0px 0px var(--retro-shadow-light),
    inset -4px -4px 0px 0px var(--retro-shadow-dark), 4px 0px 0px 0px var(--tertiary-contrast),
    0px 4px 0px 0px var(--tertiary-contrast), -4px 0px 0px 0px var(--tertiary-contrast),
    0px -4px 0px 0px var(--tertiary-contrast), 8px 8px 0px 0px var(--tertiary-contrast);
  --retro-pressed-shadow:
    inset 4px 4px 0px 0px var(--retro-shadow-dark),
    inset -4px -4px 0px 0px var(--retro-shadow-light), 4px 0px 0px 0px var(--tertiary-contrast),
    0px 4px 0px 0px var(--tertiary-contrast), -4px 0px 0px 0px var(--tertiary-contrast),
    0px -4px 0px 0px var(--tertiary-contrast), 0px 0px 0px 0px var(--tertiary-contrast);
}

[ngToolbar] {
  gap: 1.5rem;
  display: flex;
  padding: 1rem;
}

.group {
  gap: 1rem;
  display: flex;
}

.separator {
  width: 1px;
  align-self: center;
  height: calc(100% - 1rem);
  background-color: var(--quinary-contrast);
}

[ngToolbarWidget] {
  border: none;
  outline: none;
  cursor: pointer;
  padding: 0.5rem;
  font-size: 1.25rem;
  color: var(--page-background);

  background-color: var(--retro-button-color);
  box-shadow: var(--retro-clickable-shadow);
  transition:
    transform 0.1s,
    box-shadow 0.1s;
}

[ngToolbarWidget]:focus,
[ngToolbarWidget]:hover {
  transform: translate(1px, 1px);
}

[ngToolbarWidget]:active,
[ngToolbarWidget][aria-pressed='true'],
[ngToolbarWidget][aria-checked='true'] {
  transform: translate(4px, 4px);
  box-shadow: var(--retro-pressed-shadow);
  background-color: color-mix(in srgb, var(--retro-button-color) 60%, var(--gray-50));
}

[ngToolbarWidget]:focus {
  outline-offset: 4px;
  outline: 4px dashed var(--retro-button-color);
}

В этом сценарии разработчикам нужно учесть:

Клавиатурную навигацию. Пользователи должны открывать меню Enter или Space, перемещаться по опциям стрелками, выбирать Enter и закрывать Escape.
Screen readers должны объявлять состояние меню, число опций и какая опция в фокусе.
Управление фокусом должно логично перемещаться между trigger и пунктами меню.
Языки справа налево требуют возможности навигации в обратном направлении.

Что входит в комплект?

Angular Aria включает директивы с подробной документацией, рабочими примерами и API reference для распространённых интерактивных паттернов:

Поиск и выбор

Компонент	Описание
Autocomplete	Текстовый ввод с отфильтрованными подсказками по мере ввода
Listbox	Списки опций с одиночным или множественным выбором и клавиатурой
Select	Паттерн dropdown с одиночным выбором и клавиатурной навигацией
Multiselect	Паттерн dropdown с множественным выбором и компактным отображением
Combobox	Примитивная директива, координирующая текстовый ввод с popup

Компонент	Описание
Menu	Выпадающие меню со вложенными подменю и горячими клавишами
Menubar	Горизонтальная панель навигации для постоянных меню приложения
Toolbar	Группы элементов управления с логичной клавиатурной навигацией

Организация контента

Компонент	Описание
Accordion	Сворачиваемые панели контента — по одной или взаимоисключающе
Tabs	Вкладки с режимами автоматической или ручной активации
Tree	Иерархические списки с раскрытием/сворачиванием
Grid	Двумерное отображение данных с клавиатурной навигацией по ячейкам

Когда использовать Angular Aria

Angular Aria хорошо подходит, когда нужны доступные интерактивные компоненты, соответствующие WCAG, с кастомными стилями. Примеры:

Создание дизайн-системы — команда поддерживает библиотеку компонентов с конкретными визуальными стандартами и нуждается в доступных реализациях
Корпоративные библиотеки компонентов — вы создаёте переиспользуемые компоненты для нескольких приложений в организации
Требования бренда — интерфейс должен точно соответствовать дизайн-спецификациям, которые готовые стилизованные библиотеки плохо покрывают

Когда не использовать Angular Aria

Angular Aria подходит не для каждого сценария:

Готовые стилизованные компоненты — если нужны компоненты, которые выглядят завершённо без кастомных стилей, используйте Angular Material
Простые формы — нативные HTML-контролы вроде <button> и <input type="radio"> дают встроенную доступность для простых случаев
Быстрое прототипирование — при быстрой проверке идей готовые стилизованные библиотеки сокращают начальное время разработки

Следующие шаги

Выберите компонент в боковой навигации или в списке выше, либо начните с Toolbar, чтобы увидеть полный пример работы директив Angular Aria!

Что такое Angular Aria?

Установка

npm

yarn

pnpm

bun

Showcase

app.ts

app.html

app.css

app.ts

app.html

app.css

app.ts

app.html

app.css

Что входит в комплект?

Поиск и выбор

Навигация и действия

Организация контента

Когда использовать Angular Aria

Когда не использовать Angular Aria

Следующие шаги