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

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

ToolbarItem — это универсальный компонент WordPress на базе React, который позволяет превращать любой пользовательский элемент в элемент панели инструментов (Toolbar). Он отлично подходит для создания гибких элементов управления, таких как кнопки, меню и другие элементы, которые можно поместить в панель инструментов или группу инструментов.

Основные возможности ToolbarItem

  • Гибкость: с помощью ToolbarItem можно превращать любые HTML-элементы или React-компоненты в элементы панели инструментов.
  • Совместимость с Toolbar и ToolbarGroup: рекомендуется использовать ToolbarItem внутри компонентов Toolbar или ToolbarGroup для создания структурированных интерфейсов.
  • Поддержка BlockControls: если ToolbarItem используется в создании элементов управления для пользовательского блока, лучше использовать его вместе с BlockControls.

Использование свойства as

Свойство as позволяет задать HTML-элемент или пользовательский компонент, который будет использоваться для ToolbarItem. В этом примере мы создадим панель с двумя кнопками, определяя их с помощью свойства as.

import { Toolbar, ToolbarItem, Button } from '@wordpress/components';

function CustomToolbar() {
    return (
        <Toolbar label="Настройки">
            <ToolbarItem as={Button} onClick={() => console.log('Кнопка 1 нажата')}>
                Я кнопка в панели инструментов
            </ToolbarItem>
            <ToolbarItem as="button" onClick={() => console.log('Кнопка 2 нажата')}>
                Я другая кнопка в панели инструментов
            </ToolbarItem>
        </Toolbar>
    );
}

Применение ToolbarItem с функцией children

Свойство children можно использовать как функцию, которая получает HTML-свойства ToolbarItem. Эти свойства можно передать другому компоненту для создания более сложных интерфейсов. В примере ниже ToolbarItem используется для создания меню с помощью компонента DropdownMenu.

import { Toolbar, ToolbarItem, DropdownMenu } from '@wordpress/components';
import { table } from '@wordpress/icons';

function CustomToolbarWithMenu() {
    return (
        <Toolbar label="Опции">
            <ToolbarItem>
                { (toolbarItemHTMLProps) => (
                    <DropdownMenu
                        icon={table}
                        toggleProps={toolbarItemHTMLProps}
                        label="Редактировать таблицу"
                        controls={[
                            {
                                title: 'Добавить строку',
                                onClick: () => console.log('Строка добавлена'),
                            },
                            {
                                title: 'Удалить строку',
                                onClick: () => console.log('Строка удалена'),
                            },
                        ]}
                    />
                )}
            </ToolbarItem>
        </Toolbar>
    );
}

Использование ToolbarItem с BlockControls

Если вы создаете пользовательский блок и хотите добавить элементы управления на панель блока, рекомендуется использовать ToolbarItem в сочетании с BlockControls и, при необходимости, с ToolbarGroup. В этом примере ToolbarItem добавляется в блок с использованием BlockControls.

import { BlockControls } from '@wordpress/block-editor';
import { ToolbarGroup, ToolbarItem, Button } from '@wordpress/components';

function EditBlock() {
    return (
        <BlockControls>
            <ToolbarGroup>
                <ToolbarItem as={Button} onClick={() => console.log('Кнопка блока нажата')}>
                    Кнопка блока
                </ToolbarItem>
            </ToolbarGroup>
        </BlockControls>
    );
}

Параметры компонента ToolbarItem

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

СвойствоТипОписание
asReact.ElementTypeУказывает HTML-элемент или компонент, который будет отображаться в качестве элемента панели.
children(props) => ReactNodeФункция, которая получает HTML-свойства ToolbarItem и позволяет их передавать другому компоненту.

Пример с изменением элемента через as

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

import { Toolbar, ToolbarItem } from '@wordpress/components';

function NavigationToolbar() {
    return (
        <Toolbar label="Навигация">
            <ToolbarItem as="a" href="#section1">
                Перейти к секции 1
            </ToolbarItem>
            <ToolbarItem as="a" href="#section2">
                Перейти к секции 2
            </ToolbarItem>
        </Toolbar>
    );
}

Пример: использование ToolbarItem для кастомного компонента

В этом примере мы создаем кастомный компонент CustomButton, который будет использоваться в ToolbarItem. Это позволяет создать уникальный вид кнопок в панели инструментов.

import { Toolbar, ToolbarItem } from '@wordpress/components';

function CustomButton({ label, onClick }) {
    return (
        <button className="custom-button" onClick={onClick}>
            {label}
        </button>
    );
}

function CustomToolbarWithCustomButton() {
    return (
        <Toolbar label="Настройки">
            <ToolbarItem as={CustomButton} label="Моя кнопка" onClick={() => console.log('Моя кнопка нажата')} />
        </Toolbar>
    );
}

Пример с добавлением иконки и настройкой параметров

Добавим параметр иконки к ToolbarItem с использованием свойства children для кастомного отображения. Это полезно для создания кнопок с иконками и текстом.

import { Toolbar, ToolbarItem } from '@wordpress/components';
import { edit } from '@wordpress/icons';

function IconButton({ icon, label, onClick }) {
    return (
        <button onClick={onClick} style={{ display: 'flex', alignItems: 'center' }}>
            {icon}
            <span style={{ marginLeft: '4px' }}>{label}</span>
        </button>
    );
}

function ToolbarWithIconButton() {
    return (
        <Toolbar label="Инструменты">
            <ToolbarItem as={IconButton} icon={edit} label="Редактировать" onClick={() => console.log('Редактировать')} />
        </Toolbar>
    );
}

Заключение

Компонент ToolbarItem в WordPress предоставляет гибкий способ создания пользовательских элементов в панели инструментов. Он идеально подходит для различных типов элементов управления, от простых кнопок до более сложных меню. Используя свойства as и children, разработчики могут легко создавать адаптируемые элементы интерфейса для нужд панелей инструментов в редакторе WordPress.

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

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