Как добавить кнопку в редактор Gutenberg с помощью @wordpress/scripts

Почти полтора года назад Антонио написал этот пост в блоге, в котором объяснил одну из трудностей, с которыми мы столкнулись при адаптации наших плагинов к новому блочному редактору WordPress. Результат его туториала выглядел примерно так:

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

Несколько недель назад Иван, один из наших читателей, оставил нам комментарий в руководстве Антонио с просьбой о помощи. Очевидно, он не смог реализовать плагин Антонио. И, если честно, меня это не удивляет, потому что в последнее время многое изменилось. Итак, чтобы помочь Ивану и всем вам, кто читает нас и хочет продолжить изучение WordPress, давайте воссоздадим руководство о том, как добавить кнопку в редактор блоков Gutenberg, используя все новые инструменты, которые предлагает нам WordPress!

Создать плагин

Первое, что мы должны сделать, это создать плагин WordPress. Это довольно просто. По сути, все, что нам нужно сделать, это создать папку в wp-content/plugins с именем, которое мы хотим дать нашему плагину (например, gutenberg-button ), и внутри нее создать файл с тем же именем и расширением .php расширение .php . Затем введите следующий код в файл плагина:

Теперь давайте подробнее рассмотрим, что делает предыдущий фрагмент:

• Сначала мы открываем <?php . Никаких сюрпризов.
• Далее в этот основной файл добавляем многострочный комментарий. Комментарий включает в себя несколько строк с парами «Ключ/Значение». Например, мы видим, как мы указываем название плагина ( Plugin Name ), его версию ( Version ) или имя автора ( Author ). Вся эта информация будет отображаться в разделе « Плагины » в WordPress.
• Наконец, мы добавляем шаблонный код:
  • мы указываем namespace (мы говорили о пространствах имен здесь),
  • мы удостоверяемся, что если файл запускается, он запускается как часть WordPress, и
  • мы определяем некоторые константы о плагине (которые будут полезны позже).

После того, как мы все это сделали, если мы перейдем на экран плагинов нашего WordPress, мы увидим, что там есть кнопка Гутенберга :

активируем его и… вуаля! Конечно, это ничего не даст, но оно уже есть.

Разработка плагина JavaScript

В настоящее время разработчики WordPress должны владеть JavaScript. Думаю, это одно из последствий того, что Гутенберг находится в ядре. И этот урок не исключение.

Подготовка среды

Если мы хотим добавить новую кнопку в интерфейс Гутенберга, мы должны закодировать эту функцию в JavaScript. Итак, давайте подготовим среду разработки JavaScript в нашем плагине. Для этого просто запустите следующую команду из командной строки (при этом убедитесь, что вы находитесь в wp-content/plugins/gutenberg-button ):

 npm init

и следуйте инструкциям:

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

Результатом этого процесса является файл package.json . Как вы вскоре увидите, этот файл будет чрезвычайно полезен в будущем.

Как я уже указал в заголовке этого поста, мы будем использовать @wordpress/scripts для создания нашего плагина. Итак, давайте добавим его как зависимость, выполнив следующую команду:

 npm install --save-dev @wordpress/scripts

Эта команда загрузит кучу зависимостей внутри нашего плагина (в node_modules ) и изменит наш package.json , чтобы было ясно, что @wordpress/scripts теперь является зависимостью разработки.

Если вы посмотрите документацию этого пакета, вы увидите, что он включает в себя множество скриптов для сборки, проверки синтаксиса, форматирования кода и т.д.:

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

поэтому давайте отредактируем наш файл package.json так, чтобы раздел "scripts" содержал все рекомендуемые команды.

Как проверить, что все работает…

Давайте создадим папку src в корне вашего проекта и добавим в нее файл index.js . Это будет основной файл JavaScript нашего плагина, и он будет содержать весь ваш код (затем вы можете организовать код по своему усмотрению, главное, чтобы основным файлом был src/index.js ).

Давайте проверим, работает ли все как положено, добавив следующий оператор index.js :

 console.log( 'Hi!' );

и сборка проекта с помощью npm run build . Это преобразует ваш код во что-то, что может запустить браузер (на самом деле это не было необходимо прямо сейчас, но это будет всего через пару минут), и сгенерирует новый скрипт внутри папки build .

Все, что нам нужно сделать сейчас, это сообщить WordPress, что этот скрипт существует, чтобы он мог его загрузить. Для этого просто откройте основной файл вашего плагина ( gutenberg-button.php ) и добавьте в конце следующие строки:

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Если вы обратите внимание, то увидите, что мы просто говорим WordPress поставить в очередь наш новый скрипт /build/index.js в качестве ресурса редактора блоков. Таким образом, когда пользователь получает доступ к редактору блоков, наш скрипт будет частью активов, которые будет включать редактор.

Итак, давайте проверим это. Перейдите на панель инструментов WordPress, отредактируйте сообщение и посмотрите на консоль JavaScript вашего браузера. Если все прошло так, как ожидалось, вы должны увидеть «Привет!» в консоли написано:

Воспроизведение нашего руководства по добавлению кнопки в Гутенберг

Хорошо, теперь, когда мы увидели, что можем писать код JavaScript, а npm run build его во что-то, что наши браузеры поймут, пришло время воспроизвести руководство Антонио. А это, дорогой читатель, предельно просто.

Откройте файл src/index.js и замените предыдущий оператор console.log следующим:

Как видите, это почти тот же код, который Антонио написал несколько месяцев назад. Основное отличие заключается в том, что мы больше не используем глобальную переменную wp для доступа к функциям и компонентам Гутенберга; вместо этого мы теперь полагаемся на операторы import . Но кроме этого, это почти то же самое.

После того, как вы написали код, просто npm run build , соберите его, и все! Теперь у вас есть кнопка в Гутенберге:

Давайте убедимся, что это работает, выделив текст и нажав на кнопку:

и вот, мы видим, что текст снова появляется в консоли!

Последнее замечание о зависимостях…

Если вы заглянете в папку build , то увидите, что @wordpress/scripts не только создал файл index.js , но и имеет файл index.asset.php . Этот файл определяет небольшой объект с двумя свойствами:

• список зависимостей (а именно скриптов WordPress), необходимых нашему плагину
• версия сборки

Мы можем (и должны) использовать оба этих свойства при постановке скрипта в очередь в WordPress, если мы хотим убедиться, что скрипт будет работать правильно. Для этого просто вернитесь к gutenberg-button.php и измените его, как показано ниже:

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Просто загрузите объект в index.asset.php с помощью оператора include и замените список зависимостей, которые у нас были ( [] ), на фактические зависимости и используйте номер сборки в качестве версии плагина.

Выводы

Создать действительно полезные плагины для WordPress непросто. Вы должны хорошо понимать, как работает JavaScript, и быть знакомым со всеми ресурсами WordPress. Но благодаря пакету @wordpress/scripts подготовка среды разработки JavaScript и создание подключаемого модуля JavaScript, который может работать в WordPress, стали проще, чем когда-либо.

Надеюсь, вам понравился сегодняшний пост. И, как всегда, если вы застряли на каком-то этапе или у вас есть вопросы, оставьте комментарий, и мы поможем вам.

Да, и, кстати, вот ссылка на проект, готовый для загрузки и тестирования, если вы того пожелаете. Просто клонируйте проект, npm install все зависимости, npm run build его, соберите и попробуйте!

Избранное изображение Ашима Д'Сильвы на Unsplash.