注册
使用 Blockstudio 组合自己的区块非常简单。插件会在当前已启用的主题中查找 blockstudio 文件夹。文件夹中所有包含带有 blockstudio 键的 block.json 文件的子文件夹都会被注册。
block.json
{
"name": "blockstudio/native",
"title": "Native Block",
"category": "text",
"icon": "star-filled",
"description": "Native Blockstudio block.",
"blockstudio": true
}
模板
目前,自定义区块尚未注册,因为它缺少模板。要解决此问题,只需在与 block.json 文件相同的文件夹中创建 index.php,使用区块时其内容就会自动渲染。
<h1>My first native block.</h1>
条件逻辑
可以使用 conditions 键有条件地注册区块。它支持所有也可用于属性的全局变量。
以下示例仅在当前文章类型为页面时注册区块:
{
"blockstudio": {
"conditions": [
[
{
"type": "postType",
"operator": "==",
"value": "page"
}
]
]
}
}
插件依赖项
区块可以通过 pluginDependencies 键依赖已启用的 WordPress 插件。如果列出的插件有一个未启用,则注册时会跳过该区块。
依赖项使用 WordPress 插件别名:
{
"blockstudio": {
"pluginDependencies": [
"woocommerce",
"advanced-custom-fields"
]
}
}
使用对象形式可要求特定插件版本。版本约束使用与 PHP 的 version_compare() 相同的运算符;未带运算符的版本会被视为 >=。
{
"blockstudio": {
"pluginDependencies": {
"woocommerce": {
"version": ">6"
}
}
}
}
自定义图标
区块的自定义 SVG 图标可以按如下方式注册:
{
"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。
{
"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 库元素使用相同的图标。