Как добавить метаполя поста на боковую панель документа Gutenberg
В этом посте мы рассмотрим, как добавить пользовательские мета-настройки поста на боковую панель Gutenberg на вкладке «Документ», вместо того, чтобы полагаться на добавление мета-полей традиционным (и, честно говоря, гораздо более ручным) способом.
Если вы работали с WordPress задолго до того, как появился Gutenberg, вы, вероятно, знакомы с добавлением пользовательских метаданных записей с помощью [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)()
. Эта функция позволяет вам добавлять мета-поле с вашим пользовательским содержимым внизу или сбоку при редактировании сообщения. Этот метод все еще работает, в том числе и в редакторе Гутенберга!
Однако это выглядит немного не так по сравнению с остальным содержимым боковой панели Гутенберга. И не говоря уже о том, что вам нужно будет вручную написать код ввода (флажок, ввод текста и т. д.) с помощью PHP, а также написать дополнительный код, чтобы сохранить их при обновлении сообщения. И если вы хотите, чтобы ваши мета-настройки публикации были динамическими (скажем, вы хотели скрыть поле, если не было включено какое-то другое поле), тогда вам пришлось бы вручную ставить скрипт в очередь и да, как вы уже догадались, вручную обрабатывать динамическую логику. скрывать и показывать. Теперь все это устарело и стало проще благодаря новому редактору Gutenberg на основе Javascript. Мы можем довольно легко сделать что-то вроде этого:
Процесс
Процесс выглядит следующим образом:
- Мы регистрируем каждый пользовательский мета-ключ записи, который хотим добавить в PHP, с помощью
[register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)()
, и устанавливаем его как доступный в WP REST API. Это необходимый шаг, чтобы сделать метаданные поста доступными в редакторе Гутенберга. - Мы создаем файл Javascript и помещаем его в очередь специально для редактора (только).
- Внутри файла Javascript мы регистрируем плагин,
[registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()
сообщая ему об отображении нашего компонента. - Внутри этого компонента мы можем вывести все, что нам нужно. Мы можем использовать встроенные компоненты WordPress, чтобы легко отображать различные типы настроек. А с помощью пакета данных WordPress мы можем получать и обновлять мета-значения постов сразу же по мере их изменения.
Давайте приступим прямо к делу, начав с PHP-части; регистрация метаданных поста.
Регистрация метаданных поста
Для каждого мета сообщения, которое вы хотите добавить на боковую панель Gutenberg, вам нужно будет зарегистрироваться, используя [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)()
. Это необходимо, чтобы сделать их доступными через WP REST API (который использует Гутенберг) и, таким образом, доступными в нашем Javascript.
В файле вашей темы functions.php
или каком-либо другом активном PHP-файле добавьте функцию, привязанную к хуку ‘ init
‘. Внутри функции вы повторяете a register_post_meta()
для каждой пользовательской мета-записи, которую хотите добавить. Функция принимает три аргумента; Первый параметр — это тип сообщения, для которого вы хотите зарегистрировать метаданные (устанавливается как пустая строка для всех типов сообщений). Второй параметр — это имя мета-ключа для вашего мета-файла. И третье — это массив настроек. Именно здесь мы определяем, что эта мета должна быть доступна в WP REST API, установив для ‘ show_in_rest
‘ значение true.
Например, предположим, что я хочу добавить переключатель включения/выключения и ввод текста на боковую панель редактора. Это означает, что я вызываю register_post_meta()
логический и строковый типы значений соответственно. Я также хочу ограничить эти мета-сообщения только типом сообщения «сообщение». Это будет выглядеть примерно так:
Теперь у меня есть мета-ключ поста, _my_custom_bool
и он _my_custom_text
готов и доступен в Гутенберге. Я рекомендую вам переименовать их во что-то, что имеет для вас смысл.
Регистрация нашего плагина Javascript
На следующем шаге мы добавим файл Javascript и обязательно поставим его в очередь с помощью PHP.
Имейте в виду, что я пишу код Javascript с синтаксисом ES6. Это означает, что я настроил конфигурацию webpack/Babel для компиляции моего файла в отдельный читаемый файл Javascript для браузера.
У меня есть руководство о том, как это настроить, если вы не уверены, как это работает:
Нам нужно убедиться, что WordPress загружает наш скрипт в редактор. Мы делаем это, подключая функцию enqueue_block_editor_assets
и вызывая [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)()
:
add_action( 'enqueue_block_editor_assets', function() {
wp_enqueue_script(
'awp-custom-meta-plugin',
get_template_directory_uri(). '/assets/js/gutenberg/plugin-awp-custom-postmeta.js',
[ 'wp-edit-post' ],
false,
false
);
} );
Я предполагаю, что вы знакомы с тем, как ставить сценарии в очередь, и можете заменить значения своими собственными. В качестве второго параметра я указываю путь к файлу сборки (не к исходному файлу). Чтобы наш скрипт не загружался слишком рано, я установил ‘ wp-edit-post
‘ в качестве зависимости. Это пакет, который нам нужен для обработки метаданных постов.
Теперь давайте перейдем к части Javascript.
Сначала нам нужно вызвать [registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()
и передать наш компонент для рендеринга панели на боковой панели документа Gutenberg. Эта функция доступна в wp.plugins
пакете, поэтому я разбиваю ее вверху. Мне нравится содержать свои файлы в порядке, поэтому я создаю еще один файл; «awp-custom-postmeta-fields.js», чтобы содержать отображаемый компонент и импортировать его.
Пишем наш компонент
Давайте начнем создавать базовый компонент, который ничего не делает, кроме как просто сидит в правильном месте, так что мы сначала уберем его с пути. Чтобы отобразить компонент на боковой панели документа Gutenberg, мы используем [PluginDocumentSettingPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-document-setting-panel/)
компонент. Мы можем установить такие атрибуты, как title
, icon
и className
. И все, что внутри, будет отображаться на боковой панели документа. Пока я просто вывожу текст «Привет».
С приведенным выше кодом (скомпилированным) мы получаем следующее:
Потрясающий. Однако мы хотим добавить некоторые входные данные. Но для того, чтобы связать эти входные данные с нашей пользовательской мета-метой поста, нам нужно скомпоновать наш компонент с компонентами более высокого порядка withSelect
(чтобы получить мета-значения поста) и withDispatch
(чтобы обновить мета-значения поста). Это может показаться немного сложным, если вы раньше не работали с компонентами более высокого порядка, но как только вы вникнете в это, это будет довольно просто.
Сначала нам нужно изменить наше export
утверждение. Вместо того, чтобы просто возвращать наш компонент в одиночку, нам нужно скомпоновать его с withSelect
и withDispatch
, оба в wp.data
пакете.
Внутри withSelect()
у нас есть доступ к мощной select()
функции. С помощью select()
мы можем получить мета-значения текущего поста. Мы также можем получить текущий тип записи, если захотим. Как я упоминал ранее, при регистрации метаданных сообщений мы можем ограничить метаданные сообщений определенным типом сообщений. Если мы получаем тип сообщения текущего сообщения, мы можем в нашем компоненте убедиться, что наш код отображается только в том случае, если мы находимся на правильном типе сообщения. Подробнее об этом позже.
В withDispatch()
мы можем определить функции, которые мы можем запускать в нашем компоненте. Мы создаем функцию, которая будет использоваться dispatch()
для обновления метаданных поста.
Давайте изменим export
утверждение на это:
Нам также нужно деструктурировать их из следующих пакетов в верхней части файла:
const { compose } = wp.compose;
const { withSelect, withDispatch } = wp.data;
Благодаря этому наш AWP_Custom_Plugin
компонент имеет доступ к трем новым реквизитам; postMeta
который содержит все мета-значения поста для текущего поста; postType
который содержит текущий тип сообщения; setPostMeta()
и, наконец, созданная нами функция, withDispatch()
которая будет обновлять метаданные поста.
Таким образом, в определении нашего компонента мы можем деструктурировать эти три новых реквизита;
И теперь мы можем добавить некоторые входные данные в наш рендеринг, убедившись, что они отображают текущее значение и обновляют метаданные поста в событии on change. Я зарегистрировал логическое значение и строку, поэтому в качестве примера я добавлю a ToggleControl
для переключателя и simple TextControl
для ввода текста.
Если вы не уверены во встроенных компонентах WordPress, у меня есть совершенно бесплатная электронная книга, в которой рассказывается почти о большинстве компонентов, доступных в Gutenberg, в том числе о том, какие реквизиты мы можем установить для каждого из них.
Вот пример того, как может выглядеть наш компонент:
На линии #9-10
и #16-17
мы находим критические части. Мы устанавливаем текущее значение входов postMeta.<your meta key here>
и в их событии onChange запускаем функцию setPostMeta( { <your meta key here>: ... } )
для нового обновленного значения.
Наконец, несколько слов о том, как ограничить ваш компонент определенным типом сообщений. В нашем withSelect()
мы передаем тип сообщения текущего сообщения в реквизите postType
. Все, что нам нужно сделать в нашем компоненте, — это сравнить это значение с типом записи и вернуть null, если оно не совпадает:
Вот и все! Теперь наш код должен работать. Окончательный результат должен быть примерно таким:
Окончательный код
Регистрация метаданных публикации и постановка файла Javascript в очередь:
Два файла Javascript: