Добавьте пользовательскую боковую панель инспектора в WordPress Gutenberg с помощью Post Meta

В этом уроке мы рассмотрим, как добавить пользовательскую боковую панель в Инспектор (правая боковая панель) в WordPress Gutenberg. Внутри мы реализуем поле, связанное с метаданными записи. Все реализовано с помощью Javascript внутри редактора Gutenberg и является альтернативой традиционному добавлению метабоксов.

Берегись!

Это руководство по созданию собственной пользовательской боковой панели. Но если вас интересует просто добавление метаданных/настроек на стандартную боковую панель Инспектора (вкладка «Документ»), у меня есть руководство именно для этого:

Что мы создадим

WordPress Gutenberg позволяет разработчикам создавать собственные боковые панели с помощью так называемого плагина Javascript. (Не путать с традиционными плагинами WordPress). Используя плагин Javascript, мы можем создать новую боковую панель, а также подключить ее к меню «Инструменты и параметры».

Мы добавим новый пункт меню в «Инструменты», который откроет нашу настраиваемую боковую панель. Содержимое боковой панели полностью зависит от вас, но я приведу несколько примеров, в том числе то, как подключить внутри него метаполе записи.

Настройка вашего Javascript

Для этого урока я напишу ES6/ESNext Javascript с JSX, что означает, что нам нужно настроить компилятор. Если вы хотите следовать и не писать ES5 Javascript, вам нужно настроить среду разработки, которая компилирует ваш Javascript по ходу дела. Если вы не знакомы с этим, следуйте моему сообщению, объясняющему, как это настроить, а затем возвращайтесь сюда.

Я настроил свой webpack.config.jsдля компиляции исходного файла Javascript в папку моей темы /assets/js/sidebar-plugin.js. Этот скомпилированный файл — это то, что нам нужно поставить в очередь редактору Gutenberg. Пока я пишу этот код, я запустил компилятор времени выполнения, который перекомпилирует Javascript каждый раз, когда я сохраняю изменения в исходном коде (npm run start). Все это подробно объясняется в ранее упомянутом руководстве.

Я пишу это в теме, но это работает так же в плагине. Только не забудьте настроить пути при добавлении скрипта в редактор.

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

Чтобы добавить наш скрипт в редактор Gutenberg, нам нужно написать PHP. Если вы находитесь в теме, functions.phpэто хорошее место для начала или где-то в ваших файлах плагинов. Обратите внимание, что нам нужно добавить окончательный скомпилированный скрипт, а не исходный код. В моем примере скомпилированный Javascript находится в папке моей темы /assets/js/sidebar-plugin.js.

Мы создаем функцию, привязанную к enqueue_block_editor_assets. Внутри делаем как обычно [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). В качестве зависимостей к скрипту добавляем два; wp-plugins, и wp-edit-post. Эти два пакета должны быть загружены перед нашим скриптом, так как мы используем функции из них.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Поскольку мы помещаем скрипт в хук, enqueue_block_editor_assetsнаш скрипт будет загружен только тогда, когда активен редактор Гутенберга. Большой! Теперь все готово для написания нашего плагина Javascript.

Зарегистрируйте плагин Javascript

Первый шаг — регистрация плагина. Мы делаем это с помощью [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)функции в wp.plugins внутри wp.pluginsпакета.

В качестве параметра registerPlugin мы указываем имя (убедитесь, что оно уникально) и объект с настройками. Как минимум, вам нужно предоставить компонент для свойства рендеринга. Вы также можете дополнительно добавить значок из дашиконов WordPress. Имейте в виду, что если вы не укажете значок, он вернется к значку плагина. В демонстрационных целях я использую 'carrot'значок.

Что касается компонента, мы начнем с определения базового компонента, который возвращает простой div со случайным текстом внутри. И перед всем кодом мы деструктурируем функции из пакетов, которые хотим использовать.

Если ничего не происходит (даже ошибок) при обновлении Гутенберга, все готово. Мы не видим наш компонент, потому что не указали WordPress, где его отображать. Следующим шагом является подключение к пользовательскому меню боковой панели и компонентам меню инструментов для рендеринга наших материалов.

Зарегистрируйте пользовательскую боковую панель

Но сначала объяснение того, как Гутенберг обрабатывает настраиваемые боковые панели и почему нам нужно делать то, что мы будем делать. Когда мы успешно зарегистрируем пользовательскую боковую панель, сначала автоматически произойдет одна вещь. Gutenberg добавит ярлык на нашу боковую панель в верхней панели инструментов, рядом с меню «Инструменты». Это происходит потому, что наша боковая панель автоматически «закрепляется».

Проблема простого добавления пользовательской боковой панели заключается в том, что любой пользователь может «открепить» этот ярлык. Когда они это делают, у них нет точки доступа, чтобы снова открыть боковую панель! Вот почему нам нужно также добавить пункт меню в меню «Инструменты».

Регистрация пользовательской боковой панели выполняется с помощью компонента PluginSidebarиз wp.editPostпакета. Добавление пункта меню в меню «Инструменты» выполняется с помощью компонента с соответствующим названием PluginSidebarMoreMenuItem(также в wp.editPostпакете).

Для PluginSidebarкомпонента нам нужно предоставить некоторые реквизиты. Вы должны предоставить как минимум nameи title. Проп говорит titleсам за себя, это имя, которое появится в верхней части боковой панели. В реквизите укажите nameуникальный слаг. Когда вы добавляете пункт меню, вам нужно обратиться к этому слагу.

Для добавления PluginSidebarMoreMenuItemкомпонента (меню инструментов) требуется как минимум одна опора; target. Здесь вы указываете то же имя, которое вы указали в nameопоре боковой панели. В качестве содержимого компонента вы пишете текст, который будет отображаться как пункт меню. Обычно это будет то же самое, что и боковая панель title.

Поскольку React требует одного узла-обертки вокруг возврата компонента, мы обертываем все внутри Fragmentкомпонента (из wp.elementпакета). Я также упаковываю свои строки __()из wp.i18nпакета, чтобы их можно было перевести.

С приведенным выше кодом мы получим следующие две (скорее всего, три) вещи. Вы получите значок морковки на панели инструментов (если вы еще не открепили его). При нажатии на это откроется боковая панель. Вы также получите новый пункт меню на боковой панели в меню «Инструменты» под заголовком «Плагины».

Добавление контента на боковую панель

Фактическое содержание боковой панели полностью зависит от вас. Вам просто нужно добавить HTML или компоненты внутри PluginSidebarкомпонента с тем, что вы хотите (вместо текста «Привет».).

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

Добавление панелей в нашу боковую панель

Давайте быстро посмотрим, как мы можем добавить панели на нашу боковую панель. Если вы создали свои собственные типы пользовательских блоков, вы можете быть знакомы с этими компонентами. Используем PanelBodyи опционально PanelRowиз wp.componentsпакета.

Для PanelBodyкомпонента вы предоставляете как минимум реквизит title. При желании вы можете указать true или false для initialOpenреквизита, чтобы решить, следует ли расширять панель по умолчанию или нет. Поскольку содержимое внутри компонента — это все, что находится внутри панели.

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

Для примера давайте добавим две панели на нашу пользовательскую боковую панель.

С этим кодом наша пользовательская боковая панель начинает выглядеть так, как будто она принадлежит Гутенбергу!

Добавление мета-полей сообщений в настраиваемую боковую панель

Теперь мы действительно подходим к сути полезных вещей для пользовательской боковой панели; добавление настроек и сохранение их значений. Но сначала нам нужно понять, как.

Очень легко добавить поля настроек (вводы, флажки, переключаемые поля и т. д.) на боковую панель, используя готовые к использованию компоненты в пакетах WordPress. Однако нам нужно подумать о том, как хранить значения. Очевидный вариант — хранить их как метаданные поста. Но для подключения параметра к метаполю сообщения требуется дополнительный код. В частности, нам нужно использовать так называемые компоненты более высокого порядка, чтобы получать и обновлять метаданные сообщений внутри Javascript. Нам также необходимо зарегистрировать метаданные каждого сообщения с помощью PHP и сделать их доступными для REST API.

В завершение этого урока я покажу, как добавить метаданные сообщения с ключом awp_my_custom_meta, который должен храниться либо как истина, либо как ложь. На боковой панели он будет отображаться как поле переключения (составляющая true/false).

Зарегистрировать метаданные для REST API

Первым шагом к добавлению метаданных записей в наш файл Javascript является их регистрация и определение их как доступных в REST API. Для этого снова возвращаемся к PHP.

Внутри функции, связанной с initдействием, мы используем [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()функцию. В качестве параметров нам нужно определить тип объекта как ‘ post‘, потому что мы используем его как метаданные сообщения (это не исключает, например, тип сообщения страницы). Мы предоставляем мета-ключ, а затем массив аргументов. Критическая вещь, которую нужно добавить в массив аргументов, это установка ‘ show_in_rest‘ на true. Мета сообщения обычно используется как ‘ single‘ (подумайте, как вы используете get_post_meta()). Мы также определяем type. Что касается нашего случая, мы устанавливаем его на ‘ boolean‘.

С помощью этого кода awp_my_custom_metaметаполе поста доступно из Гутенберга. Вам нужно повторить register_meta()метаданные для каждого поста, который вы хотите добавить на боковую панель.

Теперь вернемся к нашему Javascript.

Добавление настройки на нашу боковую панель

Давайте начнем с простой части: добавление ввода на нашу боковую панель. Позже мы добавим больше кода, чтобы связать поле настроек с метаданными публикации. Из-за того, как нам нужно это сделать, мы определяем отдельный новый компонент для нашей настройки. Итак, внутри панели, в которую вы хотите добавить свои настройки, вы просто вызываете этот новый компонент.

Давайте назовем компонент CustomSidebarMetaComponent(вы можете назвать его как-нибудь, относящийся к вашему проекту). Внутри этого компонента мы хотим отобразить поле переключения. Для этого используем ToggleControlкомпонент из wp.componentsпакета. В качестве реквизита для ToggleControl мы предоставляем подходящую метку в titleсвойстве. ToggleControl также нужны реквизиты onChangeдля обновления значения и checkedдля текущего значения. Мы пока опустим эти два до следующего шага.

С помощью приведенного выше кода вы должны получить поле переключения на боковой панели. Он не отмечен, и при нажатии на него ничего не происходит. Это следующий шаг: подключение его к метаданным нашего поста.

Доступ к метаданным сообщений с помощью withSelect и withDispatch

Чтобы получить доступ, а также обновить мета-значение записи, нам нужно использовать компоненты высшего порядка (HOC) для доступа к версии магазинов WordPress (аналогично Redux). WordPress предоставляет нам несколько полезных HOC с функциями, которые мы можем использовать в wp.dataпакете.

Компонент более высокого порядка [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)предоставляет нашему компоненту реквизиты, которые в нашем случае извлекаются из метаданных поста. Мы используем это, чтобы получить значение метаданных нашего сообщения. Внутри withSelectмы можем использовать select('core/editor').getEditedPostAttribute('meta')для получения метаданных текущего поста.

С другой стороны, [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)это компонент более высокого порядка, который может выполнять действия. В нашем случае мы хотим обновить метаданные поста при изменении соответствующего параметра поля на нашей боковой панели. Внутри этого компонента мы используем dispatch('core/editor').editPost(), чтобы сообщить WordPress об отправке действия. Внутри объекта, который мы предоставляем, мы сообщаем WordPress, что это метаданные, которые мы хотим обновить.

Наконец, нам нужно объединить withSelectи withDispatchс нашим компонентом, который обрабатывает метаполе записи (CustomSidebarMetaComponent). Для этого мы используем WordPress composeиз wp.composeпакета. Идея в том, что withSelectи withDispatchобеспечивает наш CustomSidebarMetaComponentкомпонент реквизитом. withSelectпредоставляет значение метаданных сообщения в качестве реквизита и withDispatchпредоставляет функцию, которую мы можем вызвать для обновления значения в качестве реквизита. Мы устанавливаем эти реквизиты в ToggleField checkedи onChangeсоответственно.

Это многое объясняет. Давайте посмотрим на реальный код:

Начнем с самого начала. Который внизу. В строке #36мы меняем компонент, который мы отображаем на нашей боковой панели, на компонент, который мы создали compose(в строке #15). Компонент CustomSidebarMetaобъединит компоненты withSelectи withDispatchи вернет файл CustomSidebarMetaComponent.

У CustomSidebarMetaComponentнего будет доступ к customPostMetaValueреквизиту из withSelect, а setCustomPostMetaреквизит из withDispatchэтих двух мы используем для реквизита checkedи в .onChange``ToggleField

Обратите внимание, что в строке #5мы добавляем propsпараметры к компонентам, чтобы сделать свойства доступными в компоненте.

Заключение и заключительные слова

Я очень надеюсь, что этот урок был вам полезен. Это то, что мне удалось постичь по теме путем долгих проб и ошибок. Документации по этой теме пока практически нет. Я все еще борюсь с этим, особенно когда дело доходит до эффективной обработки нескольких мета-постов. Если мне удастся выучить несколько хороших трюков, я обязательно обновлю этот урок!

Надеюсь, следуя этому руководству, у вас должен быть код, который успешно добавляет новую пользовательскую боковую панель в редактор WordPress Gutenberg и, надеюсь, с некоторым значимым содержимым и настройками. Вот окончательный код пользовательской боковой панели с метаполем записи.