Перейти к содержимому

Регистрация

Создавать собственные блоки с помощью Blockstudio очень просто. Плагин ищет папку blockstudio в активной теме. В ней регистрируются все подпапки, содержащие файл block.json с ключом blockstudio.

block.json

JSON
{
  "name": "blockstudio/native",
  "title": "Native Block",
  "category": "text",
  "icon": "star-filled",
  "description": "Native Blockstudio block.",
  "blockstudio": true
}

Шаблон

Пока пользовательский блок не будет зарегистрирован, так как для него не задан шаблон. Чтобы исправить это, создайте index.php в той же папке, что и файл block.json. При использовании блока его содержимое будет выводиться автоматически.

PHP
<h1>My first native block.</h1>

Условная логика

Блоки можно регистрировать по условию с помощью ключа conditions. Он поддерживает все глобальные переменные, доступные также для атрибутов.

См. все условия

Следующий пример регистрирует блок, только если текущий тип записи — страница:

JSON
{
  "blockstudio": {
    "conditions": [
      [
        {
          "type": "postType",
          "operator": "==",
          "value": "page"
        }
      ]
    ]
  }
}

Зависимости от плагинов

Блоки могут зависеть от активных плагинов WordPress с помощью ключа pluginDependencies. Если один из перечисленных плагинов неактивен, блок пропускается при регистрации.

Зависимости указываются с помощью слагов плагинов WordPress:

JSON
{
  "blockstudio": {
    "pluginDependencies": [
      "woocommerce",
      "advanced-custom-fields"
    ]
  }
}

Используйте объектную форму, чтобы указать требуемую версию плагина. Для ограничений версий действуют те же операторы, что и в PHPversion_compare(); если оператор не указан, версия считается равной >=.

JSON
{
  "blockstudio": {
    "pluginDependencies": {
      "woocommerce": {
        "version": ">6"
      }
    }
  }
}

Пользовательский значок

Пользовательские значки SVG для блоков можно зарегистрировать следующим образом:

JSON
{
  "blockstudio": {
    "icon": "<svg></svg>"
  }
}

WordPress не позволяет задавать пользовательские значки SVG в собственном ключе block.json icon — здесь разрешены только идентификаторы Dashicons.

Стандартные блоки WordPress

Blockstudio также автоматически регистрирует стандартные блоки WordPress, найденные в каталогах Blockstudio. Любой block.json без ключа blockstudio, но с допустимым свойством name регистрируется с помощью встроенного WordPress register_block_type().

Это значит, что блоки, созданные с помощью @wordpress/create-block, можно размещать прямо в папке blockstudio/. Они будут зарегистрированы автоматически вместе с блоками Blockstudio. Отдельный код регистрации плагина не нужен.

Код
blockstudio/
├── hero/
│   ├── block.json          ← Blockstudio block (has "blockstudio" key)
│   └── index.twig
├── my-js-block/
│   ├── block.json          ← Standard WP block (no "blockstudio" key)
│   ├── index.js            ← Compiled editor script
│   ├── index.css
│   ├── style-index.css
│   └── render.php

Создайте блок с помощью npx wp-scripts build, затем поместите папку с результатом в каталог Blockstudio. Блок зарегистрируется автоматически.

То же относится к блокам PHP, совместимым только с WordPress 7.0: для block.json с поддержкой autoRegister и render.php не нужны скрипты и сборка; такой блок регистрируется здесь, как и любой другой стандартный блок. Core ограничивает этот путь простыми блоками со строковыми, целочисленными, логическими атрибутами и атрибутами перечисления. Если блоку понадобятся вложенные блоки, форматированный текст, медиафайлы или пользовательские элементы управления, создайте клиентский блок или укажите для него ключ blockstudio и используйте PHP.

HTML

Blockstudio использует парсер элементов React для вывода элемента значка, поэтому в строке значка можно использовать HTML.

JSON
{
  "blockstudio": {
    "icon": "<div>:-)</div>"
  }
}

Пользовательские пути

По умолчанию Blockstudio рекурсивно ищет блоки в папке blockstudio текущей темы или дочерней темы. Это поведение можно изменить двумя способами.

Фильтр

PHP
// Custom path within your theme.
add_filter('blockstudio/path', function () {
    return get_template_directory() . '/blocks';
});

// Custom path within a plugin.
add_filter('blockstudio/path', function () {
    return WP_PLUGIN_DIR . '/my-custom-plugin/blocks';
});

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

Экземпляры

Если перечисленных выше параметров недостаточно, можно создать экземпляр класса Blockstudio\Build для любых выбранных папок:

PHP
add_action('init', function () {
  Blockstudio\Build::init([
    'dir' => get_template_directory() . '/client-blocks'
  ]);
});

Фильтрация метаданных

Метаданные можно отфильтровать перед регистрацией блока с помощью фильтра blockstudio/blocks/meta:

PHP
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
    if (str_starts_with($block['name'], 'marketing')) {
        $meta['icon'] = 'megaphone';
    }
    return $meta;
}, 10, 2);

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