Внести вклад
Подробные руководства
Angular Aria

Toolbar

Обзор

Контейнер для группировки связанных контролов и действий с клавиатурной навигацией — обычно используется для форматирования текста, toolbars и командных панелей.

Использование

Toolbar лучше всего подходит для группировки связанных контролов, к которым пользователи часто обращаются. Рассмотрите toolbar, когда:

  • Несколько связанных действий — несколько контролов выполняют связанные функции (например, кнопки форматирования текста)
  • Важна эффективность клавиатуры — пользователи выигрывают от быстрой навигации стрелками
  • Сгруппированные контролы — нужно организовать контролы в логические секции с разделителями
  • Частый доступ — контролы используются многократно в рамках workflow

Избегайте toolbar, когда:

  • Достаточно простой группы кнопок — для 2–3 несвязанных действий лучше отдельные кнопки
  • Контролы не связаны — toolbar подразумевает логическую группировку; несвязанные контролы путают пользователей
  • Сложная вложенная навигация — глубокие иерархии лучше обслуживаются menus или navigation-компонентами

Возможности

Toolbar Angular предоставляет полностью доступную реализацию toolbar с:

  • Клавиатурной навигацией — перемещение по widgets стрелками, активация Enter или Space
  • Поддержкой screen reader — встроенные ARIA-атрибуты для вспомогательных технологий
  • Группами widgets — организация связанных widgets вроде radio button groups или toggle button groups
  • Гибкой ориентацией — горизонтальные или вертикальные layout с автоматической клавиатурной навигацией
  • Signal-based реактивностью — реактивное управление состоянием через сигналы Angular
  • Поддержкой двунаправленного текста — автоматическая обработка языков справа налево (RTL)
  • Настраиваемым фокусом — выбор между wrapping-навигацией или жёсткими остановками на краях

Примеры

Базовый горизонтальный toolbar

Горизонтальные toolbars организуют контролы слева направо — распространённый паттерн в текстовых редакторах и design tools. Стрелки перемещают между widgets, удерживая фокус внутри toolbar, пока пользователи не нажмут Tab для перехода к следующему элементу страницы.

Вертикальный toolbar

Вертикальные toolbars складывают контролы сверху вниз — полезно для side panels или вертикальных command palettes. Стрелки вверх и вниз перемещают между widgets.

Группы widgets

Группы widgets содержат связанные контролы, работающие вместе — например, опции выравнивания текста или форматирования списков. Группы поддерживают собственное внутреннее состояние, участвуя в навигации toolbar.

В примерах выше кнопки выравнивания обёрнуты в ngToolbarWidgetGroup с role="radiogroup", чтобы создать группу взаимоисключающего выбора.

Input multi контролирует, могут ли несколько widgets в группе быть выбраны одновременно:

<!-- Single selection (radio group) -->
<div ngToolbarWidgetGroup role="radiogroup" aria-label="Alignment">
  <button ngToolbarWidget value="left">Left</button>
  <button ngToolbarWidget value="center">Center</button>
  <button ngToolbarWidget value="right">Right</button>
</div>

<!-- Multiple selection (toggle group) -->
<div ngToolbarWidgetGroup [multi]="true" aria-label="Formatting">
  <button ngToolbarWidget value="bold">Bold</button>
  <button ngToolbarWidget value="italic">Italic</button>
  <button ngToolbarWidget value="underline">Underline</button>
</div>

Отключённые widgets

Toolbars поддерживают два режима disabled:

  1. Soft-disabled widgets остаются focusable, но визуально показывают недоступность
  2. Hard-disabled widgets полностью исключены из клавиатурной навигации.

По умолчанию softDisabled равен true, что позволяет disabled widgets всё ещё получать фокус. Чтобы включить hard-disabled режим, задайте [softDisabled]="false" на toolbar.

Поддержка right-to-left (RTL)

Toolbars автоматически поддерживают языки справа налево. Оберните toolbar в контейнер с dir="rtl", чтобы обратить layout и направление клавиатурной навигации. Навигация стрелками корректируется автоматически: стрелка влево переходит к следующему widget, стрелка вправо — к предыдущему.

Тестирование

Angular Aria предоставляет component harnesses для тестирования компонентов toolbar. Пример использования harnesses в тесте компонента:

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {HarnessLoader} from '@angular/cdk/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {ToolbarHarness} from '@angular/aria/toolbar/testing';
import {MyToolbarComponent} from './my-toolbar'; // Your component

describe('MyToolbarComponent', () => {
  let fixture: ComponentFixture<MyToolbarComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MyToolbarComponent],
    });

    fixture = TestBed.createComponent(MyToolbarComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should have widgets and allow selection', async () => {
    // Load the toolbar harness
    const toolbar = await loader.getHarness(ToolbarHarness);

    // Get all widgets
    const widgets = await toolbar.getWidgets();
    expect(widgets.length).toBe(3);

    // Click the first widget
    await widgets[0].click();

    // Verify selection state
    expect(await widgets[0].isSelected()).toBe(true);
  });
});

API reference

Подробную API-документацию смотрите в следующих API reference: