Компонент Toggle Group

Компонент Toggle Group представляет собой управляемый набор взаимосвязанных переключателей (toggle buttons), позволяющий создавать группы опций с единственным или множественным выбором. В SvelteKit UI реализация Toggle Group строится с учётом реактивной модели Svelte и интеграции с современными возможностями UI-стилей и accessibility (доступности).

Основные концепции

Toggle Group состоит из двух ключевых элементов:

  1. Контейнер группы (ToggleGroup) – управляет состоянием всей группы, задаёт тип выбора и обеспечивает синхронизацию дочерних кнопок.
  2. Элементы переключения (ToggleItem) – отдельные кнопки, которые могут быть выбраны пользователем.

Состояние группы можно управлять как контролируемо, так и неконтролируемо:

  • Контролируемое состояние задаётся через пропсы value (для одиночного выбора) или values (для множественного выбора) и изменяется через события on:change.
  • Неконтролируемое состояние хранится внутри компонента и автоматически обновляется при клике.

Структура Toggle Group

<script lang="ts">
  import { ToggleGroup, ToggleItem } from 'sveltekit-ui';

  let selectedValue = 'option1';
  let multipleValues: string[] = ['option2'];
</script>

<ToggleGroup type="single" bind:value={selectedValue}>
  <ToggleItem value="option1">Option 1</ToggleItem>
  <ToggleItem value="option2">Option 2</ToggleItem>
  <ToggleItem value="option3">Option 3</ToggleItem>
</ToggleGroup>

<ToggleGroup type="multiple" bind:values={multipleValues}>
  <ToggleItem value="option1">Option 1</ToggleItem>
  <ToggleItem value="option2">Option 2</ToggleItem>
  <ToggleItem value="option3">Option 3</ToggleItem>
</ToggleGroup>

Ключевые моменты структуры:

  • type="single" — позволяет выбрать только один элемент в группе.
  • type="multiple" — разрешает множественный выбор.
  • bind:value и bind:values обеспечивают реактивную привязку состояния.
  • Каждый ToggleItem обязательно должен иметь уникальный value.

Управление состоянием

Для одиночного выбора ToggleGroup использует строковое значение:

<ToggleGroup type="single" bind:value={selectedValue}>
  <ToggleItem value="a">A</ToggleItem>
  <ToggleItem value="b">B</ToggleItem>
</ToggleGroup>

<script>
  $: console.log(selectedValue); // вывод текущего выбранного значения
</script>

Для множественного выбора применяется массив:

<ToggleGroup type="multiple" bind:values={selectedItems}>
  <ToggleItem value="x">X</ToggleItem>
  <ToggleItem value="y">Y</ToggleItem>
</ToggleGroup>

<script>
  $: console.log(multipleValues); // ['x', 'y']
</script>

Изменение состояния может происходить программно, что позволяет интегрировать Toggle Group с формами или внешними состояниями:

<button on:click={() => selectedValue = 'option2'}>Выбрать Option 2</button>

Доступность (Accessibility)

SvelteKit UI заботится о правильной семантике:

  • role="group" для контейнера.

  • role="radio" или role="checkbox" для ToggleItem в зависимости от типа группы.

  • Поддержка клавиатурной навигации:

    • Стрелки ArrowLeft / ArrowRight для одиночного выбора.
    • Space и Enter для активации элемента.

  • Атрибуты aria-checked автоматически синхронизируются со состоянием.

Стилизация и кастомизация

Toggle Group предоставляет несколько точек кастомизации:

  1. Стилизация контейнера через проп class или CSS-переменные.

  2. Стилизация элементов через проп class и состояния:

    • .selected для активного элемента.
    • .disabled для заблокированного элемента.

Пример динамической стилизации:

<ToggleGroup type="single" bind:value={selectedValue} class="group">
  <ToggleItem value="1" class:selected={selectedValue === '1'}>1</ToggleItem>
  <ToggleItem value="2" class:selected={selectedValue === '2'}>2</ToggleItem>
</ToggleGroup>

<style>
  .group {
    display: flex;
    gap: 8px;
  }
  .selected {
    background-color: #1e40af;
    color: white;
  }
</style>

Расширенные возможности

  • Disabled элементы:

    <ToggleItem value="3" disabled>Option 3</ToggleItem>

    Заблокированный элемент не реагирует на клики и не влияет на состояние группы.

  • Обработчики событий:

    • on:change — срабатывает при изменении состояния группы.
    • on:click — срабатывает на уровне элемента.

  • Комбинированные группы: можно использовать несколько Toggle Groups на странице с независимым состоянием.

  • Интеграция с формами: Toggle Group можно использовать внутри <form>, передавая состояние через скрытые поля:

    <form on:submit|preventDefault={handleSubmit}>
  <ToggleGroup type="single" bind:value={selectedValue}>
    <ToggleItem value="a">A</ToggleItem>
    <ToggleItem value="b">B</ToggleItem>
  </ToggleGroup>
  <input type="hidden" name="selection" value={selectedValue} />
  <button type="submit">Отправить</button>
</form>

Рекомендации по использованию

  • Для одиночного выбора применять type="single" с bind:value.
  • Для множественного выбора применять type="multiple" с bind:values.
  • Стилизовать элементы через классы и состояния, а не напрямую через inline-стили, чтобы сохранить переиспользуемость.
  • Заблокированные элементы использовать только при необходимости, чтобы не нарушать пользовательский опыт.
  • Использовать события on:change для синхронизации состояния с внешними компонентами или API.

Toggle Group в SvelteKit UI — мощный инструмент для создания интерактивных интерфейсов с гибким управлением состоянием, доступностью и полной интеграцией с реактивной моделью Svelte.

Оглавление