Компонент SearchControl из библиотеки @wordpress/components предоставляет удобный интерфейс для ввода поисковых запросов. Этот компонент позволяет пользователям отображать поле для ввода текста с функцией поиска, что делает его идеальным для создания поисковых элементов в различных частях интерфейса.
Зачем использовать SearchControl?
SearchControl помогает создать доступный и функциональный интерфейс для поиска по записям или любому другому контенту. Этот компонент уже включает в себя все необходимые элементы для работы с полем ввода, а также предоставляет дополнительные параметры для кастомизации, такие как лейблы, placeholder и помощь по доступности.
Основное использование компонента SearchControl
Пример базового использования компонента SearchControl:
import { useState } from 'react';
import { __ } from '@wordpress/i18n';
import { SearchControl } from '@wordpress/components';
function MySearchControl( { className, setState } ) {
const [ searchInput, setSearchInput ] = useState( '' );
return (
<SearchControl
__nextHasNoMarginBottom
label={ __( 'Search posts' ) }
value={ searchInput }
onChange={ setSearchInput }
/>
);
}
Объяснение кода
- Хук useState
Мы создаем локальное состояние для хранения значения поля поиска, используяuseState. Это значение будет обновляться каждый раз, когда пользователь изменяет текст в поле поиска. - Компонент
SearchControl
В компонентеSearchControlпередаются следующие важные пропсы:label: описание поля для экранных читалок. В примере это «Search posts».value: текущее значение поля ввода, которое связано с состояниемsearchInput.onChange: функция, которая обновляет состояниеsearchInputпри изменении текста в поле.
__nextHasNoMarginBottom
Этот пропс помогает включить стили без нижнего отступа, что будет стандартом в будущих версиях.
Описание параметров (Props)
label- Тип:
String - Обязательный: Нет
- Описание: Доступный лейбл для поля ввода. Это описание будет доступно для экранных читалок, что является важной практикой для доступности. Если в поле ввода задан placeholder, лейбл все равно должен быть предоставлен для улучшения доступности.
- Пример:
label={ __( 'Search posts' ) }
- Тип:
placeholder- Тип:
String - Обязательный: Нет
- Описание: Текст, который будет отображаться в поле ввода до того, как пользователь начнет вводить текст. Если не задан, будет использоваться значение по умолчанию.
- Пример:
placeholder={ __( 'Enter your search query...' ) }
- Тип:
value- Тип:
String - Обязательный: Нет
- Описание: Текущее значение поля ввода. Это свойство связывается с состоянием компонента и обновляется каждый раз, когда пользователь вводит новый текст.
- Пример:
value={ searchInput }
- Тип:
className- Тип:
String - Обязательный: Нет
- Описание: Класс, который добавляется к контейнеру компонента. Это полезно для кастомизации стилей компонента.
- Пример:
className="my-custom-search"
- Тип:
onChange- Тип:
function - Обязательный: Да
- Описание: Функция, которая вызывается при изменении значения в поле ввода. Она получает новое значение как аргумент.
- Пример:
onChange={ (value) => setSearchInput(value) }
- Тип:
onClose- Тип:
function - Обязательный: Нет
- Описание: Этот пропс устарел. Когда предоставлен, он добавляет кнопку закрытия для поля поиска. Однако рекомендуется использовать другой способ для закрытия поиска.
- Тип:
help- Тип:
String | Element - Обязательный: Нет
- Описание: Текст или элемент, который будет отображаться как пояснение под полем ввода. Это может быть полезно для предоставления дополнительной информации или подсказок пользователю.
- Пример:
help={ __( 'Enter a keyword to search for posts' ) }
- Тип:
hideLabelFromVision- Тип:
Boolean - Обязательный: Нет
- Значение по умолчанию:
true - Описание: Если установлено в
true, лейбл не будет виден на экране, но будет доступен для экранных читалок. - Пример:
hideLabelFromVision={ true }
- Тип:
__nextHasNoMarginBottom- Тип:
Boolean - Обязательный: Нет
- Значение по умолчанию:
false - Описание: Включает стили без нижнего отступа. Это свойство будет стандартным в будущих версиях компонента.
- Тип:
size- Тип:
'default' | 'compact' - Обязательный: Нет
- Значение по умолчанию:
'default' - Описание: Определяет размер компонента. Если нужно меньшее поле для ввода, используйте значение
'compact'. - Пример:
size="compact"
- Тип:
Пример использования с дополнительными параметрами
import { useState } from 'react';
import { __ } from '@wordpress/i18n';
import { SearchControl } from '@wordpress/components';
function CustomSearchControl() {
const [ searchQuery, setSearchQuery ] = useState( '' );
return (
<SearchControl
label={ __( 'Search for content' ) }
placeholder={ __( 'Type your query here' ) }
value={ searchQuery }
onChange={ setSearchQuery }
help={ __( 'You can search for posts, pages, and other content.' ) }
size="compact"
hideLabelFromVision={ false }
/>
);
}
Важные моменты
- Доступность
Важно всегда предоставлятьlabel, чтобы компонент был доступен для экранных читалок. Это особенно важно для пользователей с ограниченными возможностями. - Кастомизация
КомпонентSearchControlможно кастомизировать с помощью различных пропсов, таких какsize,placeholder,help, и других, чтобы он соответствовал вашему дизайну и требованиям функциональности. - Устаревшие пропсы
ПропсonCloseустарел и будет удален в будущих версиях, так что следует избегать его использования.
Заключение
Компонент SearchControl — это мощный инструмент для добавления функциональности поиска в интерфейсе WordPress. Он прост в использовании и предоставляет множество опций для настройки доступности и внешнего вида. Вы можете легко кастомизировать компонент с помощью различных пропсов, чтобы он соответствовал вашему дизайну и улучшал пользовательский опыт.