Компонент TextControl в WordPress: Полное руководство с примерами

Главная - WordPress Codex - Компонент TextControl в WordPress: Полное руководство с примерами
Доступна с версии: 5.0
Раздел: Gutenberg
Написал: Александр Сокирка

Компонент TextControl из библиотеки компонентов WordPress помогает разработчикам создавать поля для ввода текста. Этот компонент идеально подходит для однострочного ввода, например, для имени, email-адреса или дополнительных CSS-классов. В статье рассмотрим рекомендации по дизайну и разработке TextControl, его свойства и функциональные возможности, а также примеры использования с уникальными вариантами.

Основные концепции TextControl

Компонент TextControl предоставляет пользователю поле для ввода и редактирования текста. Поля могут быть пустыми или заполненными и поддерживают различные параметры для гибкой настройки интерфейса.

Дизайн и назначение

При работе с TextControl важно следовать следующим правилам дизайна:

  • Использовать для ввода свободного текста — для случаев с заранее определёнными вариантами выбора лучше подходят SelectControl, RadioControl, CheckboxControl или RangeControl.
  • Подходит для однострочного ввода — длинные текстовые ответы лучше собирать через TextareaControl.
  • Отчётливо показывать, что поле доступно для ввода — можно добавить обводку или контрастный фон для улучшения видимости.

Анатомия компонента TextControl

Каждое поле TextControl состоит из следующих элементов:

  • Метка (Label) — информирует пользователя, какие данные требуются.
  • Контейнер ввода — создаёт визуальный контраст, облегчая идентификацию поля.
  • Текст ввода — текст, вводимый пользователем.
  • Подсказка (Help) — дополнительный текст для пояснения назначения поля.

Пример использования TextControl

Рассмотрим пример кода с компонентом TextControl, где пользователь вводит дополнительный CSS-класс. В данном примере для уникальности мы изменим ID и текст метки.

import { useState } from 'react';
import { TextControl } from '@wordpress/components';

const CustomTextControl = () => {
    const [className, setClassName] = useState('');

    return (
        <TextControl
            label="Введите CSS-класс для оформления"
            help="Дополнительный класс для стилей блока."
            value={className}
            onChange={(value) => setClassName(value)}
            className="custom-css-input"
        />
    );
};

Пояснение

  • label — метка «Введите CSS-класс для оформления» помогает пользователю понять, что в поле нужно ввести название CSS-класса.
  • help — текст помощи «Дополнительный класс для стилей блока» уточняет цель поля.
  • onChange — функция, вызываемая при изменении текста в поле, обновляет состояние className.

Свойства компонента TextControl

Компонент TextControl поддерживает ряд полезных свойств для тонкой настройки.

  • label — задаёт текст метки, видимой над полем.
  • help — текст помощи, отображаемый под полем.
  • hideLabelFromVision — Если установить значение true, то метка будет скрыта для визуальных пользователей, но останется доступной для пользователей экранных читалок, что полезно для улучшения доступности.
  • value — текущее значение ввода.
  • onChange — функция, вызываемая при изменении текста.
  • type — тип поля ввода, по умолчанию text, но можно задать email, number и другие.
  • className — Класс CSS, который добавляется к div-обёртке компонента наряду с components-base-control. Если класс не указан, используется только components-base-control.
  • __next40pxDefaultSize — Экспериментальный параметр, который в будущем может стать стандартным. Если установлен в true, компонент принимает увеличенный размер по умолчанию (40px высота), что может улучшить взаимодействие на устройствах с сенсорным экраном.

Пример с email-вводом

Создадим пример, где TextControl используется для ввода email-адреса.

import { useState } from 'react';
import { TextControl } from '@wordpress/components';

const CompleteTextControlExample = () => {
    const [email, setEmail] = useState('');

    return (
        <TextControl
            label="Адрес электронной почты"
            hideLabelFromVision={false}
            help="Введите ваш email для подписки на рассылку."
            type="email"
            value={email}
            onChange={(value) => setEmail(value)}
            className="newsletter-email-input"
            __next40pxDefaultSize={true}
        />
    );
};

Пояснение

  • label: Текст метки — «Адрес электронной почты», помогает пользователю понять, что требуется ввод email-адреса.
  • hideLabelFromVision: Установлено в false, чтобы метка была видна всем пользователям.
  • help: Текст подсказки «Введите ваш email для подписки на рассылку» служит для пояснения цели поля.
  • type: Указан тип email, что помогает браузеру проверять корректность введённого email.
  • value: Значение в поле, обновляемое при каждом вводе.
  • onChange: Обновляет состояние email при каждом изменении текста в поле.
  • className: Добавлен CSS-класс newsletter-email-input для стилизации.
  • __next40pxDefaultSize: Установлен в true, увеличивая высоту поля до 40px, что улучшает взаимодействие на сенсорных устройствах.

Пример с числовым вводом

Компонент TextControl также можно использовать для ввода чисел, установив type="number".

import { useState } from 'react';
import { TextControl } from '@wordpress/components';

const NumberInput = () => {
    const [value, setValue] = useState('');

    return (
        <TextControl
            label="Количество товаров"
            value={value}
            onChange={(value) => setValue(value)}
            type="number"
            help="Введите количество товаров для заказа."
            className="product-quantity-input"
        />
    );
};

Пояснение

  • type — number превращает поле ввода в числовое, что полезно для ввода количества.
  • className — product-quantity-input добавляет CSS-класс для стилей.

Пример скрытия метки

При необходимости можно скрыть метку для визуальных пользователей, оставив её видимой только для экранных читалок. Для этого используйте свойство hideLabelFromVision.

import { useState } from 'react';
import { TextControl } from '@wordpress/components';

const HiddenLabelInput = () => {
    const [name, setName] = useState('');

    return (
        <TextControl
            label="Имя пользователя"
            hideLabelFromVision
            value={name}
            onChange={(value) => setName(value)}
            className="hidden-label-input"
        />
    );
};

Заключение

Компонент TextControl — это гибкое средство для ввода текста, поддерживающее различные типы данных и настройку параметров.

Стартовая премиум тема для WordPress
Демо импорт тестового контента в 1 клик.
SEO оптимизированный и валидный код.
Множество готовых стартовых сайтов.
Лучшая документация и поддержка.
Опции персонализации контента.
Креативный и современный дизайн.
Тема для WordPress

Дополнительно по: Gutenberg