跳转到正文

注册

使用 Blockstudio 组合自己的区块非常简单。插件会在当前已启用的主题中查找 blockstudio 文件夹。文件夹中所有包含带有 blockstudio 键的 block.json 文件的子文件夹都会被注册。

block.json

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

模板

目前,自定义区块尚未注册,因为它缺少模板。要解决此问题,只需在与 block.json 文件相同的文件夹中创建 index.php,使用区块时其内容就会自动渲染。

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

条件逻辑

可以使用 conditions 键有条件地注册区块。它支持所有也可用于属性的全局变量。

查看所有条件

以下示例仅在当前文章类型为页面时注册区块:

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

插件依赖项

区块可以通过 pluginDependencies 键依赖已启用的 WordPress 插件。如果列出的插件有一个未启用,则注册时会跳过该区块。

依赖项使用 WordPress 插件别名:

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

使用对象形式可要求特定插件版本。版本约束使用与 PHP 的 version_compare() 相同的运算符;未带运算符的版本会被视为 >=。

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

自定义图标

区块的自定义 SVG 图标可以按如下方式注册:

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

WordPress 不允许在其自身的 block.json icon 键中使用自定义 SVG 图标,此处仅允许 Dashicons ID。

标准 WordPress 区块

Blockstudio 还会自动注册在你的 Blockstudio 目录中找到的标准 WordPress 区块。任何没有 blockstudio 键但具有有效 name 属性的 block.json,都会通过 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 目录,即可自动注册。

WordPress 7.0 的 PHP 纯区块也同样适用:带有 autoRegister 支持的 block.json 和 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 库元素使用相同的图标。