跳转到正文

逻辑发现源

Blockstudio通常会从物理主题目录中发现文件。运行时工具可以用逻辑清单替代这些目录。这适用于预览、叠加层、生成的主题、远程挂载,以及相关文件并不共享同一个物理根目录的其他环境。

Blockstudio仍会解析并注册区块、页面、集合、样板、字段、模板和模板部件。源仅决定哪些逻辑文件可见,以及每个可见文件的读取位置。

清单源

使用blockstudio/discovery/sources过滤器替换默认的Filesystem_Discovery_Source对象:

PHP
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
);

可用的上下文如下:

  • blocks
  • fields
  • pages
  • patterns
  • site-templates
  • site-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:

PHP
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输出、渲染文档和静态预渲染都共用同一可写主机边界。

两个过滤器可用于自定义运行时路由:

PHP
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过滤器。