逻辑发现源
Blockstudio通常会从物理主题目录中发现文件。运行时工具可以用逻辑清单替代这些目录。这适用于预览、叠加层、生成的主题、远程挂载,以及相关文件并不共享同一个物理根目录的其他环境。
Blockstudio仍会解析并注册区块、页面、集合、样板、字段、模板和模板部件。源仅决定哪些逻辑文件可见,以及每个可见文件的读取位置。
清单源
使用blockstudio/discovery/sources过滤器替换默认的Filesystem_Discovery_Source对象:
use Blockstudio\Inventory_Discovery_Source;
add_filter(
'blockstudio/discovery/sources',
function (array $sources, string $context, array $paths): array {
if ('blocks' !== $context) {
return $sources;
}
return [
new Inventory_Discovery_Source(
'preview:feature-card',
'/runtime-preview/feature-card/blockstudio',
[
'card/block.json' => [
'path' => '/theme/blockstudio/card/block.json',
'provenance' => [
'layer' => 'parent',
'inherited' => true,
],
],
'card/index.php' => [
'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
'provenance' => [
'layer' => 'preview',
],
],
],
'parent-and-preview-fingerprint',
['/theme/blockstudio', '/runtime-preview/feature-card/blockstudio']
),
];
},
10,
3
);
可用的上下文如下:
blocksfieldspagespatternssite-templatessite-template-parts
清单是最终可见的树结构。返回之前请先组合各层:
- 每个可见的逻辑路径使用一个条目。
- 由所选层提供物理路径。
- 省略已删除的逻辑路径。
- 条目顺序任意。Blockstudio会按逻辑路径排序。
- 当目录可见性很重要时,可在构造函数的可选第六个参数中包含空逻辑目录。
Inventory_Discovery_Source适用于基于数组的清单。
如果条目需要延迟解析,或来自其他存储系统,集成可以实现Discovery_Source接口。
同级解析
逻辑同级文件可以解析到不同的物理根目录。父级block.json可以使用叠加层index.php,叠加页面也可以继承其父级的pages.json、加载器或布局。Blockstudio会先按逻辑路径解析这些关系,再读取所选的物理文件。
集合外部的加载器路径仍受现有的blockstudio/pages/allow_external_loader_path安全边界保护。
标识和失效
每个源都会提供:
- 所选运行时的稳定源 ID。
- 会随可见清单变化的指纹。
- 用于热重载和缓存验证的物理监视输入。
- 每个条目的来源信息和元数据。
Blockstudio会将源 ID 和指纹纳入运行时、页面清单、站点编辑器模板、画布和Tailwind缓存标识中。
当相同的源选择可能在多个运行时变体下渲染时,请使用blockstudio/cache/context:
add_filter(
'blockstudio/cache/context',
fn ($context, string $scope) => [
'preview' => 'feature-card',
'site' => get_current_blog_id(),
],
10,
2
);
上下文值必须可序列化,并且对于等效请求保持稳定。Tailwind会将最近一次可用的CSS保存在特定上下文的命名空间中,因此一个预览不会收到另一个预览的备用CSS。
生成的资源
在来源信息或元数据中,使用inherited: true、readOnly: true或writable: false标记继承条目或只读条目。随后Blockstudio会将编译后的资源写入已配置Blockstudio缓存根目录下、特定上下文的generated范围,而不是写入父级源旁边。因此,生成的资源、Tailwind输出、渲染文档和静态预渲染都共用同一可写主机边界。
两个过滤器可用于自定义运行时路由:
add_filter(
'blockstudio/generated_output/path',
function (string $path, string $source, string $scope, array $metadata) {
return $path;
},
10,
4
);
add_filter(
'blockstudio/files/url',
function (string $url, string $path, string $scope) {
return $url;
},
10,
3
);
当所选文件位于wp-content之外,或通过运行时端点提供时,请使用URL过滤器。