Шорткод или Gutenberg-блок: что выбрать для своего плагина

Заказчик просит элемент «Цена с кнопкой» для записей и лендингов. Шорткод вы напишете в одном PHP-файле. Блок потребует Node, сборки и React. Но разница проявится через год, когда понадобится поменять вёрстку кнопки: в одном случае это правка одной функции, в другом сломаются блоки в сотне старых записей. Сравниваем три подхода для WordPress 6.x: шорткод, статический блок и динамический блок.

Три подхода и что каждый кладёт в запись

Всё решает одно: что именно попадает в post_content. Остальные различия следуют из этого.

Шорткод

В записи лежит строка со скобками, а HTML собирается при каждом показе страницы. Шорткод работает в классическом редакторе, в блоке «Шорткод» и в PHP-шаблонах через do_shortcode(). Цена: автор видит скобки, а не кнопку.

<?php
// Плагин myplugin, WordPress 6.x, PHP 8.x.
// Использование: [price_button price="1990" url="https://example.com/buy"]Купить[/price_button]
add_shortcode( 'price_button', function ( $atts, $content = null ) {
  $atts = shortcode_atts(
    array( 'price' => '', 'url' => '#' ),
    $atts,
    'price_button'
  );

  // Возвращаем строку: echo вывел бы кнопку над текстом записи.
  return sprintf(
    '<div class="price-button"><span>%s</span> <a href="%s">%s</a></div>',
    esc_html( $atts['price'] ),
    esc_url( $atts['url'] ),
    esc_html( (string) $content )
  );
} );

Статический блок

Функция save() на JS возвращает разметку, и WordPress записывает в запись готовый HTML внутри комментария с атрибутами. Плюс: контент переживает удаление плагина. Минус: при открытии записи редактор сравнивает сохранённый HTML с тем, что save() выдаёт сейчас. Поменяли вёрстку, и на старых записях в консоли появится «Block validation failed», а блок предложит себя восстановить. Лечится свойством deprecated с описанием всех прежних версий, и это отдельная работа на каждое изменение.

Динамический блок

Здесь save() возвращает null, в запись попадает только комментарий с атрибутами, а HTML снова собирает PHP. Начиная с WordPress 6.1 шаблон подключается полем render в block.json. На более старых версиях передавайте render_callback в аргументах register_block_type(). Значение apiVersion: 3 рассчитано на WordPress 6.3 и новее, для старых версий сверяйтесь с документацией.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "myplugin/price-button",
  "title": "Цена с кнопкой",
  "category": "widgets",
  "attributes": {
    "price": { "type": "string", "default": "" },
    "url": { "type": "string", "default": "" }
  },
  "editorScript": "file:./index.js",
  "render": "file:./render.php"
}

<?php
// $attributes передаёт WordPress (6.1+): сохранённые атрибуты блока.
?>
<div <?php echo get_block_wrapper_attributes(); ?>>
  <span><?php echo esc_html( $attributes['price'] ?? '' ); ?></span>
  <a href="<?php echo esc_url( $attributes['url'] ?? '' ); ?>">Купить</a>
</div>

import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Edit from './edit';

// save возвращает null: разметку отдаёт PHP.
registerBlockType( metadata.name, { edit: Edit, save: () => null } );

Компонент Edit с полями для цены и ссылки здесь не показан: его вид зависит от задачи. Блок регистрируется в PHP вызовом register_block_type() с путём к папке сборки, где лежит block.json.

Сравнение в одной таблице

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

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

Что ломается на практике

• Шорткод через echo вместо return: вывод уезжает в начало страницы, над текстом записи.
• Атрибуты шорткода читаются в нижнем регистре: [price_button Price="1"] даст ключ price.
• Атрибуты без экранирования при выводе: любой автор записи получает путь к XSS. Используйте esc_html, esc_attr, esc_url.
• Правка save() у опубликованного статического блока без deprecated.
• Тяжёлый запрос в render.php: он выполняется при каждом показе страницы, кеш нужно делать самому.
• Забытая сборка: в репозитории лежит src, а в плагин нужно доставлять и папку build.

Когда что выбирать

Критерий один: меняются ли после публикации вёрстка или данные.

• Меняются, а автору нужны поля в боковой панели: динамический блок.
• Меняются, но автор работает в классическом редакторе или нужен тот же вывод в PHP-шаблоне: шорткод.
• Не меняются и контент обязан пережить удаление плагина: статический блок.

Если шорткоды уже стоят в записях, переписывать их не обязательно. В Block API есть преобразование из шорткода в блок (transforms с типом shortcode), детали смотрите в документации.

Что делать дальше

Прежде чем выбирать, найдите в админке записи со строкой [price_button и посчитайте, сколько их. Затем на тестовой копии отключите плагин и посмотрите, что увидит читатель. Если решили делать блок, начните с генератора npx @wordpress/create-block и сверьте его параметры с документацией вашей версии.