画布
画布以缩小视图呈现所有由 Blockstudio 管理的页面,提供类似 Figma 的总览。每个页面都以实时 iframe 画板形式显示在单个水平行中。用触控板平移,用双指捏合或 Ctrl+滚动缩放。
启用
画布作为隐藏的管理页面提供。导航至:
/wp-admin/admin.php?page=blockstudio-canvas
只有当 dev.canvas.enabled 为 true 且当前用户具有 edit_posts 权限时,才能访问该页面。
设置
在主题的 blockstudio.json 中启用画布并配置其行为:
{
"dev": {
"canvas": {
"enabled": true,
"adminBar": false
}
}
}
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
enabled |
boolean |
false |
启用画布功能。 |
adminBar |
boolean |
true |
在画板 iframe 内显示 WordPress 管理工具栏。设置为 false 可获得更简洁的预览。 |
这两项设置也可通过筛选器使用:
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 的发现或渲染逻辑的工具使用:
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权限。
访客永远看不到画布脚本或页面元数据。