跳转到正文

迁移到 v7

本指南介绍从 Blockstudio 6 升级到 7 时需要进行的更改。

ES 模块导入

Blockstudio 7 为 ES 模块导入引入了新的 npm: 前缀,与 Deno 的 npm 说明符惯例保持一致。

之前(v6):

JavaScript
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):

JavaScript
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):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

之后(v7):

JavaScript
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 名称。

迁移示例:

PHP
// 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"] 的项目:

HTML
<!-- 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 中的默认开关行为,则需要明确启用它:

JSON
{
  "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 时,每个前端请求都会在服务器端编译。编译流程如下:

  1. WordPress 将完整页面渲染到 HTML 输出缓冲区
  2. 从 HTML 中提取 CSS 类候选项(快速正则表达式,无需编译)
  3. 使用 CSS 配置对候选项排序并生成哈希值,以创建缓存键
  4. 命中缓存时:读取缓存的 CSS 文件并将其注入
  5. 未命中缓存时:TailwindPHP 编译 CSS,将其写入 tailwind 作用域下 Blockstudio 的共享运行时缓存,并将其注入

编译后的 CSS 会作为内联 <style id="blockstudio-tailwind"> 标签注入到 </head> 之前。其中包括 Tailwind 的预检样式和所有匹配的实用类。

CDN 脚本仍会在编辑器中运行,仅用于实时预览。它绝不会在前端加载。

config 格式更改

config 属性已从 JSON 对象(Tailwind v3)改为 CSS 字符串(Tailwind v4 CSS 优先语法)。

之前(v6):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

之后(v7):

JSON
{
  "tailwind": {
    "config": "@theme { --color-primary: pink; }"
  }
}

customClasses 设置已移除

customClasses 数组设置已移除。采用 Tailwind v4 的 CSS 优先方案后,自定义实用类可通过 @layer utilities 直接定义在 config 字符串中。

之前(v6):

JSON
{
  "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):

JSON
{
  "tailwind": {
    "config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
  }
}

多行配置也可以通过过滤器添加:

PHP
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 文件。