Dennis · 2026年2月7日
Introducing Blockstudio 7
Blockstudio 7 发布了。这是该项目历史上规模最大的一次发布:整个代码库从头全面重写。每个类、每个钩子、每行代码都经过重建,致力于采用现代 PHP、WordPress 编码规范,并确保长期可维护性。
但这不只是一次重构。Blockstudio 7 引入了多项重要新功能,例如基于文件的页面和区块模式、文章元数据存储系统、SEO集成,以及为所有功能提供支持的全新 HTML到区块解析器。此外,Blockstudio 现已完全免费开源。
下面来详细了解所有新功能。
免费开源
自 2020 起,我一直在开发 Blockstudio,这些年来发布了数十个版本。用户很喜欢它,但商业化的 WordPress 区块框架始终难以找到合适的市场定位。
改变局面的是 LLM。AI 编码助手如今已经足以编写区块代码,但它们需要结构清晰、基于文件的内容来处理。WordPress 区块标记很杂乱:序列化的 HTML 注释中嵌入了 JSON 属性,还混杂着 DOM 结构。这对人类来说很难处理,对 LLM 来说更难正确生成。
Blockstudio 始终采用文件优先的方式来保持简洁:一个目录中放一个 block.json 和一个 PHP 模板。不需要数据库条目,不需要 React,也不需要构建步骤。借助 v7,这一理念得以进一步延伸。HTML到区块解析器可以让你编写纯 HTML,并自动将其转换为有效的区块标记。所有内容都保留在文件系统中。只有通过 PHP API 或 CLI 明确请求页面同步时,才会写入数据库;而同步内容由文件模板驱动。
将 Blockstudio 开源是顺理成章的下一步。LLM 训练的 Blockstudio 代码越多,生成代码的能力就越强。开放的代码库、开放的文档,以及任何工具都能读取的预构建AI 上下文文件,这正是打造最佳 AI 辅助 WordPress开发环境的方式。
完整插件现已发布在GitHub,任何人都可以使用、派生和参与贡献。无需许可证密钥,没有付费墙,也没有功能限制。
新功能
基于文件的页面
这是 7.0 中最重要的新增功能之一。现在,你可以将整个 WordPress 页面定义为文件模板;调用页面同步 API 或 CLI 时,模板会以原生区块内容的形式同步到数据库。
创建一个包含 page.json 和模板文件的文件夹:
{
"name": "about",
"title": "About Us",
"slug": "about",
"postStatus": "publish"
}
<div class="about-page">
<h1>About Us</h1>
<p>Welcome to our site.</p>
</div>
运行 wp bs pages sync,让 Blockstudio 将 HTML 解析为 WordPress 区块,并在数据库中创建或更新页面。
按键合并区块
模板同步时,用户的编辑通常会被覆盖。key 属性通过在同步期间保留用户内容解决了这个问题:
<h1 key="hero-title">Default Title</h1>
<p key="hero-description">Default description.</p>
键匹配的区块在模板更新时会保留用户编辑的内容。没有键的区块则会被完全替换。
区块绑定
除了使用键,你还可以使用 WordPress 核心的区块绑定API,将区块直接连接到文章元数据。这不是 Blockstudio 功能,而是原生 WordPress API。Blockstudio 只需将 metadata 属性传递给生成的区块标记。内容存储在元数据中,而非区块标记中,因此模板同步不会破坏用户的编辑。还可以通过 WP_Query 查询数据,并通过 REST API 使用数据。
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
Default Title
</h1>
这两种方式可以在同一个模板中使用。
编辑控制
页面支持 blockEditingMode 和 templateLock,用于控制用户可以修改的内容:
{
"name": "landing",
"title": "Landing Page",
"blockEditingMode": "contentOnly",
"templateLock": "all"
}
这样可以锁定页面结构,同时仍允许用户编辑文本和媒体。模板中的 blockEditingMode 属性可以覆盖页面级设置,应用于单个元素。
固定到文章 ID
使用 postId 将页面模板绑定到现有的 WordPress 文章,以防止页面重复,并确保模板始终更新正确的文章:
{
"name": "home",
"title": "Home",
"postId": 2
}
详情请参阅页面文档。
基于文件的区块模式
与页面类似,现在你也可以将区块模式定义为文件模板。用 HTML 编写模式,Blockstudio 会将其解析为区块标记,并注册为原生 WordPress 区块模式。它们会显示在区块插入器中,用户可以将其放置在任意位置。
{
"name": "hero-section",
"title": "Hero Section",
"categories": ["featured"],
"keywords": ["hero", "banner"]
}
<div class="hero">
<h1>Welcome</h1>
<p>Get started today.</p>
</div>
与页面不同,区块模式不会创建数据库条目。每次加载页面时,它们都会在内存中注册。请参阅区块模式文档。
HTML到区块解析器
页面和区块模式都由全新的 HTML 解析器驱动,可将标准 HTML 模板转换为 WordPress 区块标记。它会自动处理容器区块(例如组和栏)以及叶区块(例如段落和标题)。解析器采用基于 trait 的渲染器架构,可通过 blockstudio/parser/renderers 筛选器轻松扩展,以支持其他区块类型:
add_filter( 'blockstudio/parser/renderers', function ( $renderers, $parser ) {
$renderers['acme/hero'] = function ( $element, $attrs, $parser ) {
$content = $parser->get_inner_html( $element );
$html = '<div class="acme-hero">' . $content . '</div>';
return array(
'blockName' => 'acme/hero',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => $html,
'innerContent' => array( $html ),
);
};
return $renderers;
}, 10, 2 );
注册后,你就可以在任何页面或区块模式模板中使用该区块:
<block name="acme/hero" background="/hero.jpg">
<h1>Welcome to our site</h1>
</block>
存储
现在,除了区块属性之外,字段值还可以存储在文章元数据或站点选项中。这是一项重要功能:
{
"id": "subtitle",
"type": "text",
"label": "Subtitle",
"storage": {
"type": "postMeta"
}
}
将值存储在文章元数据中后,你可以:
- 使用
WP_Query和meta_query按字段值查询文章 - 在无头架构中,通过 REST API 访问字段数据
- 与其他插件(例如 SEO 工具)和缓存层共享数据
你也可以将值存储在选项表中,用于全局的站点级设置:
{
"id": "phone",
"type": "text",
"label": "Phone Number",
"storage": {
"type": "option",
"optionKey": "company_phone"
}
}
完整存储文档请参阅API。
自定义字段
现在可以在多个区块之间共享可复用的字段定义。只需定义一次字段集,即可在任何区块中引用。这样,当多个区块使用相同的字段结构时,就不必重复定义。
在你的 blockstudio 目录中创建一个 field.json:
{
"name": "hero",
"title": "Hero Section",
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Hello World" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
然后使用 custom/ 前缀,在任意区块中引用它:
{
"blockstudio": {
"attributes": [
{ "type": "custom/hero", "idStructure": "hero_{id}" }
]
}
}
idStructure 属性会为每个字段 ID 添加前缀,因此 heading 会变为 hero_heading。你也可以使用 overrides 键按实例覆盖单个字段属性。
请参阅自定义字段文档。
Tailwind CSS v4
Tailwind 支持已针对 v4 全面重建。以往采用 CDN 在客户端编译,并在文章保存时写入磁盘(即 v6 方式);Blockstudio 7 则会在每次前端请求时,通过 TailwindPHP 在服务器端编译 Tailwind。无需 Node.js,无需 CLI,也无需构建步骤。
编译采用基于候选项的缓存:Blockstudio 从最终的 HTML 中提取所有 CSS 类名,将它们排序并与 CSS 配置一起计算哈希,然后检查缓存文件。即使外围的 HTML 发生变化(例如 nonce、时间戳、动态内容),相同的类仍会命中同一缓存。
配置使用 Tailwind v4 的 CSS 优先语法。可直接在 blockstudio.json 中定义自定义主题和实用类,也可以通过 blockstudio/tailwind/css 筛选器定义:
add_filter('blockstudio/tailwind/css', function ($css) {
return $css . '
@theme {
--color-brand: #4f46e5;
}
@layer utilities {
.container-narrow {
max-width: 48rem;
margin-inline: auto;
}
}
';
});
在区块编辑器中,内置的 Tailwind CDN 脚本会在输入时提供实时预览。classes 字段类型可为所有 Tailwind 实用类提供自动补全。前端始终使用服务器编译的 CSS,并将其作为内联样式标签注入到 </head> 之前。
完整设置说明请参阅Tailwind 文档。
交互性 API
Blockstudio 现已支持WordPress 交互性 API。在你的 block.json 中启用:
{
"blockstudio": {
"interactivity": true
}
}
向模板添加 data-wp-* 指令:
<div useBlockProps
data-wp-interactive="myBlock"
data-wp-context='{ "isOpen": false }'>
<button data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen">
Toggle
</button>
<div data-wp-bind--hidden="!context.isOpen">
This content is toggled by the button.
</div>
</div>
然后创建一个 script.js,编写存储逻辑:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Blockstudio 会在前端和区块编辑器中处理导入映射表、模块加载和指令处理。仅使用声明式指令和 data-wp-context(例如 data-wp-bind--hidden 或 data-wp-text)的区块完全不需要 JavaScript。前端也支持通过 wp_interactivity_state() 使用服务器端状态。
完整设置说明请参阅交互性文档。
SEO 内容分析
Blockstudio 区块是动态的,因此默认情况下,SEO 插件无法看到其中的字段内容。Blockstudio 7 通过自动集成 Yoast SEO、Rank Math 和 SEOPress 解决了这一问题。系统会提取 text、textarea、richtext、wysiwyg 和 link 字段中的文本值(包括嵌套的重复器行),并将其提供给各插件进行内容分析。现在,SEO 插件可以正确分析区块内容的关键词密度、可读性和其他指标。无需配置。
重复器默认行
重复器字段现在支持 default 属性,可为行预先填入数组。插入区块时,重复器会在编辑器和前端中填入指定的行及其值:
{
"id": "features",
"type": "repeater",
"label": "Features",
"default": [
{ "title": "Fast", "icon": "bolt" },
{ "title": "Secure", "icon": "shield" }
],
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "icon", "type": "text", "label": "Icon" }
]
}
min 属性也适用于字段级默认值:如果重复器具有 min: 3,且其内部字段设有 default 值,自动生成的行就会预先填入这些默认值,而不会留空。
改进和修复
- 带字段默认值的重复器
min:自动生成的最小行数现在会在前端和编辑器中使用字段级默认值 - Tailwind 编辑器样式:编译后的 Tailwind CSS 现在会与 CDN 一同注入区块编辑器 iframe,因此自定义
@apply规则和主题配置在编辑器中也能生效 - AI 上下文文件:
blockstudio-llm.txt已重建为静态文件,由完整的 v7 文档和去重后的 JSON 架构(约 48k tokens)汇编而成,取代了从 v6 动态生成的方式 - 代码字段弹出窗口:现在可以在独立窗口中打开代码字段,并提供独立的撤消/重做和 JavaScript 语法高亮
- Tailwind v4 服务器端编译:请参阅上文的Tailwind相关章节
- API 第 3 版:区块现在可以在 iframe 编辑器中正确渲染,包括站点编辑器和响应式预览
- 资源的点号表示法:资源后缀使用更简洁的文件命名约定(
*.inline.css、*.editor.js、*.scoped.css) - 修复了使用
useBlockProps时WP_Block_Supports中的bs_render_block()警告 - 修复了条件字段在首次加载时不遵循默认值的问题
- 修复了前端内容中的美元符号被删除的问题:
<RichText /> - 修复了
populate功能,使其适用于其他插件注册的分类法 - 修复了 WPML 上下文中的
optionsPopulate空值错误
内部实现
全面重写
这不是一次重构或代码清理。每个类都从头重写。最终代码库更加简洁、模块化,也更易于维护和扩展。
现代 PHP
Blockstudio 7 要求 PHP 8.2+,并全面使用现代类型声明。
重大变更
作为一次主要版本更新,7.0 包含多项重大变更。大多数变更都提供向后兼容的回退方案,但升级前仍应仔细查看。完整迁移指南请参阅v7迁移文档。
钩子名称现在使用 snake_case
所有 PHP 钩子都已从 camelCase 重命名为 snake_case,以符合 WordPress 核心约定:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
旧的 camelCase 名称仍然可用,但我们建议进行更新。
字段开关默认关闭
switch 属性现在默认设置为 false,而不是 true。在 v6 中,每个字段左侧边缘都有一个默认启用且不可见的切换开关。在 v7 中,开关改为默认关闭,并在字段标签中使用可见的眼睛图标。如果你依赖默认开关行为,请在字段定义中添加 "switch": true。
资源文件名使用点号表示法
资源后缀现在使用点号而非连字符(style.inline.css 而非 style-inline.css)。旧的连字符写法仍然可用,但今后建议使用点号写法。
npm 导入前缀
ES 模块导入现在使用 npm:,而不是 blockstudio/:
// Before (v6)
import confetti from "blockstudio/canvas-confetti@1.6.0";
// After (v7)
import confetti from "npm:canvas-confetti@1.6.0";
为保持向后兼容,仍支持 blockstudio/ 前缀。
已移除的功能
管理区域和代码编辑器。 WordPress 管理设置页面和内置区块代码编辑器均已移除。现在所有配置都通过 blockstudio.json 和 PHP 筛选器完成,这意味着配置会与区块一同保存在版本控制中。
早期版本中的代码编辑器可用于预览区块,但始终无法完全匹配真正的开发环境。多年来,一些插件功能一直受限,因为它们无法在独立编辑器中实现。它也不可能取代完整的 IDE。移除代码编辑器后,插件可以专注于基于文件的开发,不再受此限制。
许可证密钥。 不再需要。Blockstudio 免费开源。
区块库。 内置的“Blockstudio Elements”库(图库、滑块、图像对比、代码、图标)已移除。这些是随插件附带的预构建示例区块。如果你正在使用它们,请将区块文件夹从 v6 复制到主题的 blockstudio 目录中。
开始使用
安装 Blockstudio 7,几分钟内即可创建第一个区块。请参阅入门指南,按步骤了解操作流程;如果你要从 v6 升级,请参阅v7迁移指南。
完整源代码位于GitHub。欢迎提交问题、PR 和反馈。