FormTokenField — это компонент, который создает поле для ввода токенов, напоминающее поля тегов или категорий в WordPress. Компонент позволяет пользователям вводить токены вручную или выбирать их из предложенного списка.
Этот компонент полезен для создания интерфейсов, где нужно добавлять несколько значений (например, теги, категории, получатели сообщений и т.п.). Подсказки появляются автоматически на основе введенного текста и могут быть выбраны с помощью клавиш управления.
Основные Принципы Использования FormTokenField
Клавиатурная навигация:
- Стрелка влево/вправо — перемещение курсора между токенами.
- Стрелка вверх/вниз — выбор предыдущей/следующей подсказки.
- Tab / Enter / запятая — добавление токена.
Когда использовать FormTokenField:
- Для ввода нескольких элементов или тегов, как в поле тегов или категорий.
- Для автоматического завершения ввода, отображая подсказки.
Параметры компонента FormTokenField
Компонент FormTokenField поддерживает множество параметров, которые позволяют гибко управлять его поведением.
- value — Список токенов, отображаемых в поле. Если это массив объектов, каждый объект должен иметь ключ
value.- Тип: Массив строк или объектов.
- Обязательный: Нет.
value={[
{ value: "Africa", status: "success" },
{ value: "Antarctica", title: "Заснеженный континент" },
]}
- displayTransform — функция, вызываемая для преобразования токенов перед их отображением. Например, это может быть полезно для декодирования HTML-сущностей, таких как
&, которые могут быть дважды закодированы через REST API и React. Функция принимает значение токена и должна возвращать его отформатированную версию.- Тип:
Function - Обязательный: Нет
- Тип:
displayTransform={(token) => token.toUpperCase()}
- saveTransform — функция для преобразования токенов перед сохранением. По умолчанию удаляет пробелы в начале и конце значения токена, что важно для корректного совпадения токенов в случаях с пробелами. Особенно полезно при работе с API WordPress, так как API может не сохранить токен с ведущими и завершающими пробелами.
- Тип:
Function - Обязательный: Нет
- Тип:
saveTransform={(token) => token.trim()}- onChange — функция, которая вызывается при изменении токенов. Она принимает массив новых токенов, позволяя обработать добавление или удаление значений в поле.
- Тип:
Function - Обязательный: Да
- Тип:
onChange={(tokens) => console.log("Текущие токены:", tokens)}
- onInputChange — функция, вызываемая при вводе текста в поле. Обычно используется для выполнения автозаполнения (например, вызова сервера для получения предложений).
- Тип:
Function - Обязательный: Нет
- Тип:
onInputChange={(input) => console.log("Введенный текст:", input)}
- onFocus — функция, вызываемая при фокусе на поле
FormTokenField. Принимает событиеFocusEvent, полезно для аналитики, чтобы отслеживать моменты, когда поле активно.- Тип:
Function - Обязательный: Нет
- Тип:
- suggestions — массив строк, который используется для автозаполнения. Предоставляет пользователю варианты для быстрого выбора токенов.
- Тип:
Array<string> - Обязательный: Нет
- Тип:
suggestions={["Africa", "America", "Asia", "Europe", "Oceania"]}- maxSuggestions — максимальное количество отображаемых предложений одновременно. Полезно для ограничения количества элементов в выпадающем списке.
- Тип:
Number - Обязательный: Нет
- Тип:
maxSuggestions={5}- tokenizeOnSpace — если установлено в
true, при нажатии пробела, введенное значение будет добавлено в поле как токен.- Тип:
Boolean - Обязательный: Нет
- Тип:
tokenizeOnSpace={true}- isBorderless — если установлено в
true, рендеринг токенов будет без фона.- Тип:
Boolean - Обязательный: Нет
- Тип:
isBorderless={true}- maxLength — ограничивает количество токенов, которые можно добавить в поле. Полезно для контроля за количеством значений.
- Тип:
Number - Обязательный: Нет
- Тип:
maxLength={10}- disabled — при значении
trueтокены нельзя добавлять или удалять. Полезно для блокировки ввода.- Тип:
Boolean - Обязательный: Нет
- Тип:
disabled={true}- placeholder — строка-заполнитель, отображаемая в поле, когда токены отсутствуют.
- Тип:
String - Обязательный: Нет
- Тип:
placeholder="Введите континент..."- messages — объект, настраивающий сообщения для экранных считывателей при различных действиях (например, добавление или удаление токена).
- Поддерживаемые свойства:
added: сообщение, когда добавляется новый токен.removed: сообщение при удалении токена.remove: сообщение, когда пользователь фокусируется на кнопке для удаления токена.
- Тип:
Object - Обязательный: Нет
- Поддерживаемые свойства:
messages={{
added: "Токен добавлен",
removed: "Токен удален",
remove: "Нажмите для удаления"
}}- __experimentalInvalid — отображается, если пользователь пытается добавить токен, который не проходит проверку.
- Тип:
Boolean - Обязательный: Нет
- Тип:
- __experimentalRenderItem — пользовательская функция для рендеринга элементов в списке предложений. Получает объект
item, содержащий данные отдельного предложения.- Тип:
Function - Обязательный: Нет
- Тип:
- __experimentalExpandOnFocus — если установлено в
true, список предложений всегда будет развернут, когда поле ввода находится в фокусе.- Тип:
Boolean - Обязательный: Нет
- Тип:
- __experimentalShowHowTo — если установлено в
false, текст с указанием, как использовать выбор (например, «Разделяйте запятыми или клавишей Enter»), будет скрыт.- Тип:
Boolean - Обязательный: Нет
- Тип:
- __experimentalValidateInput — проверяет все введенные значения перед добавлением их как токенов. Полезно для валидации данных.
- Тип:
Function - Обязательный: Нет
- Тип:
- __experimentalAutoSelectFirstMatch — если установлено в
true, автоматически выбирает первое совпадающее предложение при нажатии Enter.- Тип:
Boolean - Обязательный: Нет
- Тип:
- __next40pxDefaultSize — включение увеличенного по умолчанию размера высоты, который станет стандартом в будущей версии.
- Тип:
Boolean - Обязательный: Нет
- Тип:
- __nextHasNoMarginBottom — опция для использования стиля без нижнего поля, который станет стандартом в WordPress 7.0.
- Тип:
Boolean - Обязательный: Нет
- Тип:
- tokenizeOnBlur — при значении
trueдобавляет значение, которое еще не завершено в поле, как новый токен при потере фокуса.- Тип:
Boolean - Обязательный: Нет
- Тип:
Пример 1: Базовый пример с подсказками
import { useState } from 'react';
import { FormTokenField } from '@wordpress/components';
const tags = ["JavaScript", "React", "WordPress", "PHP", "CSS"];
const TagSelector = () => {
const [selectedTags, setSelectedTags] = useState([]);
return (
<FormTokenField
value={selectedTags}
suggestions={tags}
onChange={(tokens) => setSelectedTags(tokens)}
placeholder="Введите теги..."
/>
);
};
export default TagSelector;
Пример 2: Ограничение на количество токенов
import { useState } from 'react';
import { FormTokenField } from '@wordpress/components';
const limitedTags = ["HTML", "CSS", "JavaScript", "React", "Node.js"];
const LimitedTagSelector = () => {
const [tags, setTags] = useState([]);
return (
<FormTokenField
value={tags}
suggestions={limitedTags}
onChange={(newTags) => setTags(newTags)}
maxLength={3}
placeholder="Выберите до 3 тегов"
/>
);
};
export default LimitedTagSelector;
Пример 3: Кастомизация сообщений для экранных ридеров
import { useState } from 'react';
import { FormTokenField } from '@wordpress/components';
const AccessibleTagSelector = () => {
const [tokens, setTokens] = useState([]);
return (
<FormTokenField
value={tokens}
onChange={(newTokens) => setTokens(newTokens)}
messages={{
added: "Токен успешно добавлен.",
removed: "Токен удален.",
remove: "Нажмите, чтобы удалить токен."
}}
placeholder="Добавьте новый токен"
/>
);
};
export default AccessibleTagSelector;
Заключение
Компонент FormTokenField предоставляет гибкий и удобный интерфейс для ввода токенов, который можно использовать для создания списков тегов, категорий или других элементов. С его помощью можно легко реализовать автозаполнение, ограничения на количество токенов, кастомизацию сообщений и другие функции, подходящие для разных сценариев.