Создание пользовательских блоков Гутенберга: полное руководство по разработке блоков

Многие люди жалуются на трудности, связанные с созданием блоков и приложений Gutenberg. Кривая обучения крутая, в основном из-за сложности установки и настройки среды разработки. Кроме того, твердые знания JavaScript, Node.js, React и Redux являются обязательными ингредиентами для этого довольно сложного рецепта.

Официальное руководство по редактору блоков WordPress предоставляет разработчикам огромное количество информации, но вы можете потеряться в этом море деталей.

И стоит упомянуть, что Матиас Вентура, ведущий архитектор проекта Gutenberg, сообщил в своем интервью WP Tavern:

Хотя есть люди, которые могут быстро этому научиться, для людей это все еще большой барьер. Я думаю, что в этом есть несколько слоев; документация могла бы быть на порядок лучше как в организации, так и в представлении. Я надеюсь, что мы сможем сделать намного больше там.

Имея это в виду, мы решили предоставить пошаговое руководство, призванное помочь нашим читателям начать разработку блоков Gutenberg.

Звучит интересно? Давайте погрузимся!

Предпосылки для разработки блоков Gutenberg

Для этого руководства единственными необходимыми навыками являются хорошее знание разработки плагинов WordPress и хотя бы базовое понимание HTML, CSS, JavaScript и React.

Будет ли это амбициозным проектом? Вы держите пари, что это будет!

Было непросто найти правильный компромисс между полнотой и простотой или решить, какие темы включить, а какие исключить.

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

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

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

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

Что такое блок Гутенберга?

С момента своего первого выпуска в декабре 2018 года редактор блоков был значительно улучшен во всех аспектах: более мощные API, более продвинутый пользовательский интерфейс, улучшенное удобство использования, множество новых блоков, первые реализации полного редактирования сайта и многое другое. .

Короче говоря, даже если Gutenberg все еще находится в стадии активной разработки, он прошел долгий путь — и сегодня редактор блоков является полноценным кандидатом на роль надежного, функционального конструктора страниц и сайтов.

С точки зрения разработчика, Gutenberg — это одностраничное приложение (SPA) на основе React, которое позволяет пользователям WordPress создавать, редактировать и удалять контент в WordPress. Однако это не должно наводить вас на мысль об улучшенной версии традиционного редактора контента.

Мы хотим прояснить это:

В Гутенберге контент разделен на блоки, которые представляют собой «кирпичики», которые пользователи могут использовать для создания постов и страниц или целых своих веб-сайтов.

Но что технически представляет собой блок?

Нам нравится определение WordPress:

«Блок» — это абстрактный термин, используемый для описания единиц разметки, которые, составленные вместе, формируют содержимое или макет веб-страницы. Идея сочетает в себе концепции того, что сегодня мы достигаем в WordPress с помощью шорткодов, пользовательского HTML и встраивания обнаружения в единый согласованный API и пользовательский интерфейс.

Заголовки, абзацы, столбцы, изображения, галереи и все элементы, из которых состоит интерфейс редактора, от панелей боковой панели до элементов управления панели инструментов блока, являются компонентами React.

Итак, что такое компоненты React? W3Schools предоставляет следующее определение:

Компоненты — это независимые и многократно используемые фрагменты кода. Они служат той же цели, что и функции JavaScript, но работают изолированно и возвращают HTML через функцию render() .

Хотя возможности редактирования, предоставляемые Gutenberg, являются новыми по сравнению с классическим редактором WordPress, способ, которым WordPress хранит ваши фрагменты контента в базе данных, совсем не меняется. Это потому, что Gutenberg — это приложение, которое работает в WordPress, но не меняет принцип работы CMS по своей сути.

Сообщения (включая сообщения, страницы и пользовательские типы сообщений), созданные с помощью Gutenberg, по-прежнему хранятся в таблице wp_posts , точно так же, как и в классическом редакторе.

Но в сообщении, созданном с помощью Гутенберга, вы найдете дополнительную информацию в таблице, которая представляет собой фундаментальное различие между сообщениями, созданными с помощью классического редактора, и сообщениями, созданными с помощью Гутенберга.

Эти фрагменты информации выглядят как HTML-комментарии и выполняют определенную функцию: разграничивают блоки:

Разделители блоков сообщают WordPress, какой блок должен отображаться на экране. Они также предоставляют значения для свойств блока в объекте JSON. Эти реквизиты определяют способ отображения блока на экране:

Настройка среды разработки WordPress

Настройка современной среды разработки JavaScript требует глубоких знаний передовых технологий, таких как Webpack, React и JSX, Babel, ESLint и т. д.

Запуган? Не будь! Сообщество WordPress уже пришло на помощь, предоставив мощные инструменты, которые позволяют избежать запутанного процесса ручной настройки.

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

Настройка среды разработки JavaScript для создания блоков Gutenberg — это трехэтапный процесс:

1. Установите Node.js и npm
2. Настроить среду разработки
3. Настройте плагин блокировки

Давайте начнем.

1. Установите Node.js и npm

Перед установкой среды разработки и регистрацией первого блока вам необходимо установить Node.js и диспетчер пакетов Node (npm).

Вы можете установить Node.js и npm несколькими способами. Но сначала вы можете проверить, установлено ли программное обеспечение на вашем компьютере.

Для этого запустите терминал и выполните следующую команду:

 node -v

Если результат command not found , то Node.js не установлен на вашем компьютере, и вы можете продолжить установку.

Для этой статьи мы выбрали самый простой вариант установки — Node Installer. Все, что вам нужно сделать, это загрузить версию, соответствующую вашей операционной системе, и запустить мастер установки:

После того, как вы установили Node.js, снова запустите команду node -v в своем терминале. Вы также можете запустить команду npm -v , чтобы убедиться, что у вас есть доступный пакет npm.

Теперь у вас есть следующие инструменты:

• Средство запуска пакетов npx Node.js (см. документацию). Это позволяет запускать команду npm без ее предварительной установки.
• Менеджер npm Node.js (см. документацию). Это используется для установки зависимостей и запуска скриптов.

Следующим шагом будет установка среды разработки.

2. Настройте среду разработки

Когда на вашем локальном компьютере установлены последние версии Node.js и npm, вам понадобится среда разработки для WordPress.

Вы можете использовать локальную среду разработки, такую ​​как DevKinsta, или использовать официальный инструмент WordPress. Давайте взглянем на оба варианта.

Вариант 1: Локальная среда разработки (DevKinsta)

Всего за несколько кликов вы можете установить WordPress локально с помощью DevKinsta, нашего современного локального инструмента разработки WordPress. Или вы можете выбрать другой локальный инструмент разработки, например MAMP или XAMPP:

Вариант 2: wp-env

Вы также можете выбрать официальный инструмент wp-env , который предоставляет локальную среду разработки WordPress, которую вы можете запустить прямо из командной строки. Ной Ален определяет это следующим образом:

Локальные среды WordPress теперь так же просты, как запуск одной команды. wp-env — это инструмент с нулевой конфигурацией для безболезненных локальных сред WordPress. Он предоставляет решения по параметрам, чтобы пользователи могли быстро развернуть WordPress, не теряя времени. Действительно, цель состоит в том, чтобы сделать эти среды легко доступными для всех — будь то разработчик, дизайнер, менеджер или кто-либо еще.

Если вы решите попробовать, установка wp-env потребует минимальных усилий. Просто выполните следующие действия:

Шаг 1. Подтвердите установку Docker и Node.js

Чтобы соответствовать техническим требованиям, вам сначала необходимо установить на свой компьютер Docker и Node.js. Это потому, что wp-env создает экземпляр Docker, на котором работает веб-сайт WordPress. Любые изменения, внесенные в код, немедленно отражаются в экземпляре WordPress.

Шаг 2. Установите @wordpress/env из командной строки.

Запустив Docker и Node.js на вашем компьютере, вы можете перейти к установке среды разработки WordPress.

Вы можете установить wp-env глобально или локально. Чтобы сделать это глобально, вам нужно запустить следующую команду из каталога плагинов (подробнее об этом в поле «Важно» ниже):

 npm install -g @wordpress/env

Давайте разберем это:

• npm install устанавливает пакет.
• -g , добавленный к команде, устанавливает указанный пакет глобально.
• @wordpress/env — это пакет, который вы собираетесь установить.

Чтобы убедиться, что wp-env успешно установлен, выполните следующую команду:

 wp-env --version

Вы должны увидеть текущую версию wp-env , что означает, что теперь вы можете запустить среду, используя следующую команду из папки вашего плагина:

 wp-env start

Вы можете получить доступ к панели инструментов WordPress, используя следующий адрес:

• http://локальный:8888/wp-admin/

Учетные данные по умолчанию следующие:

• Имя пользователя: admin
• Пароль: password

Настройте свой блок-плагин

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

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

Вариант 1. Настройка блочного плагина с помощью @wordpress/create-block

@wordpress/create-block — официальный инструмент нулевой конфигурации для создания блоков Гутенберга:

Create Block — это официально поддерживаемый способ создания блоков для регистрации блока для плагина WordPress. Он предлагает современную настройку сборки без настройки. Он генерирует код PHP, JS, CSS и все остальное, что вам нужно для запуска проекта.

Он во многом вдохновлен create-react-app. Большое спасибо @gaearon, всей команде Facebook и сообществу React.

Как только ваша локальная среда будет запущена, вы можете настроить начальный блок, просто запустив команду npx @wordpress/create-block , и она предоставит все файлы и папки, необходимые для создания каркаса плагина и регистрации нового блока. .

Давайте запустим тест, чтобы увидеть, как это работает.

В инструменте командной строки перейдите в каталог /wp-content/plugins/ и выполните следующую команду:

 npx @wordpress/create-block my-first-block

Когда вас попросят подтвердить, введите y , чтобы продолжить:

Процесс занимает несколько минут. По завершении вы должны получить следующий ответ:

И это все!

Теперь запустите среду разработки WordPress и перейдите на экран « Плагины » на панели управления WordPress. Новый плагин под названием «Мой первый блок» должен быть добавлен в ваш список плагинов:

При необходимости активируйте плагин, создайте новую запись в блоге, прокрутите средство вставки блоков до раздела « Виджеты » и выберите новый блок:

Теперь вернитесь к терминалу и измените текущий каталог на my-first-block :

 cd my-first-block

Затем выполните следующую команду:

 npm start

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

 npm run build

Вариант 2. Настройка блочного плагина с помощью create-guten-block

create-guten-block — это сторонний инструмент разработки для создания блоков Гутенберга:

create-guten-block — это набор инструментов разработки с нулевой конфигурацией (#0CJS) для разработки блоков WordPress Gutenberg за считанные минуты без настройки React, webpack, ES6/7/8/Next, ESLint, Babel и т. д.

Как и официальный инструмент создания create-block , create-guten-block основан на приложении create-react-app и может помочь вам без проблем создать свой первый блочный плагин.

Набор инструментов предоставляет все необходимое для создания современного плагина WordPress, включая следующее:

• Поддержка синтаксиса React, JSX и ES6.
• Процесс сборки webpack dev/production за кулисами.
• Дополнительные возможности языка помимо ES6, такие как оператор расширения объекта.
• CSS с автоматическим префиксом, поэтому вам не нужны -webkit или другие префиксы.
• Сценарий сборки для объединения JS, CSS и изображений для производства с исходными картами.
• Беспроблемные обновления для вышеперечисленных инструментов с единственной зависимостью cgb-scripts.

Обратите внимание на следующее предостережение:

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

Когда у вас есть локальный веб-сайт WordPress, запустите инструмент командной строки, перейдите в папку /wp-content/plugins вашей установки и выполните следующую команду:

 npx create-guten-block my-first-block

Вам придется подождать минуту или две, пока будет создана структура проекта и загружены зависимости:

Когда процесс завершится, вы должны увидеть следующий экран:

На следующем изображении показана структура проекта с терминалом, работающим в Visual Studio Code:

Теперь вернитесь в панель управления WordPress. На экране «Плагины» должен появиться новый элемент — это плагин « мой первый блок» :

Активируйте плагин и вернитесь в терминал. Измените текущий каталог на my-first-block , затем запустите npm start :

 cd my-first-block npm start

Вы должны получить следующий ответ:

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

 npm run build

Активируйте плагин и создайте новый пост или страницу, затем просмотрите свои блоки и выберите новый блок Gutenberg:

Для более подробного обзора или в случае ошибок обратитесь к документации, предоставленной Ахмадом Аваисом.

Прохождение строительных лесов для стартового блока

Какой бы из двух инструментов разработки — create-block или create-guten-block — вы не выбрали, теперь у вас есть каркас блока, который вы можете использовать в качестве отправной точки для создания блочного плагина.

Но что такое блочные леса?

Блок-скаффолдинг — это сокращенный термин, описывающий поддерживающую структуру каталогов, необходимую WordPress для распознавания блока. Обычно этот каталог содержит такие файлы, как index.php , index.js , style.css и другие, которые, в свою очередь, содержат такие вызовы, как register_block_type .

Мы выбрали официальный инструмент разработчика Create Block , поскольку он используется в Руководстве по редактору блоков. Но даже если вы решите использовать сторонний инструмент, такой как create-guten-block , ваш опыт не будет сильно отличаться.

С учетом сказанного давайте углубимся в инструмент create-block .

Более пристальный взгляд на инструмент разработчика Create Block

Как мы упоминали выше, Create Block — это официальный инструмент командной строки для создания блоков Gutenberg. Запуск @wordpress/create-block в вашем терминале генерирует файлы PHP, JS и SCSS и код, необходимые для регистрации нового типа блока:

 npx @wordpress/create-block [options] [slug]

• [slug] (необязательно) — используется для назначения слага блока и установки плагина.
• [options] (необязательно) — доступные опции

По умолчанию назначается шаблон ESNext. Это означает, что вы получите следующую версию JavaScript с добавлением синтаксиса JSX.

Если вы опустите имя блока, команда запустится в интерактивном режиме, что позволит вам настроить несколько параметров перед созданием файлов:

 npx @wordpress/create-block

На изображении ниже показана файловая структура плагина блока, созданного с помощью официального инструмента Create Block:

С учетом сказанного давайте пройдемся по основным файлам и папкам нашего нового блочного плагина.

Файл плагина

С помощью основного файла плагина вы регистрируете блок на сервере:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

Функция register_block_type регистрирует тип блока на сервере, используя метаданные, хранящиеся в файле block.json .

Функция принимает два параметра:

• Имя типа блока, включая пространство имен, или путь к папке, в которой находится файл block.json , или полный объект WP_Block_Type
• Массив аргументов блочного типа

В приведенном выше коде аргумент типа блока предоставляется магической константой __DIR__ . Это означает, что файл block.json находится в той же папке, что и файл плагина.

Файл package.json

Файл package.json определяет свойства и сценарии JavaScript для вашего проекта. Здесь вы можете установить зависимости вашего проекта.

Чтобы лучше понять, для чего предназначен этот файл, откройте его в своем любимом редакторе кода:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

Свойство scripts — это словарь, содержащий команды, которые запускаются в разное время жизненного цикла пакета с помощью npm run [cmd] .

В этой статье мы будем использовать следующие команды:

• npm run build — создать (сжатую) производственную сборку
• npm run start — создать (несжатую) сборку для разработки

dependencies и devDependencies — это два объекта, сопоставляющие имя пакета с версией. dependencies требуются в продакшене, тогда как devDependences нужны только для локальной разработки (подробнее).

Единственной зависимостью разработчика по умолчанию является пакет @wordpress/scripts , который определяется как «набор повторно используемых скриптов, адаптированных для разработки WordPress».

Файл block.json

Начиная с WordPress 5.8 файл метаданных block.json является каноническим способом регистрации типов блоков.

Наличие файла block.json дает несколько преимуществ, включая повышение производительности и лучшую видимость в каталоге плагинов WordPress:

С точки зрения производительности, когда темы поддерживают ленивую загрузку ресурсов, блоки, зарегистрированные с помощью block.json , будут иметь оптимизированную постановку ресурсов в очередь. Ресурсы CSS и JavaScript внешнего интерфейса, перечисленные в свойствах style или script , будут поставлены в очередь только тогда, когда блок присутствует на странице, что приведет к уменьшению размера страницы.

Запуск команды @wordpress/create-block создает следующий файл block.json :

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Вот полный список свойств по умолчанию:

• apiVersion — версия используемого блоком API (текущая версия 2)
• name — уникальный идентификатор блока, включая пространство имен
• version — текущая версия блока
• title — отображаемый заголовок для блока
• category — категория блока
• icon — ярлык Dashicon или пользовательский значок SVG
• description — краткое описание, видимое в инспекторе блоков
• supports — набор опций для управления функциями, используемыми в редакторе.
• textdomain — текстовый домен плагина
• editorScript — определение скрипта редактора
• editorStyle — определение стиля редактора
• style — предоставляет альтернативные стили для блока

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

Взгляните на следующий пример определений атрибутов:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

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

Папка src

В папке src происходит разработка. В этой папке вы найдете следующие файлы:

• index.js
• edit.js
• сохранить.js
• редактор.scss
• стиль.scss

index.js

Файл index.js — ваша отправная точка. Здесь вы импортируете зависимости и регистрируете тип блока на клиенте:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

Первый оператор импортирует функцию registerBlockType из пакета @wordpress/blocks . Следующие операторы импорта импортируют таблицу стилей вместе с функциями Edit и save .

Функция registerBlockType регистрирует компонент на клиенте. Функция принимает два параметра: пространство имени блока namespace/block-name имя блока (то же, что и зарегистрированное на сервере) и объект конфигурации блока.

Функция Edit предоставляет интерфейс блока, отображаемый в редакторе блоков, а функция save предоставляет структуру, которая будет сериализована и сохранена в базе данных (подробнее).

edit.js

В edit.js вы создадите интерфейс администратора блока:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Во-первых, он импортирует функцию __ из пакета @wordpress/i18n (этот пакет содержит JavaScript-версию функций перевода), useBlockProps React и файл editor.scss .

После этого он экспортирует компонент React (подробнее об операторах импорта и экспорта).

сохранить.js

В файле save.js мы создаем блочную структуру для сохранения в базе данных:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

редактор.scss и стиль.scss

Помимо скриптов, в папках src находятся два файла SASS. Файл editor.scss содержит стили, примененные к блоку в контексте редактора, а файл style.scss содержит стили блока для отображения во внешнем интерфейсе. Мы углубимся в эти файлы во второй части этого руководства.

node_modules и папки сборки

Папка node_modules содержит модули узлов и их зависимости. Мы не будем углубляться в пакеты узлов, так как это выходит за рамки этой статьи, но в этой статье вы можете узнать больше о том, куда npm устанавливает пакеты.

Папка build содержит файлы JS и CSS, полученные в процессе сборки. Вы можете глубже погрузиться в процесс сборки в синтаксисе ESNext и руководствах по настройке сборки JavaScript.

Проект: создание первого блока Гутенберга

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

Блок будет состоять из двух столбцов, с изображением слева и текстовым абзацем справа. Под текстом будет размещена кнопка с настраиваемой ссылкой:

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

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

• Как настроить плагин Starter Block
• block.json на работе
• Использование встроенных компонентов: компонент RichText
• Добавление элементов управления на панель инструментов блока
• Настройка боковой панели настроек блока
• Добавление и настройка внешней ссылки
• Добавление нескольких стилей блоков
• Вложение блоков с помощью компонента InnerBlocks
• Дополнительные улучшения

На старт, внимание, марш!

Как настроить плагин Starter Block

Запустите инструмент командной строки и перейдите в папку /wp-content/plugins :

Теперь выполните следующую команду:

 npx @wordpress/create-block

Эта команда создает файлы PHP, SCSS и JS для регистрации блока в интерактивном режиме, что позволяет легко добавлять необходимые данные для вашего блока. Для нашего примера мы будем использовать следующие детали:

• Слизняк блока : мой-партнерский-блок
• Внутреннее пространство имен : my-affiliate-plugin
• Отображаемый заголовок блока: Партнерский блок
• Краткое описание блока : пример блока для читателей Kinsta.
• Дашикон : деньги
• Название категории : дизайн
• Автор плагина : ваше имя
• Лицензия : –
• Ссылка на текст лицензии : –
• Текущая версия плагина : 0.1.0

Установка плагина и всех зависимостей занимает пару минут. Когда процесс завершится, вы увидите следующий ответ:

Теперь выполните следующую команду из папки /wp-content/plugins :

 cd my-affiliate-block

Наконец, из папки вашего плагина ( my-affiliate-block в нашем примере) вы можете начать разработку с помощью:

 npm start

Теперь откройте экран плагинов, чтобы найти и активировать плагин Affiliate Block :

Создайте новую публикацию, откройте средство вставки блоков и прокрутите вниз до категории « Дизайн ». Нажмите, чтобы добавить партнерский блок:

block.json на работе

Как мы упоминали ранее, регистрация блока на стороне сервера происходит в основном файле .php . Однако мы не будем определять настройки в файле .php . Вместо этого мы будем использовать файл block.json .

Итак, снова откройте block.json и внимательно посмотрите на настройки по умолчанию:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Скрипты и стили

editorScript , editorStyle и style предоставляют относительные пути к внешним и внутренним сценариям и стилям.

Вам не нужно вручную регистрировать скрипты и стили, определенные здесь, потому что они автоматически регистрируются и ставятся в очередь WordPress. Чтобы убедиться в этом, запустите инспектор браузера и откройте вкладку « Сеть »:

Как видно из изображения выше, наш скрипт index.js , находящийся в папке сборки , регулярно ставится в очередь без добавления кода PHP .

Метки пользовательского интерфейса

Свойства title и description предоставляют метки, необходимые для идентификации блока в редакторе:

Ключевые слова

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

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Локализация

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Этот код создает статический блок с простым нередактируемым текстом. Но мы можем легко изменить ситуацию:

Чтобы сделать текст редактируемым, вам придется заменить текущий <p> компонентом, который делает редактируемым входной контент. Для этого Гутенберг предоставляет встроенный компонент RichText.

Добавление встроенного компонента в ваш блок состоит из 5 шагов:

1. Импортируйте необходимые компоненты из пакета WordPress
2. Включите соответствующие элементы в свой код JSX.
3. Определите необходимые атрибуты в файле block.json
4. Определить обработчики событий
5. Сохранить данные

Шаг 1. Импортируйте необходимые компоненты из пакета WordPress.

Теперь откройте файл edit.js и измените следующий оператор import :

 import { useBlockProps } from '@wordpress/block-editor';

…к:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

Таким образом, вы импортируете функцию useBlockProps и компонент RichText из пакета @wordpress/block-editor .

useBlockProps

useBlockProps React помечает элемент-оболочку блока:

При использовании API версии 2 вы должны использовать новый хук useBlockProps в функции edit блока, чтобы пометить элемент-оболочку блока. Хук будет вставлять атрибуты и обработчики событий, необходимые для включения поведения блока. Любые атрибуты, которые вы хотите передать блочному элементу, должны быть переданы через useBlockProps а возвращаемое значение будет распространено на элемент.

Проще говоря, useBlockProps автоматически назначает атрибуты и классы элементу-оболочке (элемент p в нашем примере):

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

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

Богатый текст

Компонент RichText предоставляет редактируемый контент, позволяющий пользователям редактировать и форматировать контент.

Вы найдете компонент, задокументированный на GitHub, по адресу gutenberg/packages/block-editor/src/components/rich-text/README.md.

Шаг 2. Включите соответствующие элементы в свой код JSX

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Прокомментируем код построчно:

• tagName — имя тега редактируемого HTML-элемента.
• onChange — функция, вызываемая при изменении содержимого элемента
• allowedFormats — массив разрешенных форматов. По умолчанию разрешены все форматы
• value — строка HTML, которую нужно сделать доступной для редактирования
• placeholder — текст-заполнитель для отображения, когда элемент пуст

Шаг 3: Определите необходимые атрибуты в файле block.json

Атрибуты предоставляют информацию о данных, хранящихся в блоке, таких как расширенный контент, цвет фона, URL-адреса и т. д.

Вы можете установить произвольное количество атрибутов в объекте attributes в парах ключ/значение, где ключ — это имя атрибута, а значение — определение атрибута.

Теперь откройте файл block.json и добавьте следующие attributes :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

Атрибут content позволяет сохранить текст, набранный пользователем, в редактируемом поле:

• type указывает тип данных, хранимых атрибутом. Тип требуется, если вы не определяете свойство enum .
• source определяет, как значение атрибута извлекается из содержимого публикации. В нашем примере это HTML-контент. Обратите внимание, что если вы не укажете исходное свойство, данные будут храниться в разделителе блоков (подробнее).
• selector — это HTML-тег или любой другой селектор, например имя класса или атрибут id.

Мы передадим функции Edit объект свойств. Итак, вернитесь к файлу edit.js и внесите следующие изменения:

 export default function Edit( { attributes, setAttributes } ) { ... }

Шаг 4: Определите обработчики событий

Элемент RichText имеет атрибут onChange , предоставляющий функцию для вызова при изменении содержимого элемента.

Давайте определим эту функцию и посмотрим весь скрипт edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Теперь сохраните файл и запустите npm run start в окне терминала. Затем вернитесь в панель управления WordPress, создайте новый пост или страницу и добавьте свой партнерский блок:

Добавьте текст и переключитесь в режим просмотра кода. Вот как должен выглядеть ваш код:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Если вы сейчас сохраните страницу и проверите результат внешнего интерфейса, вы можете быть немного разочарованы, потому что ваши изменения не влияют на сайт. Это потому, что вам нужно изменить файл save.js , чтобы сохранить вводимые пользователем данные в базе данных при сохранении сообщения.

Шаг 5: Сохраните данные

Теперь откройте файл save.js и измените скрипт следующим образом:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

Вот что мы делаем здесь:

• Импортируйте компонент RichText из пакета block-editor .
• Передайте несколько свойств через аргумент объекта в функцию save (в этом примере мы передаем только свойство attributes )
• Вернуть содержимое компонента RichText

Вы можете прочитать больше о компоненте RichText в Руководстве по редактору блоков и найти полный список реквизитов на Github.

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

Добавление элементов управления на панель инструментов блока

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

Например, вы можете добавить элемент управления выравниванием текста для своего блока. Все, что вам нужно сделать, это импортировать два компонента из пакета @wordpress/block-editor .

Мы пройдем те же шаги, что и в предыдущем примере:

1. Импорт необходимых компонентов из пакетов WordPress
2. Включите соответствующие элементы в свой код JSX
3. Определите необходимые атрибуты в файле block.json
4. Определить обработчики событий
5. Сохранить данные

Шаг 1. Импортируйте компоненты BlockControls и AlignmentControl из @wordpress/block-editor.

Чтобы добавить элемент управления выравниванием на панель инструментов блока, вам понадобятся два компонента:

• BlockControls отображает динамическую панель инструментов с элементами управления (недокументировано).
• AlignmentControl отображает раскрывающееся меню, в котором отображаются параметры выравнивания для выбранного блока (подробнее)

Откройте файл edit.js и отредактируйте оператор import , как показано ниже:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Шаг 2. Добавьте элементы BlockControl и AlignmentControl.

Перейдите к функции Edit и вставьте элемент <BlockControls /> на том же уровне, что и <RichText /> . Затем добавьте и <AlignmentControl /> внутри <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

В приведенном выше коде <> и </> — это короткий синтаксис для объявления фрагментов React, с помощью которого мы возвращаем несколько элементов в React.

В этом примере AlignmentControl имеет два атрибута:

• value предоставляет текущее значение для элемента
• onChange предоставляет обработчик событий для запуска при изменении значения

Мы также определили дополнительные атрибуты для элемента RichText (см. полный список атрибутов с примерами).

Шаг 3: Определите атрибут align в block.json

Теперь перейдите в файл block.json и добавьте атрибут align :

 "align": { "type": "string", "default": "none" }

Вернитесь в терминал, остановите текущий процесс с помощью ^C и снова запустите скрипт с помощью npm run start . Затем вернитесь в редактор блоков, обновите страницу и выберите блок. Вы должны увидеть панель инструментов блока с элементом управления выравниванием:

Теперь, если вы попытаетесь отформатировать содержимое блока с помощью новых элементов управления выравниванием, вы увидите, что ничего не происходит. Это потому, что мы еще не определили обработчик события.

Шаг 4: Определите обработчики событий

Теперь определите onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Если newAlign не undefined , то мы устанавливаем для newAlign значение none . В противном случае мы используем newAlign .

Наш скрипт edit.js должен быть завершен (на данный момент):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Теперь вы можете вернуться в редактор и выровнять содержимое блока.

Нам нужно изменить функцию сохранения для хранения содержимого и атрибутов блоков в базе данных.

Шаг 5: Сохраните данные

Откройте save.js и измените функцию save следующим образом:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Наконец, чтобы сделать код более читабельным, вы можете извлечь отдельные свойства из объекта attribute , используя синтаксис деструктурирующего присваивания:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Сохраните файл, перезапустите процесс и вернитесь в редактор в режиме редактора кода. Код должен выглядеть примерно так:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

И это все! Вы только что добавили элемент управления выравниванием на панель инструментов блока.

Вы можете прочитать больше об элементах управления панели инструментов блока в Руководстве по редактору блоков.

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

Вы также можете добавить элементы управления на боковую панель настроек блока (или даже создать новую боковую панель для своего приложения).

API предоставляет для этого компонент InspectorControls .

Руководство по редактору блоков объясняет, как использовать боковую панель настроек:

Боковая панель настроек используется для отображения редко используемых настроек или настроек, которые требуют больше места на экране. Боковая панель настроек должна использоваться только для настроек на уровне блоков .

Если у вас есть настройки, которые влияют только на выделенное содержимое внутри блока (например, настройка «полужирный» для выделенного текста внутри абзаца): не размещайте его на боковой панели настроек. Боковая панель настроек отображается даже при редактировании блока в режиме HTML, поэтому она должна содержать только настройки уровня блока.

Очередной раз:

1. Импорт необходимых компонентов из пакетов WordPress
2. Включите соответствующие элементы в свой код JSX
3. Определите необходимые атрибуты в файле block.json
4. Определить обработчики событий
5. Сохранить данные

Шаг 1. Импортируйте компоненты InspectorControls и PanelColorSettings из @wordpress/block-editor.

Вы можете добавить несколько элементов управления, чтобы пользователи могли настраивать определенные аспекты блока. Например, вы можете предоставить панель управления цветом. Для этого вам потребуется импортировать компоненты InspectorControls и PanelColorSettings из модуля block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Шаг 2. Включите соответствующие элементы в свой код JSX.

Теперь вы можете добавить соответствующие элементы в JSX, возвращаемый функцией Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Обратите внимание, что мы также обновили атрибут style элемента RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Шаг 3: Определите необходимые атрибуты в block.json

Теперь определите атрибуты backgroundColor и textColor в файле block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Шаг 4: Определите обработчики событий

Теперь вам нужно определить две функции для обновления backgroundColor и textColor при вводе пользователем:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Шаг 5: Сохраните данные

Последний шаг: откройте файл save.js и измените скрипт следующим образом:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Теперь остановите процесс (^C) и снова запустите npm run start . Обновите страницу, удалите любой экземпляр вашего блока и снова добавьте его в свой пост:

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

Добавление и настройка внешней ссылки

В этом разделе вы добавите новые компоненты к вашему типу блока:

• Компонент ExternalLink , позволяющий пользователям добавлять настраиваемую ссылку в блок Affiliate.
• Несколько элементов управления боковой панели, позволяющих пользователям настраивать параметры ссылок.

Шаг 1. Импорт компонентов из @wordpress/components

Теперь вам нужно импортировать несколько компонентов из @wordpress/components . Откройте файл edit.js и добавьте следующий оператор import :

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody добавляет складной контейнер на боковую панель настроек.
• PaneRow создает универсальный контейнер для элементов управления боковой панели.
• TextControl предоставляет элемент управления вводом текста.
• ToggleControl предоставляет переключатель, позволяющий пользователям включать/отключать определенную опцию.
• ExternalLink — это простой компонент для добавления внешней ссылки.

Шаг 2. Включите соответствующие элементы в свой код JSX

Сначала вы добавите элемент ExternalLink на том же уровне RichText в контейнер div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

Компонент ExternalLink не документирован, поэтому мы обратились к самому компоненту, чтобы получить список доступных атрибутов. Здесь мы используем атрибуты href , className и rel .

По умолчанию для rel установлено значение noopener noreferrer . Наш код добавит ключевое слово nofollow к атрибуту rel результирующего a , когда переключатель включен .

Теперь вы можете добавить настройки ссылки на боковую панель блока.

Во-первых, вы добавите элемент PanelBody внутрь InspectorControls на том же уровне, что и PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Вот что мы делаем с этим:

1. Атрибут title предоставляет заголовок панели.
2. initialOpen устанавливает, открыта ли панель изначально.

Далее мы добавим два элемента PanelRow внутри PanelBody и элемент TextControl внутри каждого PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

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

Мы также добавим дополнительный PanelRow с ToggleControl для включения/выключения определенной опции, например, включать ли атрибут или нет:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Шаг 3: Определите необходимые атрибуты в block.json

Теперь определите linkLabel affiliateLink hasLinkNofollow в файле block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Здесь больше нечего добавить! Перейдем к определению функций обработки событий.

Шаг 4: Определите обработчики событий

Вернитесь к файлу edit.js и добавьте следующие функции:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Эти функции обновляют соответствующие значения атрибутов при вводе данных пользователем.

Шаг 5: Сохраните данные

Наконец, мы должны обновить функцию save в save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Обратите внимание, что здесь мы использовали обычный элемент a вместо ExternalLink :

Теперь сохраните данные и перезапустите вашу среду.

Добавление нескольких стилей блоков

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

Для этой цели мы будем использовать полезную функцию Block API: стили блоков.

Все, что вам нужно сделать, это определить свойство styles block.json и объявить соответствующие стили в ваших таблицах стилей.

Например, вы можете добавить следующий массив стилей:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

При этом вы только что добавили стиль по умолчанию и дополнительный стиль, называемый border . Теперь вернитесь в редактор блоков:

Стили будут доступны пользователю, если щелкнуть переключатель блоков, а затем найти панель « Стили» на боковой панели «Параметры блока ».

Выберите стиль и проверьте классы, применяемые к элементу p . Щелкните правой кнопкой мыши блок и выберите Inspect . Добавлен новый класс с именем, структурированным следующим образом:

 is-style-{style-name}

Если вы отметили стиль «Border», то к элементу p будет добавлен класс is-style-border . Если вы отметили стиль «По умолчанию», вместо него будет добавлен класс is-style-default .

Теперь вам нужно только объявить свойства CSS. Откройте файл editor.scss и замените текущие стили следующими:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Теперь вы можете сделать то же самое с style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Остановите процесс (^C) и снова запустите npm run start .

И это все! Обновите страницу и наслаждайтесь новыми стилями блоков:

Вложение блоков Гутенберга с помощью компонента InnerBlocks

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

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

Компонент InnerBlocks определяется следующим образом:

InnerBlocks экспортирует пару компонентов, которые можно использовать в блочных реализациях для включения содержимого вложенных блоков.

Во-первых, вам нужно создать новый файл .js в папке src . В нашем примере мы назовем этот файл container.js .

Теперь вам нужно импортировать новый ресурс в файл index.js :

 import './container';

Вернитесь в container.js и импортируйте необходимые компоненты:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

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

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

Шаблон структурирован как массив типов блоков (имя блока и необязательные атрибуты).

В приведенном выше коде мы использовали несколько атрибутов для настройки блоков Columns и Column. В частности, атрибут templateLock: 'all' блокирует блоки столбцов, чтобы пользователь не мог добавлять, изменять порядок или удалять существующие блоки. templateLock может принимать одно из следующих значений:

• all — InnerBlocks заблокирован, и никакие блоки нельзя добавлять, переупорядочивать или удалять.
• insert — Блоки можно только переупорядочивать или удалять.
• false — шаблон не заблокирован.

Затем шаблон назначается элементу InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Чтобы предотвратить проблемы с совместимостью, мы также добавили атрибут templateLock в компонент InnerBlocks (см. также проблему № 17262 и запрос № 26128).

Вот наш окончательный файл container.js :

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Дополнительные улучшения

Наш блок полностью функционален, но мы могли бы немного улучшить его, внеся небольшие изменения.

Мы присвоили атрибут backgroundColor абзацу, сгенерированному компонентом RichText . Однако мы можем предпочесть назначить цвет фона контейнеру div :

Итак, измените файл edit.js и сохраните.js div следующим образом:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Это позволит пользователю изменить фон всего блока.

С другой стороны, более важное изменение касается метода useBlockProps . В исходном коде мы определили константу blockProps следующим образом:

 const blockProps = useBlockProps();

Но мы можем использовать useBlockProps более эффективно, передавая набор свойств. Например, мы можем импортировать имена классов из модуля classnames и соответствующим образом установить имя classnames -оболочки.

В следующем примере мы назначаем имя класса на основе значения атрибута align ( edit.js ):

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Мы внесем те же изменения в файл save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

И это обертка! Теперь вы можете запустить сборку для производства.

Резюме

И вот мы в конце этого невероятного путешествия! Мы начали с настройки среды разработки и закончили созданием полного блочного типа.

Как мы упоминали во введении, глубокие знания Node.js, Webpack, Babel и React необходимы для создания расширенных блоков Gutenberg и позиционирования себя на рынке в качестве профессионального разработчика Gutenberg.

Но вам не обязательно иметь опыт работы с React, чтобы начать получать удовольствие от блочной разработки. Разработка блоков может дать вам мотивацию и цели для получения все более широких навыков в технологиях, лежащих в основе блоков Гутенберга.

Таким образом, это руководство далеко не полное. Это просто введение в широкий спектр тем, которые помогут вам начать создавать свои самые первые блоки Гутенберга.

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

• Официальное руководство по созданию блока для начинающих
• Официальное руководство по Block для разработчиков среднего уровня
• Динамические блоки
• Мета-боксы
• Создание боковой панели для вашего плагина

Если вы только начинаете разработку WordPress, возможно, вы захотите понять основные концепции разработки внешнего интерфейса. Вот краткий список ресурсов, которые могут помочь вам начать работу:

• Как установить WordPress локально (бесплатная электронная книга)
• Реальная ценность управляемого хостинга WordPress (бесплатная электронная книга)
• Что такое JavaScript?
• HTML против HTML5
• Как редактировать CSS в WordPress
• Что такое PHP?
• Учебный курс по хукам WordPress: как использовать действия, фильтры и пользовательские хуки

И помните, что полный код примеров из этого руководства доступен на Gist.

Теперь ваша очередь: разработали ли вы блоки Гутенберга? Каковы основные трудности, с которыми вы столкнулись на данный момент? Дайте нам знать о своем опыте в комментариях!