迁移到 v7
本指南介绍从 Blockstudio 6 升级到 7 时需要进行的更改。
ES 模块导入
新的 npm: 前缀(推荐)
Blockstudio 7 为 ES 模块导入引入了新的 npm: 前缀,与 Deno 的 npm 说明符惯例保持一致。
之前(v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
之后(v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
CSS 导入
同样的更改也适用于 CSS 导入:
之前(v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
之后(v7):
import "npm:swiper@11.0.0/swiper.min.css";
向后兼容性
blockstudio/ 前缀仍受支持,以保持向后兼容。现有代码无需更改即可继续运行。不过,为与更广泛的 JavaScript 生态系统保持一致,我们建议迁移到 npm: 前缀。
npm: 前缀具有以下优势:
- 生态系统一致性 – 符合 Deno 已确立的惯例
- 清晰明了 – 一眼就能看出你是从 npm 导入
- 面向未来 –
blockstudio/前缀可能会在未来的主版本中弃用
Hook 名称
Blockstudio 7 将所有 PHP hook 名称统一为使用 snake_case,而不是 camelCase,与 WordPress 核心惯例保持一致。
更改后的 Hook 名称
| 旧名称(v6) | 新名称(v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
向后兼容性
旧的 camelCase hook 名称仍受支持,以保持向后兼容。现有代码无需更改即可继续运行。不过,为保持一致,我们建议迁移到新的 snake_case 名称。
迁移示例:
// 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'];
});
规范区块标签
Blockstudio 7.6 仍将项目前缀和精确别名作为运行时扩展点,但在示例、目录输出、渲染声明和诊断信息中使用 <bs:namespace-slug> 作为规范写法。规范标签包含实际注册的区块名称,且不依赖特定宿主的过滤器。
对于使用 brand => ["theme-components"] 和 ui => ["bsui"] 的项目:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
独立的迁移命令会盘点现有项目,并将简写改写为规范写法。它会先生成报告,遇到未解决的情况时会停止,并且只会更改标签名称。有关该命令、输入和安全行为,请参阅区块标签迁移。
资源文件命名
Blockstudio 7 引入了资源文件后缀的点号写法,取代旧的连字符写法,作为推荐惯例。
更改后的文件名
| 旧名称(v6) | 新名称(v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
向后兼容性
旧的连字符写法仍受支持,以保持向后兼容。现有文件无需重命名即可继续使用。不过,我们建议新建区块时改用点号写法。
迁移示例:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
字段开关
switch 属性现在默认值为 false,而不是 true。在 v6 中,每个字段左侧都有一个默认启用的隐藏切换开关。在 v7 中,开关需选择启用,并会在字段标签中显示一个可见的眼睛图标。
更改内容
- 现在默认关闭
false:除非明确设置"switch": true,否则字段不会带有开关 - 可见的眼睛图标:标签区域会显示眼睛图标按钮,取代隐藏的左侧点击区域
- 禁用遮罩层:字段禁用时,会显示带有“此字段已禁用”文字的模糊遮罩层,而不只是降低不透明度
迁移
如果你依赖 v6 中的默认开关行为,则需要明确启用它:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
如果你之前将 "switch": false 设为禁用切换开关,现在可以移除该设置,因为 false 现已是默认值。
Tailwind CSS
Blockstudio 7 完全取代了 v6 Tailwind 方案。在 v6 中,Tailwind CSS 由编辑器中的 CDN 在客户端编译,并在文章保存时写入磁盘。在 v7 中,Tailwind CSS 会在每次前端请求时通过 TailwindPHP 在服务器端编译,并自动使用基于文件的缓存。
有关新系统的完整详情,请参阅Tailwind CSS文档。
始终启用服务器端编译
当 tailwind.enabled 为 true 时,每个前端请求都会在服务器端编译。编译流程如下:
- WordPress 将完整页面渲染到 HTML 输出缓冲区
- 从 HTML 中提取 CSS 类候选项(快速正则表达式,无需编译)
- 使用 CSS 配置对候选项排序并生成哈希值,以创建缓存键
- 命中缓存时:读取缓存的 CSS 文件并将其注入
- 未命中缓存时:TailwindPHP 编译 CSS,将其写入
tailwind作用域下 Blockstudio 的共享运行时缓存,并将其注入
编译后的 CSS 会作为内联 <style id="blockstudio-tailwind"> 标签注入到 </head> 之前。其中包括 Tailwind 的预检样式和所有匹配的实用类。
CDN 脚本仍会在编辑器中运行,仅用于实时预览。它绝不会在前端加载。
config 格式更改
config 属性已从 JSON 对象(Tailwind v3)改为 CSS 字符串(Tailwind v4 CSS 优先语法)。
之前(v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
之后(v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
customClasses 设置已移除
customClasses 数组设置已移除。采用 Tailwind v4 的 CSS 优先方案后,自定义实用类可通过 @layer utilities 直接定义在 config 字符串中。
之前(v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
之后(v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
多行配置也可以通过过滤器添加:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
blockstudio/settings/tailwind/custom_classes 过滤器也已移除。请改用 blockstudio/tailwind/css 过滤器来追加自定义 CSS 规则。
REST 端点已移除
POST /blockstudio/v1/editor/tailwind/save 端点已移除。编辑器不再保存编译后的 CSS。如果你的自定义代码调用了此端点,可以安全地将其移除。
缓存
Blockstudio 使用基于候选项的缓存策略。它不会对整个页面 HTML 进行哈希处理(因为 nonce 和时间戳会导致每次请求都使缓存失效),而只对 CSS 类候选项进行哈希处理。这意味着:
- 两个使用相同 CSS 类的页面会共用同一个缓存文件
- 动态内容(nonce、管理栏、时间戳)不会导致缓存失效
- 只有 CSS 类集合或配置更改时,缓存才会失效
缓存文件使用配置的 Blockstudio 运行时根目录,位于
sites/{network-blog}/{runtime-identity}/tailwind/。调用
Blockstudio\Runtime_Cache::purge('tailwind') 可强制重新编译。
过滤器更改
| 旧名称(v6) | 新名称(v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
已移除 |
blockstudio/settings/tailwind/custom_classes |
已移除 |
已移除的文件和加载项
在 v6 中,Tailwind CSS 作为外部样式表(blockstudio-tailwind、blockstudio-tailwind-preflight)加载。在 v7 中,所有 CSS 都通过输出缓冲区以内联方式注入。前端不会为 Tailwind 添加链接标签或加载样式表。
区块库
内置的“Blockstudio Elements”库已移除。blockstudio.json 中的 library 设置和 blockstudio/settings/library 过滤器均不再起作用。
如果你使用了该库中的区块(图库、滑块、图像对比、代码、图标),请将区块文件夹从 v6 安装目录的 includes/library/blockstudio-element/ 目录复制到主题的 blockstudio 目录,并使用新名称和分类更新其中的 block.json 文件。