В этой статье мы подробно рассмотрим компонент Autocomplete в WordPress, его назначение и использование. Autocomplete помогает предложить пользователю автозавершение текста при вводе определённого символа или префикса, что повышает удобство работы с редактором, например, для выбора блоков, пользователей или других данных.
Описание компонента Autocomplete
Компонент Autocomplete используется для добавления функционала автозавершения к полям ввода текста. В WordPress этот компонент часто используется для автозавершения ввода на основе списка предложений, которые отображаются в выпадающем меню при вводе текста.
Пропсы компонента Autocomplete
- record (необходим): объект с текстовым значением, к которому применяется автозавершение.
- Тип:
RichTextValue
- Тип:
- onChange (необходим): функция, которая вызывается при выборе опции для вставки в текст.
- Тип:
(value: string) => void
- Тип:
- onReplace (необходим): функция, которая вызывается при выборе опции для замены текста.
- Тип:
(values: RichTextValue[]) => void
- Тип:
- completers (необходим): массив всех автозаполнителей для текущего элемента.
- Тип:
Array<WPCompleter>
- Тип:
- contentRef (необходим): ссылка на редактируемый элемент, который будет служить якорем для всплывающего окна автозавершения.
- Тип:
MutableRefObject<HTMLElement | undefined>
- Тип:
- children (необходим): функция, возвращающая элементы для рендеринга внутри компонента Autocomplete.
- Тип:
Function
- Тип:
- isSelected (необходим): булевое значение, которое определяет, выбран ли компонент и нужно ли отображать всплывающее окно автозавершения.
- Тип:
Boolean
- Тип:
Интерфейс Completer
Каждый completer предоставляет интерфейс для автозавершения:
- name: имя автозаполнителя, используется для идентификации.
- options: данные, которые предлагаются для выбора.
- triggerPrefix: префикс, который запускает автозавершение.
- getOptionLabel: функция для отображения метки (label) каждого варианта.
- getOptionKeywords: функция для определения ключевых слов для совпадения.
- getOptionCompletion: функция для определения, как вариант будет вставлен в текст.
Доступные функции
- allowContext: функция, которая проверяет, можно ли использовать автозавершение в текущем контексте.
- className: класс для применения к меню автозавершения.
- isDebounced: функция для включения или отключения дебаунса при отображении автозавершений.
Пример использования компонента Autocomplete
import { RichText, useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';
import { registerBlockType } from '@wordpress/blocks';
registerBlockType('my-plugin/autocomplete-block', {
apiVersion: 2,
title: __('Autocomplete Block', 'my-plugin'),
description: __('Block with Autocomplete functionality', 'my-plugin'),
category: 'common',
icon: 'smiley',
attributes: {
value: {
type: 'string',
},
},
edit: ({ attributes, setAttributes }) => {
const autoConfigs = [
{
name: 'Fruits',
triggerPrefix: '/',
options: [
{ label: 'Apple', id: 1 },
{ label: 'Orange', id: 2 },
{ label: 'Banana', id: 3 },
],
getOptionLabel: (option) => `${option.label}`,
getOptionKeywords: (option) => [option.label],
getOptionCompletion: (option) => option.label,
},
];
return (
<div {...useBlockProps()}>
<RichText
autocompleters={autoConfigs}
value={attributes.value}
onChange={(newValue) => setAttributes({ value: newValue })}
placeholder={__('Type / to select a fruit', 'my-plugin')}
/>
</div>
);
},
save: ({ attributes }) => (
<div {...useBlockProps.save()}>
<RichText.Content value={attributes.value} />
</div>
),
});
Пример создания собственного автозаполнителя
Вы можете расширить стандартный функционал и добавить свой автозаполнитель, например, для выбора фруктов:
Этот код создаёт автозаполнитель для фрутов, который появляется при вводе символа ~. Для каждого фрукта отображается его визуальный символ (например, 🍎 для яблока).
(function () {
// Определим автозаполнитель для фруктов
const fruits = {
name: 'fruit',
triggerPrefix: '~',
options: [
{ visual: '🍎', name: 'Apple', id: 1 },
{ visual: '🍊', name: 'Orange', id: 2 },
{ visual: '🍇', name: 'Grapes', id: 3 },
{ visual: '🥭', name: 'Mango', id: 4 },
],
getOptionLabel: (option) => `${option.visual} ${option.name}`,
getOptionKeywords: (option) => [option.name],
getOptionCompletion: (option) => option.visual,
};
// Функция добавления нового автозаполнителя
function appendFruitCompleter(completers, blockName) {
return blockName === 'core/paragraph' ? [...completers, fruits] : completers;
}
// Используем хук для добавления автозаполнителя
wp.hooks.addFilter(
'editor.Autocomplete.completers',
'fruit-test/fruits',
appendFruitCompleter,
11
);
})();
Заключение
Использование компонента Autocomplete в WordPress с React значительно улучшает пользовательский интерфейс, позволяя быстро выбирать нужные элементы. С помощью автозаполнителей можно реализовывать различные сценарии, такие как выбор блоков, пользователей или других элементов через префиксы. Мы рассмотрели, как использовать стандартные и кастомные автозаполнители, а также как интегрировать этот функционал в блоки Gutenberg.