Перейти до вмісту

Реєстрація

Створювати власні блоки за допомогою 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"
    ]
  }
}

Використовуйте форму об’єкта, щоб указати потрібну версію плагіна. Для обмежень версії діють ті самі оператори, що й у version_compare() PHP; версія без оператора вважається >=.

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 не потребує скрипту чи збірки й реєструється тут, як будь-який стандартний блок. Ядро обмежує цей підхід простими блоками з атрибутами типу рядок, ціле число, булеве значення та перелік. Щойно блоку знадобляться внутрішні блоки, форматований текст, медіафайли чи власні елементи керування, створіть клієнтський блок або додайте ключ 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 мали однакову піктограму.