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

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

Компонент RichText предоставляет гибкий контент с возможностью редактирования (contenteditable), позволяя пользователям форматировать текст, добавлять ссылки, использовать жирный и курсивный шрифт, и многое другое. Этот компонент является мощным инструментом для разработчиков блоков в WordPress, поскольку он автоматически обрабатывает большинство функциональных возможностей и взаимодействий с блоками.

Преимущества использования RichText
  1. Единый стиль в админке и на фронтенде: можно выбрать любой блоковый HTML-элемент, например, div, p или h2, что упрощает работу с CSS.
  2. Поддержка placeholder: можно задать текст-заполнитель, который отображается, пока пользователь не начал ввод.
  3. Контроль форматов: можно задать форматы, которые будут доступны пользователям (жирный, курсив и другие).

Основные параметры компонента RichText

ПараметрТипОписание
tagNamestringОпределяет HTML-тег (например, p, h2 и т.д.), который будет использоваться для редактируемого элемента.
valuestringСодержит текст, который будет отображаться и редактироваться в блоке.
onChangefunctionФункция, вызываемая при изменении контента.
allowedFormatsArrayОпределяет, какие форматы (например, bold, italic) можно применять к тексту.
placeholderstringТекст-заполнитель, который отображается, пока пользователь не начал ввод.
withoutInteractiveFormattingbooleanЕсли true, отключает все форматы и делает RichText чистым текстовым полем без форматирования.

Регистрация простого блока с компонентом RichText

Этот пример демонстрирует, как создать блок с использованием RichText. Блок включает заголовок, который можно форматировать (жирный и курсив).

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

registerBlockType('custom/richtext-example', {
    title: __('RichText Example', 'text-domain'),
    icon: 'edit',
    category: 'text',

    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'h2',
        },
    },

    edit({ attributes, setAttributes }) {
        const blockProps = useBlockProps();

        return (
            <RichText
                { ...blockProps }
                tagName="h2" // Заголовок второго уровня
                value={ attributes.content } // Содержимое блока
                allowedFormats={ [ 'core/bold', 'core/italic' ] } // Доступны только жирный и курсив
                onChange={ (content) => setAttributes({ content }) } // Обновление содержимого
                placeholder={ __('Введите заголовок...', 'text-domain') } // Плейсхолдер
            />
        );
    },

    save({ attributes }) {
        const blockProps = useBlockProps.save();

        return <RichText.Content { ...blockProps } tagName="h2" value={ attributes.content } />;
    },
});

Пример с использованием свойства allowedFormats

В этом примере мы ограничим форматы только курсивом и жирным, исключая возможность добавления других форматов.

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

registerBlockType('custom/format-restricted', {
    title: __('Format Restricted Block', 'text-domain'),
    icon: 'format-image',
    category: 'text',

    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
    },

    edit({ attributes, setAttributes }) {
        const blockProps = useBlockProps();

        return (
            <RichText
                { ...blockProps }
                tagName="p" // Параграф
                value={ attributes.content }
                allowedFormats={ [ 'core/bold', 'core/italic' ] } // Только жирный и курсив
                onChange={ (content) => setAttributes({ content }) }
                placeholder={ __('Введите текст...', 'text-domain') }
            />
        );
    },

    save({ attributes }) {
        const blockProps = useBlockProps.save();

        return <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } />;
    },
});

Пример с withoutInteractiveFormatting

Если нужно сделать поле только для ввода текста без каких-либо форматов, можно использовать withoutInteractiveFormatting.

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

registerBlockType('custom/plaintext-block', {
    title: __('Plain Text Block', 'text-domain'),
    icon: 'text',
    category: 'text',

    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'div',
        },
    },

    edit({ attributes, setAttributes }) {
        const blockProps = useBlockProps();

        return (
            <RichText
                { ...blockProps }
                tagName="div" // Контейнер
                value={ attributes.content }
                onChange={ (content) => setAttributes({ content }) }
                withoutInteractiveFormatting // Без форматирования
                placeholder={ __('Введите текст...', 'text-domain') }
            />
        );
    },

    save({ attributes }) {
        const blockProps = useBlockProps.save();

        return <RichText.Content { ...blockProps } tagName="div" value={ attributes.content } />;
    },
});

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

placeholder можно использовать для добавления текста, который будет отображаться, пока пользователь не начнет вводить данные. Это удобно для подсказок.

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

registerBlockType('custom/placeholder-example', {
    title: __('Placeholder Example', 'text-domain'),
    icon: 'welcome-write-blog',
    category: 'text',

    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
    },

    edit({ attributes, setAttributes }) {
        const blockProps = useBlockProps();

        return (
            <RichText
                { ...blockProps }
                tagName="p"
                value={ attributes.content }
                onChange={ (content) => setAttributes({ content }) }
                placeholder={ __('Начните вводить текст...', 'text-domain') } // Текст-заполнитель
            />
        );
    },

    save({ attributes }) {
        const blockProps = useBlockProps.save();

        return <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } />;
    },
});
Частые проблемы и решения
  • Отображение HTML-тегов форматирования: если HTML-теги, такие как <strong> или <em>, отображаются на сайте вместо форматирования текста, убедитесь, что сохранение контента выполняется через RichText.Content, как показано в примерах выше.
  • Ненужные опции форматирования: если необходимо отключить все опции форматирования, можно использовать withoutInteractiveFormatting или ограничить форматы через allowedFormats.
  • Отключение отдельных типов форматов: если нужно убрать конкретный формат (например, изображения), можно воспользоваться функцией unregisterFormatType. Например:
wp.richText.unregisterFormatType('core/image');

Заключение

Компонент RichText является мощным инструментом для создания редактируемого контента в WordPress. С его помощью можно легко реализовать блоки с возможностью форматирования текста, ограничить доступные форматы, задать плейсхолдер и многое другое.

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

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