useSliderThumb для ползунков

Хук useSliderThumb предназначен для создания доступных и интерактивных элементов ползунка в библиотеке React Aria. Он обеспечивает правильную работу с клавиатурой, фокусом, событиями мыши и сенсорного ввода, а также управление атрибутами ARIA для поддержки пользователей с особыми потребностями.

Хук используется внутри компонента thumb (ползунок), который является движущейся частью слайдера. Основной принцип работы — связывание состояния слайдера с DOM-элементом, предоставляя необходимые обработчики событий и атрибуты.

Импорт и базовое использование

import { useSliderThumb } from '@react-aria/slider';
import { useRef } from 'react';
import { useSliderState } from '@react-stately/slider';

function SliderThumb({ index, sliderState }) {
  const ref = useRef();
  const { thumbProps, inputProps, isDragging } = useSliderThumb({
    index,
    sliderState,
    // дополнительные опции
  }, ref);

  return (
    <div {...thumbProps} ref={ref}>
      <input {...inputProps} />
    </div>
  );
}

Ключевые моменты:

  • index — индекс текущего ползунка в слайдере (важно для множественных ползунков).
  • sliderState — объект состояния, полученный через useSliderState, который управляет значением и диапазоном слайдера.
  • thumbProps — набор свойств для основного DOM-элемента ползунка, включая обработку мыши, клавиатуры и фокуса.
  • inputProps — свойства для скрытого <input> элемента, чтобы обеспечить правильную интеграцию с формами и доступность.
  • isDragging — флаг, указывающий на активное перемещение ползунка.

Аргументы хука

Хук принимает два аргумента:

  1. Объект с параметрами:
{
  index,        // индекс ползунка
  sliderState,  // состояние слайдера
  isDisabled,   // необязательный, блокирует ползунок
  orientation,  // 'horizontal' или 'vertical'
  // возможны дополнительные настройки
}
  1. Ссылка на DOM-элемент: Используется для привязки событий и управления фокусом.

Основные возвращаемые значения

thumbProps

  • role: "slider" — указывает роль ползунка для технологий доступности.

  • aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext — атрибуты ARIA, обеспечивающие корректное озвучивание значений.

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

    • onFocus и onBlur — управление фокусом.
    • onKeyDown — обработка клавиш стрелок, Home, End для управления значением.
    • onPointerDown — начало перетаскивания мышью или сенсорным экраном.

inputProps

  • <input type="hidden"> для синхронизации значения с формой.
  • Включает name, value, onChange для корректной работы с HTML-формами.

isDragging

  • Булевый флаг, который позволяет визуально отображать состояние активного перемещения, например, изменение стиля или анимацию.

Примеры кастомизации

Горизонтальный слайдер

<SliderThumb index={0} sliderState={sliderState} orientation="horizontal" />

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

<SliderThumb index={1} sliderState={sliderState} orientation="vertical" />

Блокировка ползунка

<SliderThumb index={0} sliderState={sliderState} isDisabled={true} />

Интеграция с состоянием слайдера

useSliderThumb тесно связан с useSliderState. Пример инициализации состояния:

import { useSliderState } from '@react-stately/slider';

const sliderState = useSliderState({
  minValue: 0,
  maxValue: 100,
  defaultValue: [50], // для одного ползунка
  step: 1,
  isDisabled: false
});

Состояние управляет текущим значением, шагом, минимальным и максимальным пределами, а также поддерживает множественные ползунки.

Работа с клавиатурой и доступностью

Хук автоматически добавляет поддержку:

  • Стрелки вверх/вправо — увеличение значения.
  • Стрелки вниз/влево — уменьшение значения.
  • Home — установка в минимальное значение.
  • End — установка в максимальное значение.

Атрибуты ARIA гарантируют, что экранные читалки корректно озвучивают позицию ползунка.

Взаимодействие с несколькими ползунками

При использовании нескольких ползунков:

  • Каждый ползунок получает уникальный index.
  • useSliderState управляет массивом значений [value1, value2, ...].
  • Хук автоматически предотвращает пересечение ползунков и корректно перемещает их при перетаскивании.

Практические советы

  1. Использовать ref для прямого доступа к DOM, особенно если требуется кастомная анимация или взаимодействие с библиотеками визуализации.
  2. Поддерживать orientation, чтобы ползунки корректно реагировали на вертикальные и горизонтальные слайдеры.
  3. Всегда включать inputProps, если значение слайдера должно быть отправлено через форму.
  4. Использовать isDragging для визуальной обратной связи, например, изменение цвета или размера ползунка во время перетаскивания.

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

  • Совместимость с сенсорными экранами и pointer events.
  • Полная поддержка RTL (right-to-left) интерфейсов.
  • Возможность создавать диапазонные слайдеры с двумя и более ползунками.
  • Легкая интеграция с кастомной стилизацией и анимациями через CSS или библиотеки анимации.

Эта гибкость и готовность к доступности делает useSliderThumb ключевым инструментом для создания современных и удобных интерфейсов с ползунками в React.

Оглавление