Это краткий документ, подробно описывающий, как работает поддержка мета-блоков в Гутенберге. Благодаря превосходному опыту разработчиков блоков и пользователей, особенно после того, как шаблоны блоков стали доступны, настоятельно рекомендуется переносить мета-блоки PHP на блоки!
Тестирование, преобразование и поддержка существующих мета-блоков
Перед преобразованием мета-блоков в блоки может быть проще проверить, работает ли мета-бокс с Гутенбергом, и явно пометить его как таковой.
Если мета-блок не работает в Гутенберге, и его корректная работа для корректной работы невозможна, следующим шагом будет добавление __block_editor_compatible_meta_box
аргумента в объявление мета-блока:
add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
null, 'normal', 'high',
array(
'__block_editor_compatible_meta_box' => false,
)
);
WordPress переключится на классический редактор, где мета-блок продолжит работать, как и раньше.
Явная установка __block_editor_compatible_meta_box
для true
заставит WordPress остаться в Гутенберге (предполагается , что другая мета — поле не вызывает запасной вариант).
После преобразования мета-блока в блок его можно объявить существующим для обратной совместимости:
add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
null, 'normal', 'high',
array(
'__back_compat_meta_box' => true,
)
);
Когда используется Гутенберг, этот мета-бокс больше не будет отображаться в области мета-бокса, поскольку теперь он существует только для целей обратной совместимости. Он будет правильно отображаться в редакторе Classic, если какой-то другой мета-блок вызовет откат.
При каждой загрузке страницы Гутенберга мы регистрируем действие, которое собирает данные метабокса, чтобы определить, является ли область пустой. Исходное глобальное состояние сбрасывается при сборе данных метабокса.
Увидеть lib/register.php gutenberg_trick_plugins_into_registering_meta_boxes()
gutenberg_collect_meta_box_data()
подключен позже admin_head
. Он будет проходить через функции и хуки, которые post.php
запускаются для регистрации мета-блоков; а именно add_meta_boxes
, add_meta_boxes_{$post->post_type}
и do_meta_boxes
.
Создается копия глобального объекта , который $wp_meta_boxes
затем фильтруется apply_filters( 'filter_gutenberg_meta_boxes', $_meta_boxes_copy );
, что удаляет все основные мета-блоки, стандартные пользовательские мета-блоки таксономии и любые мета-блоки, которые объявили себя существующими только в целях обратной совместимости.
Затем каждое местоположение для этого конкретного типа метабокса проверяется на предмет его активности. Если оно не пустое, значение true сохраняется, если оно пустое, сохраняется значение false. Эти данные о расположении метабокса затем отправляются в редактор Redux store в INITIALIZE_META_BOX_STATE
.
В идеале это можно сделать при создании экземпляра редактора и помочь упростить этот процесс. Тем не менее, невозможно узнать состояние метабокса до того admin_enqueue_scripts
, куда мы звоним initializeEditor()
. Это нужно будет делать, если только мы не захотим перейти initializeEditor()
к стрельбе в нижнем колонтитуле или в какой-то момент после admin_head
. С недавними изменениями в загрузчике редактора это стало возможным. Проверьте с ACF, чтобы убедиться.
Redux и React Meta Box Management
При рендеринге страницы Гутенберга мета-блоки передаются скрытому элементу div #metaboxes
.
Хранилище Redux по умолчанию будет содержать все мета-блоки как неактивные . Когда INITIALIZE_META_BOX_STATE
приходит, магазин будет обновлять любые активные области метабокса, устанавливая isActive
флаг в true
. Как только это произойдет, React проверит новые реквизиты, отправленные Redux на MetaBox
компонент. Если MetaBox
он сейчас активен, вместо рендеринга ноль, MetaBoxArea
компонент будет отрендерен. MetaBox
Компонент является компонентом , контейнера , который опосредует между MetaBoxArea
и в Redux Store. Если мета-блоки не активны, ничего не происходит. Это будет поведение по умолчанию, поскольку все основные мета-блоки были удалены.
Компонент
Когда компонент рендерится, он сохранит ссылку на контейнер мета-блоков и извлечет мета-блоки HTML из местоположения предварительной выборки.
Когда сообщение обновляется, будут отправлены только те области мета-полей, которые активны. Это предотвращает ненужные запросы. Никакие дополнительные ревизии не создаются в представлениях метабокса. Действие Redux будет активировано REQUEST_POST_UPDATE
для любого активного метабокса. См editor/effects.js
. REQUEST_META_BOX_UPDATES
Действие будет установлено состояние этого мета — приставки к isUpdating
. isUpdating
Проп будет послан в MetaBoxArea
и вызвать форму представления.
Когда область мета-поля сохраняется, мы отображаем наложение обновления, чтобы пользователи не могли изменять значения формы во время сохранения.
После того, как новый редактор блоков сделан в редакторе по умолчанию, необходимо будет предоставить флаг classic-editor для доступа к частичной странице мета-блока.
gutenberg_meta_box_save()
сохраняет изменения в метабоксе. meta_box
Параметр запроса должен присутствовать и должен соответствовать одному из 'advanced'
, 'normal'
, или 'side'
. Это значение будет определять, какая область метабокса обслуживается.
Так пример URL будет выглядеть так:
mysite.com/wp-admin/post.php?post=1&action=edit&meta_box=$location&classic-editor
Этот URL-адрес автоматически передается в React через _wpMetaBoxUrl
глобальную переменную.
Эта страница имитирует post.php
форму публикации, поэтому при ее отправке она запускает все обычные хуки и действия и имеет правильное глобальное состояние для корректного запуска любого мета-блока PHP mumbo jumbo без необходимости изменения какого-либо существующего кода. При успешной отправке React подаст сигнал handleMetaBoxReload
об удалении наложения обновления.
Распространенные проблемы совместимости
Большинство мета-блоков PHP должны продолжать работать в Гутенберге, но некоторые мета-блоки, которые включают расширенные функциональные возможности, могут сломаться. Вот несколько общих причин, почему мета-блоки могут работать не так, как ожидалось в Гутенберге:
- Плагины, основанные на селекторах, предназначенных для заголовка сообщения, полей содержимого публикации и других метабоксов (старого редактора).
- Плагины опираются на API TinyMCE, потому что в Гутенберге больше нет ни одного экземпляра TinyMCE для общения.
- Плагины, делающие обновления в своей DOM при «отправить» или «сохранить».
Также обратите внимание, что если ваш плагин вызывает предупреждение или уведомление PHP для вывода на страницу, это приведет <!DOCTYPE html>
к неправильному выводу типа документа HTML ( ). Это заставит браузер выполнять рендеринг в «режиме причуд», который является слоем совместимости, который включается, когда браузер не знает, какой тип документа он анализирует. Редактор блоков не предназначен для работы в этом режиме, но может показаться, что он работает просто отлично. Если вы столкнулись с такими проблемами, как мета-блоки, накладываемые на редактор,или с другими проблемами макета, проверьте исходный источник страницы вашего документа, чтобы убедиться, что определение типа документа — это первое, что выводится на страницу. Также будет предупреждение в консоли JavaScript, отмечающее проблему.