跳转到正文

画布

画布以缩小视图呈现所有由 Blockstudio 管理的页面,提供类似 Figma 的总览。每个页面都以实时 iframe 画板形式显示在单个水平行中。用触控板平移,用双指捏合或 Ctrl+滚动缩放。

启用

画布作为隐藏的管理页面提供。导航至:

代码
/wp-admin/admin.php?page=blockstudio-canvas

只有当 dev.canvas.enabled 为 true 且当前用户具有 edit_posts 权限时,才能访问该页面。

设置

在主题的 blockstudio.json 中启用画布并配置其行为:

JSON
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
属性 类型 默认值 描述
enabled boolean false 启用画布功能。
adminBar boolean true 在画板 iframe 内显示 WordPress 管理工具栏。设置为 false 可获得更简洁的预览。

这两项设置也可通过筛选器使用:

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');

视图

使用右上角的下拉菜单切换视图。

  • 页面:由 Blockstudio 管理的所有页面,以全宽画板形式显示在同一行中。
  • 区块:所有已注册的 Blockstudio 区块以网格布局显示,每个区块均使用默认属性值进行渲染。

公共清单和文档 API

Canvas 提供一个有版本的、与使用方无关的 PHP 契约,供需要获取相同已注册内容、而无需重新构建 Blockstudio 的发现或渲染逻辑的工具使用:

PHP
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);

当前版本可通过 Canvas::SCHEMA_VERSION 获取。清单结果包含:

  • inventory:规范化后的 pages、blocks、patterns、templates、parts,以及公共 ui 系列示例
  • order:跨类型稳定的显示顺序
  • sources:精确选中的源路径,每条记录均带有来源信息;页面记录的 source 是其稳定的源身份,而 path 是实际渲染模板路径
  • warnings 和 errors:结构化问题,而非生成的输出
  • deleted:已不存在的请求标识符
  • selection:规范化后的选择,以及该选择是否有目标

Canvas::documents() 为每条选定记录添加一份完整的渲染文档。每份文档包含其正文、组合后的 HTML、依赖闭包中的区块名称,以及精确的 CSS、JavaScript、模块、交互引导代码、打包的 UI 全局变量和 Tailwind 输出。页面文档使用语义化的 <main> 内容包装器;调用方可通过共享的渲染文档选项覆盖或禁用该包装器。每个选定页面都会在独立恢复的前端 WordPress 上下文中渲染,因此查询条件、正文类筛选器、短代码、布局、重定向和 wp_enqueue_scripts 回调都会针对该页面执行,而不是针对管理界面或发起 Canvas 结果请求的 REST 请求执行。调用方提供的正文类会与页面的上下文类合并,前端入队注册表则在各文档间相互隔离。Canvas 根据公开的 WordPress 函数名称解析这些生命周期回调,因此即使通过 Composer 或迁移后的应用命名空间加载 Blockstudio,也会保留相同的上下文。

精确选择语义

选择规则严格:

  • 没有可识别的类型键时,会加载所有类型。
  • true、null 或 "*" 会加载该类型的所有记录。
  • 字符串或列表只会加载 ID、名称、别名、路径或源路径完全匹配的记录。
  • 空字符串/列表或 false 会排除该类型的所有记录。
  • 一旦出现任何类型键,就不会发现、同步、渲染或编译未指定的类型。

这使大型项目中的仅处理变更请求更加安全。现有区块和页面会通过其规范注册表解析。当某个前端请求只加载了持久化的页面投影时,Canvas 会以只读方式发现源,并合并匹配的文章 ID 和永久链接,而不进行内容同步。如果逻辑发现源先填充了基于源的注册表,也会应用相同的身份合并,因此上下文页面渲染仍会使用匹配的、由 WordPress 管理的文章。新的实时会话拓扑只会在发生变更的目录附近发现,而选定的样板和站点编辑器模板源只有在选中后才会编译。

REST 刷新端点对现有的 blocks 和 pages 查询参数遵循相同规则。例如,?blocks=theme/hero 会返回该区块而不返回页面;若要获得混合响应,请同时使用两个参数。不带任何一个参数调用该端点,则会保留完整的旧版响应。

实时模式

实时模式使用服务器发送事件(SSE)检测文件变更,并实时更新画布。编辑区块模板、页面模板或样式表时,受影响的画板会在约一秒内自动刷新。

可从下拉菜单切换实时模式。启用时会显示绿色脉动指示灯。该设置会通过 localStorage 在不同会话间保留。

实时模式会跟踪区块和页面目录中的 .php、.json、.css、.scss、.js、.twig 和 .html 文件变更。已知编辑只会刷新相应的已注册区块或页面。真正新增区块或页面时,会执行一次限定于该目录的拓扑扫描,因此即使实时会话处于打开状态,也能创建内容而无需重新扫描无关源。

专注模式

点击任意画板标签即可进入专注模式。选中的画板会以全宽填满视口,并可垂直滚动。按 Escape 或点击关闭按钮即可返回概览。

控件

操作 输入
平移 滚动 / 触控板双指拖动
缩放 Ctrl+滚动或双指捏合
适合视图 下拉菜单
缩放至 100% 下拉菜单
专注画板 点击画板标签
退出专注模式 Escape / 关闭按钮

安全

只有满足所有条件时才会加载画布脚本和页面数据:

  • dev.canvas.enabled设置为true。
  • 当前用户具有edit_posts权限。

访客永远看不到画布脚本或页面元数据。