RatingInput
Компонент для выбора оценки с помощью звёзд. Поддерживает дробные значения, сброс оценки, собственные иконки и управление с клавиатуры.
Быстрый старт
Управление внешним видом
Свойство view задаёт цветовое оформление, size — типографику значения и отступы, а iconSize — размер иконок. По умолчанию используются view="default", size="l" и iconSize="m".
- View
- Size
- IconSize
Доступны виды default и accent:
Доступны размеры s, m, l, h1, h2, h3, h4, h5, dsplS, dsplM и dsplL. Размер значения можно выбирать независимо от размера иконок:
Свойство iconSize принимает значения s, m и l:
Управление значением
В неуправляемом режиме начальная оценка задаётся через defaultValue. В управляемом режиме передавайте value и обновляйте его в обработчике onChange.
onChange получает выбранное число, а при сбросе — null. Значение null означает отсутствие оценки; значение 0 остаётся числовой оценкой.
- Управляемый
- Неуправляемый
Сброс оценки
При allowClear повторное нажатие на выбранную оценку сбрасывает её и вызывает onChange(null). По умолчанию allowClear выключен. В управляемом режиме оценку также можно сбросить, передав value={null}.
Дробные значения
Свойство fractions задаёт количество равных частей одной звезды. По умолчанию fractions={1}, шаг выбора равен 1 / fractions: 2 — половины, 3 — трети, 4 — четверти. Значение округляется до ближайшего шага и ограничивается диапазоном от 0 до iconQuantity.
Для стандартных звёзд при заполнении на половину используется готовая половинная иконка, в том числе при fractions={4}. Для остальных дробей применяется пропорциональное заполнение.
Количество звёзд
Количество звёзд задаётся свойством iconQuantity. По умолчанию отображается пять звёзд. Свойства iconQuantity и fractions принимают положительные целые числа.
Отображение значения
Свойство hasValue включает отображение выбранной оценки. По умолчанию выводится числовое значение value или внутреннее значение, заданное через defaultValue и изменённое пользователем. Когда оценка не выбрана, числовое значение не отображается.
С помощью renderValue можно задать свой текст или React-элемент. Функция получает выбранное число или null и вызывается при hasValue.
Положение и выравнивание
valuePlacement задаёт положение значения: top или bottom. valueAlign управляет выравниванием: start или center. По умолчанию значение находится снизу и центрируется относительно звёзд. Ширина боковых подписей на центрирование не влияет.
Подписи крайних значений
Свойство hasLimitLabels включает подписи, заданные через minLabel и maxLabel. С помощью limitLabelsPlacement можно расположить их сбоку (side, по умолчанию) или под звёздами (bottom).
Кастомные иконки
С помощью iconSlot можно заменить заполненную звезду, а с помощью iconSlotOutline — пустую. Цвет иконок наследуется при color="inherit".
При дробных значениях заполненная иконка обрезается пропорционально выбранной доле поверх пустой. Собственную иконку для дроби можно задать через renderFractionIcon.
Иконки для дробных значений
renderFractionIcon получает два аргумента: количество заполненных частей и количество частей одной звезды. Например, (3, 4) соответствует заполнению на три четверти.
Функция вызывается для частично заполненной иконки. Пустые и полные иконки задаются через iconSlotOutline и iconSlot. Если функция возвращает undefined, используется стандартное отображение дроби; null оставляет место дробной иконки пустым.
Наведение и события
При наведении заливка иконок показывает предварительную оценку. Обработчик onHoverChange получает эту оценку, а при уходе указателя со звёзд — null.
Выбранную оценку передаёт onChange. Для отображения выбранного значения в renderValue предварительная оценка не используется.
Работа с формой
Свойство name задаёт имя поля для отправки оценки в составе формы. Выбранное число передаётся строкой. При отсутствии выбранного значения поле не попадает в FormData.
В неуправляемом режиме сброс формы восстанавливает defaultValue. В управляемом режиме приложение обновляет value через состояние.
Доступность и клавиатура
С помощью aria-label или aria-labelledby задайте название группы оценок. getLabelText возвращает доступное название каждого варианта для скринридера. По умолчанию используется подпись вида «3 из 5».
getLabelText задаёт только доступные названия вариантов. Видимое значение настраивается через hasValue и renderValue.
| Клавиша | Действие |
|---|---|
Tab | Переводит фокус на выбранную оценку или первый вариант, если оценка не задана. |
→, ↑ | Выбирают следующий вариант с шагом 1 / fractions. |
←, ↓ | Выбирают предыдущий вариант с шагом 1 / fractions. |
Home | Выбирает первый вариант: 1 / fractions. |
End | Выбирает максимальную оценку: iconQuantity. |
Пробел | Выбирает вариант в фокусе. При allowClear повторное нажатие сбрасывает выбранную оценку. |
Навигация стрелками не зацикливается. На максимальной оценке → и ↑ сохраняют текущее значение. На первом варианте ← и ↓ сбрасывают оценку и вызывают onChange(null) независимо от allowClear; фокус остаётся на первом варианте. После сброса → или ↑ выбирают первое значение: 1 / fractions.