Создание пользовательского блока Гутенберга. Часть 5: Настройки инспектора

На предыдущих шагах мы узнали основы того, как визуализировать компоненты и атрибуты в блоке. На этом шаге мы сосредоточимся на том, что WordPress (по крайней мере, в коде) называет Inspector: на боковой панели справа в редакторе. Мы коснемся некоторых новых компонентов, которые имеет смысл разместить на боковой панели, и того, как с ними обращаться.

Инспектор / компонент боковой панели

Чтобы вставить свои пользовательские настройки и HTML-код в боковую панель Inspector, вы поместите все в компонент с именем InspectorControls. Все, что вы поместите внутрь этого компонента, будет выводиться на боковой панели, а не внутри самого блока/редактора. По сути, вы можете поместить компонент и его содержимое везде в возврате editфункции.

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

Давайте сначала посмотрим, как выглядит боковая панель нашего блока (когда наш блок активен в редакторе), основываясь на коде, который мы получили на предыдущем шаге.

Все блоки по умолчанию будут отображать значок, имя и описание блока, а раздел «Дополнительно» — свернутый. Внутри Advanced вы найдете текстовый ввод для предоставления класса CSS для блока.

Добавление раздела боковой панели и некоторых настроек

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

Используйте компонент PanelBodyдля добавления раздела (тех, которые вы можете открыть или свернуть), найденный в wp.componentsпакете. Компонент принимает несколько реквизитов, например, для заголовка и того, должна ли панель быть открытой или закрытой по умолчанию. Вы также можете предоставить собственный класс, значок и прикрепить функцию события к триггеру открытия-закрытия.

PanelBodyЗатем в WordPress рекомендуется использовать компонент, который действует как общие контейнеры внутри PanelRowпанели, чтобы обеспечить оптимизацию дизайна. Этот компонент автоматически применяет некоторые стили полей и гибких строк для вашего содержимого. Из-за flex-direction: rowстилей «» вы должны обернуть каждую настройку внутри одной PanelRow. Или вы можете вообще пропустить ее и взять на себя ответственность за ее стилизацию с помощью div и тому подобного.

Добавление панели и настроек

Давайте добавим боковую панель для нашего блока с несколькими настройками внутри, просто чтобы увидеть это на практике. Мы добавим переключатель, ввод выбора, палитру цветов и флажок — просто чтобы получить некоторый опыт работы с различными типами компонентов ввода. Я оставил содержимое блока (с двумя RichTexts) и saveфункцию, как и раньше.

Как всегда, мы начинаем с деструктуризации компонентов и функций, которые хотим использовать. Внутри attributesмы registerBlockType()определяем один атрибут для каждого входа и сопоставляем тип — например, элемент управления-переключатель ожидает логическое значение, а поскольку значения раскрывающегося списка являются строками, этот атрибут также должен быть строкой типа.

В строке #41мы запускаем InspectorControlsкомпонент, и все, что от этой точки до строки #80, появится в боковой панели. Остальное появится внутри самого редактора, а я там никаких изменений не делал.

Внутри мы сначала создаем панель с PanelBodyпараметром initialOpentrue и сообщаем Гутенбергу, что эта панель должна быть открыта по умолчанию. А дальше уже нам решать, что добавить внутрь каждого PanelRow.

Для компонента ToggleControlмы используем те же реквизиты, что и раньше, с текстовым вводом, за исключением того, что вместо реквизита valueмы предоставляем значение атрибута внутри реквизита checked. Это относится ко всем входным данным, которые ожидают наличия атрибута checked в простом HTML, например, к флажкам. Для переключателей вы должны использовать реквизит selected, так как это то, что вы использовали бы и в простом HTML. Имейте в виду, что атрибут для этого ввода должен быть типа boolean.

Что касается CheckboxControlфлажка при обработке единственного числа, то он работает точно так же, как и ToggleControl— он возвращает логическое значение независимо от того, отмечен он или нет.

Генерирует SelectControlраскрывающийся список выбора и ожидает возможные варианты выбора в виде массива в свойстве options. Каждый элемент должен быть объектом со свойствами labelи value. То же самое относится к флажкам и переключателям (RadioControl). В обычных обстоятельствах вы, вероятно, сгенерировали бы выбор как переменную вне вывода HTML.

Вы могли заметить, что ColorPickerон работает немного иначе, чем другие, так как это более сложный компонент, а не стандартный ввод HTML. Предоставьте опору colorдля сохраненного цвета и вместо onChange(срабатывает один раз при нажатии, но также и каждый раз, когда значение изменяется при перетаскивании — что может привести к большому количеству срабатываний) используйте onChangeComplete. Свойство, возвращаемое в этом событии, также является объектом, в котором нам нужно решить, какую часть мы хотим сохранить в нашем атрибуте. В этом примере мы хотим сохранить шестнадцатеричное значение (без альфы/непрозрачности), поэтому внутри setAttributes()мы извлекаем hexсвойство colorвозвращаемого объекта. Именно поэтому мы добавляем свойствоdisableAlphaкак удалить пользовательский интерфейс альфа-канала (для управления непрозрачностью), поскольку нет смысла предлагать пользователю это, когда мы никогда не сохраняем значение непрозрачности.

Каждый из компонентов имеет labelдоступную опору, кроме палитры цветов. Если вы хотите вывести метку или текст перед ним, вам нужно будет повозиться с HTML или стилем, чтобы убедиться, что он выглядит хорошо.

Очевидно, вы можете добавить столько панелей, сколько захотите, просто добавьте еще один PanelBodyкомпонент после предыдущего.

Если вам интересно узнать больше о добавлении настроек блока, у меня есть отдельные руководства для более сложных настроек и компонентов для Inspector; Как добавить выбор изображения и как добавить панель настроек цвета.

Умение обращатьсяsave

Я оставил saveфункцию, как это было раньше. Это зависит от вас, и все зависит от того, что настройки контролируют в выводе. Вы уже знаете, как получить значения каждого параметра. В качестве примера предположим, что логический атрибут activateLasersопределяет, будет ли отображаться пользовательский элемент HTML. Если атрибут trueдолжен быть выведен div, иначе нет. Вы можете сделать это с помощью традиционной проверки if или использовать встроенный ifи &&оператор JSX. Подробнее об этом читайте в руководстве React по условному рендерингу.

Поскольку мы используем RichTextэтот вывод, он не будет виден в редакторе, но появится во внешнем интерфейсе.

Вы найдете больше компонентов в wp.components репозитории Github. Большинство этих папок должны предоставить вам файл readme с некоторой документацией о том, как его использовать. Я узнал большую часть этого, просмотрев этот репозиторий, а также основные компоненты WordPress, как они это сделали.

В следующем шаге мы сосредоточимся на том, как управлять панелью инструментов блока. Мы узнаем, как обрабатывать, например, выравнивание блока и добавлять пользовательские кнопки на панель инструментов.