Регистрация
Создавать собственные блоки с помощью Blockstudio очень просто. Плагин ищет папку blockstudio в активной теме. В ней регистрируются все подпапки, содержащие файл block.json с ключом blockstudio.
block.json
{
"name": "blockstudio/native",
"title": "Native Block",
"category": "text",
"icon": "star-filled",
"description": "Native Blockstudio block.",
"blockstudio": true
}
Шаблон
Пока пользовательский блок не будет зарегистрирован, так как для него не задан шаблон. Чтобы исправить это, создайте index.php в той же папке, что и файл block.json. При использовании блока его содержимое будет выводиться автоматически.
<h1>My first native block.</h1>
Условная логика
Блоки можно регистрировать по условию с помощью ключа conditions. Он поддерживает все глобальные переменные, доступные также для атрибутов.
Следующий пример регистрирует блок, только если текущий тип записи — страница:
{
"blockstudio": {
"conditions": [
[
{
"type": "postType",
"operator": "==",
"value": "page"
}
]
]
}
}
Зависимости от плагинов
Блоки могут зависеть от активных плагинов WordPress с помощью ключа pluginDependencies. Если один из перечисленных плагинов неактивен, блок пропускается при регистрации.
Зависимости указываются с помощью слагов плагинов WordPress:
{
"blockstudio": {
"pluginDependencies": [
"woocommerce",
"advanced-custom-fields"
]
}
}
Используйте объектную форму, чтобы указать требуемую версию плагина. Для ограничений версий действуют те же операторы, что и в PHPversion_compare(); если оператор не указан, версия считается равной >=.
{
"blockstudio": {
"pluginDependencies": {
"woocommerce": {
"version": ">6"
}
}
}
}
Пользовательский значок
Пользовательские значки SVG для блоков можно зарегистрировать следующим образом:
{
"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.
{
"blockstudio": {
"icon": "<div>:-)</div>"
}
}
Пользовательские пути
По умолчанию Blockstudio рекурсивно ищет блоки в папке blockstudio текущей темы или дочерней темы. Это поведение можно изменить двумя способами.
Фильтр
// 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 для любых выбранных папок:
add_action('init', function () {
Blockstudio\Build::init([
'dir' => get_template_directory() . '/client-blocks'
]);
});
Фильтрация метаданных
Метаданные можно отфильтровать перед регистрацией блока с помощью фильтра blockstudio/blocks/meta:
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
if (str_starts_with($block['name'], 'marketing')) {
$meta['icon'] = 'megaphone';
}
return $meta;
}, 10, 2);
Пример выше используется внутри библиотеки, чтобы все элементы Blockstudio имели одинаковый значок.