跳转到正文

Dennis · 2026年10月14日

Blockstudio 7.7

Blockstudio 7.7 为没有 WordPress 文章的文档添加虚拟路由,改进定向预渲染构建,并提高现有区块的编辑与渲染可靠性。它还扩展了 PHPStan 的区块标签检查,并改善了捆绑的 UI 组件的无障碍支持。

以文件为先的工作流保持不变。区块从其模板渲染,基于文件的页面通过显式的 CLI 或 API 同步来更改。本次发布不会在访客或管理请求时引入页面自动同步。

简而言之:

  • 虚拟路由:提供组件库、目录或其他完整文档,无需创建文章或编写自定义重定向处理程序。
  • 定向预渲染构建:HTTP 构建会记录每个页面使用的源文件,因此后续构建只需渲染受影响的路由。
  • 缓存保留:为缓存页面继续提供已停用的样式表,并检查或清理未使用的早期服务映射条目。
  • 编辑器可靠性:多选区块会保留各自的值;RichText 和侧边栏字段支持撤销与重做;继承的上下文会保留在正确的区块中。
  • 文件内容保真度:嵌套列表、分节元素、内联 HTML、短代码和转义属性在解析与渲染时都会保留。
  • PHPStan 改进:前缀标签、别名、映射的页面元素和模板变量都会根据项目自身的定义进行检查。
  • 无障碍的 UI:控件会正确呈现其状态,标签会切换对应的输入控件,列表和表格组件会使用有效的 HTML 结构。
  • 翻译:已安装的 JavaScript 翻译会在编辑器和管理概览中加载,包括此前未翻译的字段控件。

虚拟路由

有些页面来自数据,而不是由编辑器管理的文章。例如,组件参考页面可能需要自己的 URL 和文档标题,但不需要在 wp_posts 中创建条目。

使用 Blockstudio\Virtual_Routes 注册该文档:

PHP
add_action('init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function () {
            get_header();
            echo bs_block([
                'name' => 'mytheme/card',
                'data' => ['heading' => 'Example card'],
            ]);
            get_footer();
        },
        ['title' => 'Component gallery']
    );
});

该路由会提供 /components/。其回调在 Blockstudio 的输出缓冲区中运行,因此渲染的区块会通过常规流水线获得其样式、脚本、捆绑的 UI 资源以及 Tailwind 输出。WordPress 不会将匹配的路由转换为 404,也不会将其重定向到文章。

对于一组 URL,将 prefix 设置为 true 并提供一个 match 回调。回调会接收路由下的路径,并返回渲染器所需的值。返回 null 或 false 时,请求会交由 WordPress 处理。使用 urls 列出静态预渲染构建应包含的路径。单个非前缀路由默认会包含自身路径。

Virtual_Routes::urls() 会返回绝对 URL,供用于生成站点地图的集成使用。它不会自动将虚拟文档添加到 WordPress 的文章站点地图中。

完整的 虚拟路由及其 API 和选项请参阅此处。

更精准的预渲染构建

现在,针对 HTTP 执行的图模式构建会记录每条路由使用的文件:WordPress 模板、渲染的区块模板和资源、文件页面定义与布局,以及通过 blockstudio/render/dependencies 添加的依赖项。

在下一次构建时,build_plan() 会比较这些依赖项。更改区块模板会标记其依赖路由以供重新渲染,无需重建所有不相关的页面。共享配置更改仍会影响整个构建;新路由和过期路由也仍会按原来的方式渲染。

仅存在于数据库中的更改不属于文件依赖项。部署若要获取某个选项、文章或其他数据库值,必须强制构建,或显式渲染受影响的 URL。

本次发布还修复了首次渲染期间构建标识发生变化、过时的操作码缓存早期服务映射,以及仅仅因为路径包含 search 或 preview 而被排除的有效 URL。使用 Accept: text/markdown 的 Markdown 请求会绕过缓存的 HTML,相关响应会发送 Vary: Accept。

静态预渲染现在会在决定是否挂接钩子时,遵循活动主题注册的筛选器。主题可以禁用此功能,不会因为更早的设置查询而使其保持启用状态。

请参阅静态预渲染。

缓存保留与维护

缓存的 HTML 页面可能比编译其样式表的运行时标识存续更久。清理首次发现某个命名空间已停用后,cache.namespaceGrace 会控制该命名空间继续保留多久:

JSON
{
  "cache": {
    "namespaceGrace": 777600
  }
}

此示例会将已停用的文件保留九天。默认值为一天。当前活动的命名空间和提供已部署预渲染产物的命名空间,不会被停用清理删除。

早期服务映射也提供检查和清理命令:

命令行
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune

这些命令会报告并移除已删除站点或目录缺失的条目。删除多站点中的某个站点也会移除其条目。缺失的路由文档会单独报告,不会导致整个有效站点条目被移除。

请参阅缓存了解保留期限,并参阅映射维护了解相关命令。

更可靠的编辑器

现在,编辑多选区块时只会更新该区块。保存时,每个区块都会保留自己的内容、键、元数据和锁定状态,而不会在所选区块之间复制属性。

RichText 值直接存储在区块属性中,因此 Gutenberg 可以将其纳入撤销和重做。侧边栏字段也会参与同一历史记录。InnerBlocks templateLock="false" 会以真正的布尔值传入,即使外层区域已锁定,也能解锁内容。

首次预加载会收到正在编辑的文章 ID 和类型,因此模板在首次渲染时就能读取正确的元数据。预加载和渲染缓存会为不同父级下的相同子区块分别保留继承的上下文。首次请求期间属性或上下文的更改,不再会导致预览内容滞后。

Blockstudio 还会停止在区块根元素之间插入隐藏的渲染标记元素。像 .card + .card 这样的相邻兄弟选择器,现在会在编辑器中看到与前端相同的元素关系;编辑器预览和插入器预览的渲染仍彼此分开。

更安全的全站选项存储

由选项支持的字段仍会提供全站值,但保存文章时不再盲目写入这些字段的所有已保存副本:

  • 草稿、待审、私密和定时发布的保存不会写入实时站点选项。
  • 已发布文章的保存会写入本次编辑中提供且已更改的字段。
  • 只修改标题并保存旧副本,不会回退较新的全站值。
  • 缺失字段和已移除的区块不会删除现有选项。
  • 显式的 null 会移除选项。空字符串、false、零和空数组仍是有效值。

升级时首先需要检查这一主要行为变化。如果某个集成曾使用私密文章或草稿更新实时选项,请显式写入该选项,或改用已发布的配置文章。文章元数据存储不受仅限已发布文章这一限制的影响。

完整的保存规则请参阅存储。

文件内容保持完整

HTML到区块的流水线会保留更多你编写的结构:

  • 嵌套列表会变成其父列表项的内部列表区块。列表和列表项的类名会保留;普通的平面列表仍保持原有输出。
  • main、header、footer、article 和 aside 会变成群组区块,保留其元素,而不再变成绕过区块渲染的原始 HTML。
  • 映射的富文本段落会保留内联标记;仅含图像的段落会解析为映射的图像区块;短代码标签会保留其内容。
  • 转义属性会被解码并且只转义一次,包括 InnerBlocks、RichText 和 useBlockProps 元素上的属性。
  • 带引号的自闭合标签属性中的大于号现在可被接受。
  • 如果区块没有将全局 HTML 属性声明为字段,这些属性也会传递到 Blockstudio 区块的根元素。wp bs pages sync 会报告已存储但未渲染的属性。

由 Blade 提供支持的页面、样式和站点编辑器模板,现在会通过 Blockstudio\Blade_Renderer 渲染,并支持 illuminate/view 8 到 12。针对同一区块的扩展文件现在都会注册;其优先级、群组字段和目标列表均遵循文档中说明的架构。

也会追踪嵌套的 SCSS 依赖项。编辑由另一个局部模板导入的局部模板时,会更改依赖样式表的版本并触发重新编译。

PHPStan 改进

单独安装的 blockstudio/phpstan 软件包扩展了区块标签验证范围,包括前缀和别名标签、映射的页面元素、布局、捆绑的 UI 区块,以及可选的其他项目 PHP 源。命名空间解析与运行时一致,包括包含连字符的命名空间;转发的全局 HTML 属性也会被接受。

$a、$block 和 $context 等区块模板变量会被视为由 Blockstudio 定义。在 PHPStan 2.3 下,字段类型经过空值合并和 isset() 后仍会保留;模板自行赋值的 $a 则会保留所赋类型。

这些更改已发布在 blockstudio/phpstan 0.1.9 中。请将该软件包与插件分开更新;它要求使用 PHPStan 2.1.47 或更高版本:

命令行
composer require --dev blockstudio/phpstan:^0.1.9

有关配置和分析预设,请参阅 PHPStan。

无障碍与翻译

捆绑的 UI 触发控件会在实际按钮上公开其展开状态。复选框、开关和单选框标签会标识并切换各自的控件。面包屑、分页、导航菜单和表格不会再在列表或表格与其子项之间插入无效的包装元素。

密码切换按钮会公开其按下状态,并拥有更大的点击区域。输入控件接受 autocomplete,密码输入控件接受显式 ID 和无障碍标签。轮播视口可通过键盘聚焦,微调器和骨架屏动画会遵循减少动态效果偏好。

编辑器和管理概览会加载已安装的 JavaScript 翻译,用于 blockstudio 文本域。属性菜单和占位文本、代码弹窗操作,以及图像和文件徽章现在都可翻译。没有对应译文的字符串仍会显示为英文。

请参阅UI库和翻译设置。

文档与升级

文档新增了有关文档站点、Content Sync、Site Editor 模板、区块标签、岛屿、自定义字段类型、部署、预渲染、注册表设置、分析工具和 UI 应用界面的指南。ACF迁移指南反映了当前的 ACF 注册方式和区块绑定。

自定义填充示例现在使用受支持的单参数命名数据集筛选器。资源文档说明了前端样式表的顺序,以及如何在区块 CSS 之后加载主题覆盖样式。贡献者安装时无需注册表凭据即可使用公开的 Font Awesome 软件包。

PHP 8.2 和 WordPress 6.7 仍是最低要求。虚拟路由和新的维护命令均可使用,且无需更改现有页面集合。请查看上文的选项存储保存规则;如果使用独立的 PHPStan 软件包,请更新它;并像以前一样继续显式运行页面同步。

7.7.1 后续跟进

7.7.1 补丁让同步结果更清晰、更安全。按键合并若未更改文章,就不会再创建修订版本或更新修改时间。现有发布状态会得到保留,文件接管的标题和别名替换会在 CLI 报告中列出被锁定或已移除的页面。内容同步会标记由页面同步管理的正文,并保留现有审核副本。该补丁还会保护由 WordPress 管理的属性,避免字段 ID 冲突,并保留其他筛选器添加的编辑器类名。