跳转到正文

PHP 钩子

以下列出了所有可用的 PHP 钩子,你可以使用它们扩展或调整插件功能。

路径

此筛选器可用于调整区块文件夹的路径。默认情况下,该路径位于当前启用主题的 blockstudio 中。你也可以 创建新实例,以使用多个源目录。

PHP
add_filter('blockstudio/path', function() {
  $path = get_stylesheet_directory() . '/blocks';
  return $path;
});

初始化

全局

此操作会在插件注册完所有区块后触发。

PHP
add_action('blockstudio/init', function($blocks) {
  // All blocks have been registered
});

实例

此操作会在插件注册完特定实例的所有区块后触发。$instance 部分是相对于 wp-content 的实例路径。

PHP
$instance = 'themes/my-theme/client-blocks';
add_action("blockstudio/init/$instance", function() {
  // All blocks of this instance have been registered
});

global/before

此操作会在插件注册所有区块之前触发。

PHP
add_action('blockstudio/init/before', function() {
  // Before blocks are registered
});

global/before/$instance

此操作会在插件注册特定实例的所有区块之前触发。

PHP
$instance = 'themes/my-theme/client-blocks';
add_action("blockstudio/init/before/$instance", function() {
  // Before blocks of this instance are registered
});

区块

渲染

此筛选器可用于调整区块渲染前的输出。

PHP
add_filter('blockstudio/blocks/render', function($content, $block, $attributes) {
  // Modify the block content
  return $content;
}, 10, 3);

元数据

此筛选器可用于调整 block.json 文件的数据,然后再进行注册。

PHP
add_filter('blockstudio/blocks/meta', function($meta, $block) {
  if (str_starts_with($block['name'], 'marketing')) {
    $meta['icon'] = 'megaphone';
  }
  return $meta;
}, 10, 2);

上面的代码会更改所有名称以 marketing 开头的区块图标。

条件

此筛选器允许你添加可在区块中使用的自定义条件。每种条件类型都会映射到一个值,编辑器会将该值与条件的 value 进行比较。请参阅 自定义条件。

PHP
add_filter('blockstudio/blocks/conditions', function($conditions) {
  $conditions['myCustomCondition'] = 'expected';
  return $conditions;
});

属性

此筛选器会在区块注册前调整单个字段定义。筛选后的定义决定编辑器控件和渲染时的值验证方式。更多信息请参阅 筛选。

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  // Modify this field definition before registration.
  return $attribute;
}, 10, 2);

attributes/render

此筛选器会在字段值传递给区块模板之前对其进行调整。它对每个字段运行一次,并接收三个参数:$value(解析后的值)、$key(字段键,在 $a 中使用)和 $block(模板以 $block 或 $b 的形式接收的区块数据数组)。注册时请设置为接受三个参数。有关详情,请参阅 筛选。

PHP
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
  // Modify the value of one field before rendering.
  return $value;
}, 10, 3);

attributes/files/sizes

files 字段会为每张图片返回一个 sizes 数组,其中包含 URL、full 的宽度和高度,以及每种已注册图片尺寸的信息,例如 $image['sizes']['thumbnail'] 和 $image['sizes']['thumbnail-width']。每种尺寸的每张图片都会调用一次 wp_get_attachment_image_src(),因此其筛选器仍会生效。永远不会读取 sizes 的模板可以移除或缩短此列表。

PHP
add_filter('blockstudio/blocks/attributes/files/sizes', function($sizes, $id, $size) {
  // Keep only two sizes. Return an empty array to skip them, `sizes` is then null.
  return ['full', 'large'];
}, 10, 3);

$sizes 是尺寸名称列表,full 排在最前(如果未注册中间尺寸,则为空)。$id 是附件 ID,$size 是为该值的 url 请求的尺寸。此筛选器会更改请求中每个文件值的 sizes 数组。若不使用此筛选器,该数组将保持不变。

以字符串形式返回尺寸名称。无效条目会被忽略,重复名称只处理一次,非数组返回值则会跳过尺寸。请求的 url 和其他附件属性保持不变。对于带有 returnFormat: "url" 的 files 字段,不会运行此钩子,因为该字段不会构建尺寸映射。

attributes/validate

调整显式调用 bs_validate_block() 后的发现结果,例如自定义渲染筛选器解析已存储的引用时。此操作不会启用保存或渲染时的自动验证。

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  return $findings;
}, 10, 3);

返回发现结果列表。如果区块没有 Blockstudio 字段或匹配的扩展(null),则不会调用此筛选器。

attributes/schema

调整JSON Schema,该 Schema 由bs_block_schema()返回,例如,自定义渲染过滤器解析已存储引用时。

PHP
add_filter('blockstudio/blocks/attributes/schema', function($schema, $name) {
  return $schema;
}, 10, 2);

返回 Schema 数组。当区块没有Blockstudio字段或匹配的扩展(null)时,不会调用此过滤器。

attributes/populate

此筛选器可用于向 checkbox、select 或 radio 字段的选项添加自定义数据。更多信息请参阅 填充选项。

筛选器接收一个参数:包含所有自定义数据集的数组,键名为 "populate": {"type": "custom", "custom": "myCustomOptions"} 中使用的名称。

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['myCustomOptions'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

components/use_block_props/render

此筛选器可用于调整 useBlockProps 内容的输出。

所有组件筛选器(use_block_props、inner_blocks 和 rich_text)都会将区块作为最后一个参数。$block 是正在渲染的区块所注册的 WP_Block_Type,因此 $block->name 是区块名称,例如 acme/hero。

$props 是包含 HTML 属性的字符串,而不是数组。在前端,它是 get_block_wrapper_attributes() 的结果,例如 class="wp-block-acme-hero my-class"。在编辑器中,它是元素的 class 属性。请返回字符串。在编辑器中,只会应用返回字符串的 class 属性。

PHP
add_filter('blockstudio/blocks/components/use_block_props/render', function($props, $block) {
  if ($block->name !== 'acme/hero') {
    return $props;
  }

  return str_replace('class="', 'class="my-custom-class ', $props);
}, 10, 2);

components/inner_blocks/render

此筛选器可用于调整 <InnerBlocks /> 内容的输出。

PHP
add_filter('blockstudio/blocks/components/inner_blocks/render', function($content, $block) {
  return '<div class="inner-wrapper">' . $content . '</div>';
}, 10, 2);

components/inner_blocks/frontend/wrap

此筛选器可用于从前端移除 <InnerBlocks /> 包装元素。

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

components/rich_text/render

此筛选器允许你调整 <RichText /> 内容的输出。它会接收属性值和区块。

PHP
add_filter('blockstudio/blocks/components/rich_text/render', function($content, $block) {
  return wp_kses_post($content);
}, 10, 2);

区块标签

blockstudio/block_tags/builders

此筛选器注册由区块标签使用的区块数组构建器,以及通过 blockstudio/parser/element_mapping 选择的自定义区块构建器。每个构建器都会接收解析后的属性和原始内部内容。

PHP
add_filter('blockstudio/block_tags/builders', function($builders, $parser) {
  $builders['theme/paragraph'] = function(array $attributes, string $inner) {
    $attributes['content'] = trim($inner);

    return [
      'blockName' => 'theme/paragraph',
      'attrs' => [
        'blockstudio' => [
          'attributes' => $attributes,
        ],
      ],
      'innerBlocks' => [],
      'innerHTML' => '',
      'innerContent' => [],
    ];
  };

  return $builders;
}, 10, 2);

兼容的 blockstudio/block_tags/renderers 和 blockstudio/parser/renderers 筛选器会在此钩子之后运行,并可覆盖相同的区块名称。

blockstudio/block_tags/tag_aliases

此筛选器允许你注册自定义的连字符作者标签,这些标签会在原始 HTML 回退之前解析为实际区块名称。当主题希望提供简洁的项目专用标签,同时仍渲染标准 Blockstudio 或核心区块时,这会很有用。

PHP
add_filter('blockstudio/block_tags/tag_aliases', function($aliases) {
  $aliases['theme-button'] = 'bsui/button';
  $aliases['theme-card'] = 'theme/card';

  return $aliases;
});
HTML
<theme-button href="/download" label="Download" />
<theme-card title="Fast authoring">
  <p>Children are parsed as nested blocks.</p>
</theme-card>

blockstudio/block_tags/prefixes

此筛选器允许你将前缀简写映射到一个或多个区块命名空间。每个键都是不带连字符的小写前缀。每个值可以是命名空间字符串,也可以是有序的命名空间列表。

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

<theme-card> 解析为 theme-components/card。<theme-button> 会先尝试 theme-components/button,然后回退到 bsui/button。相同标签的显式 blockstudio/block_tags/tag_aliases 条目具有优先权,无法解析的带前缀标签会保持不变。

前缀可以组合使用:如果带前缀的标签无法直接解析,且其 slug 本身是已注册的前缀标签,则会递归解析。对于 theme => ['theme-components'] 和 ui => ['bsui'],<theme-ui-input> 会继续尝试 ui 前缀,并解析为 bsui/input。已注册的前缀和别名标签也会在区块模板输出中渲染,而不只是在页面内容中渲染。

设置

路径

此筛选器允许你调整 blockstudio.json 文件的路径。默认情况下,该文件位于当前启用主题中的 blockstudio.json。

PHP
add_filter('blockstudio/settings/path', function() {
  return get_stylesheet_directory() . '/config/blockstudio.json';
});

users/ids

此筛选器允许你为特定用户 ID 启用编辑器。

PHP
add_filter('blockstudio/settings/users/ids', function() {
  return [1];
});

users/roles

此筛选器允许你为特定用户角色启用编辑器。

PHP
add_filter('blockstudio/settings/users/roles', function() {
  return ['administrator', 'editor'];
});

assets/enqueue

此筛选器允许你启用或禁用在前端和编辑器中加入资源队列。

PHP
add_filter('blockstudio/settings/assets/enqueue', function() {
  return false;
});

assets/reset/enabled

此筛选器允许你启用或禁用移除 WordPress 核心区块样式和编辑器实用布局重置。

PHP
add_filter('blockstudio/settings/assets/reset/enabled', function() {
  return true;
});

assets/reset/full_width

此筛选器允许你控制哪些文章类型使用全宽编辑。

PHP
add_filter('blockstudio/settings/assets/reset/full_width', function() {
  return ['page'];
});

assets/minify/css

此筛选器允许你启用或禁用 CSS 的压缩。

PHP
add_filter('blockstudio/settings/assets/minify/css', function() {
  return true;
});

assets/minify/js

此筛选器允许你启用或禁用 JS 的压缩。

PHP
add_filter('blockstudio/settings/assets/minify/js', function() {
  return true;
});

assets/process/scss

此筛选器允许你启用或禁用在 .css 文件中处理 SCSS。

PHP
add_filter('blockstudio/settings/assets/process/scss', function() {
  return true;
});

assets/process/scss_files

此筛选器允许你启用或禁用将 .scss 文件处理为 CSS。

PHP
add_filter('blockstudio/settings/assets/process/scss_files', function() {
  return true;
});

assets/output

此筛选器允许你控制编译后的区块资源写入位置。

PHP
add_filter('blockstudio/settings/assets/output', function() {
  return 'cache';
});

assets/inline_limit

筛选每个页面内联的外部区块 CSS 字节数。

PHP
add_filter('blockstudio/settings/assets/inline_limit', function() {
  return 40000;
});

cache/enabled

此筛选器允许你启用或禁用所有由文件支持的 Blockstudio 运行时和编辑器资源缓存。

PHP
add_filter('blockstudio/settings/cache/enabled', function() {
  return false;
});

cache/path

此筛选器允许你更改由 Blockstudio 文件支持的缓存目录。

PHP
add_filter('blockstudio/settings/cache/path', function() {
  return 'cache/blockstudio';
});

cache/namespace_grace

此筛选器允许你更改已弃用的缓存命名空间在清理前保留的时长。

PHP
add_filter('blockstudio/settings/cache/namespace_grace', function() {
  return 777600;
});

githooks/commit

此筛选器会公开 Blockstudio 所属的 PHPStan 提交钩子是否已启用。

PHP
add_filter('blockstudio/settings/githooks/commit', function() {
  return true;
});

content/enabled

此筛选器允许你启用或禁用内容同步。

PHP
add_filter('blockstudio/settings/content/enabled', function() {
  return true;
});

content/id

此筛选器允许你设置内容同步的所有权命名空间。

PHP
add_filter('blockstudio/settings/content/id', function() {
  return 'docs';
});

content/path

此筛选器允许你设置内容同步文件目录。

PHP
add_filter('blockstudio/settings/content/path', function() {
  return 'content';
});

content/include_page_sync_managed

此筛选器允许你纳入或排除由页面同步管理的文章。

PHP
add_filter('blockstudio/settings/content/include_page_sync_managed', function() {
  return false;
});

content/authors

此筛选器允许你配置内容同步的作者处理方式。

PHP
add_filter('blockstudio/settings/content/authors', function() {
  return 'ignore';
});

content/post_types

此筛选器允许你配置内容同步的文章类型允许列表。

PHP
add_filter('blockstudio/settings/content/post_types', function() {
  return ['team_member'];
});

content/taxonomies

此筛选器允许你配置内容同步的分类法允许列表。

PHP
add_filter('blockstudio/settings/content/taxonomies', function() {
  return ['category', 'post_tag'];
});

content/media

此筛选器允许你配置内容同步的媒体处理方式。

PHP
add_filter('blockstudio/settings/content/media', function() {
  return 'manifest';
});

tailwind/enabled

此筛选器允许你启用或禁用 Tailwind。

PHP
add_filter('blockstudio/settings/tailwind/enabled', function() {
  return true;
});

tailwind/config

此筛选器允许你添加自定义的 Tailwind CSS 配置。

PHP
add_filter('blockstudio/settings/tailwind/config', function() {
  return '@theme { --color-primary: pink; }';
});

tailwind/output

此筛选器允许你选择内联或链接形式的 Tailwind CSS 输出。

PHP
add_filter('blockstudio/settings/tailwind/output', function() {
  return 'link';
});

ui/enabled

此筛选器允许你启用或禁用捆绑的 UI 组件。

PHP
add_filter('blockstudio/settings/ui/enabled', function() {
  return true;
});

editor/format_on_save

此筛选器允许你启用或禁用保存时的代码格式化。

PHP
add_filter('blockstudio/settings/editor/format_on_save', function() {
  return true;
});

editor/assets

此筛选器允许你在编辑器中加入其他资源。

PHP
add_filter('blockstudio/settings/editor/assets', function() {
  return ['my-stylesheet', 'another-stylesheet'];
});

editor/markup

此筛选器允许你在编辑器末尾添加其他标记。

PHP
add_filter('blockstudio/settings/editor/markup', function() {
  return '<style>body { background: black; }</style>';
});

block_editor/disable_loading

此筛选器允许你禁用区块编辑器中的区块加载。

PHP
add_filter('blockstudio/settings/block_editor/disable_loading', function() {
  return true;
});

block_editor/enhance

此筛选器允许你启用 Blockstudio 编辑器交互功能,例如更简洁的焦点样式以及悬停/选择轮廓。

PHP
add_filter('blockstudio/settings/block_editor/enhance', function() {
  return true;
});

block_editor/css_classes

此筛选器允许你添加样式表,以便其类可在类字段中供选择。

PHP
add_filter('blockstudio/settings/block_editor/css_classes', function() {
  return ['my-stylesheet', 'another-stylesheet'];
});

block_editor/css_variables

此筛选器允许你添加样式表,以便其 CSS 变量可在代码字段中用于自动补全。

PHP
add_filter('blockstudio/settings/block_editor/css_variables', function() {
  return ['my-stylesheet', 'another-stylesheet'];
});

block_editor/blocks/allow

此筛选器允许你控制哪些区块名称可在插入器中使用。

PHP
add_filter('blockstudio/settings/block_editor/blocks/allow', function() {
  return ['core/*', 'acf/*', 'my-theme/*'];
});

block_editor/blocks/deny

此筛选器允许你从插入器中移除区块名称。

PHP
add_filter('blockstudio/settings/block_editor/blocks/deny', function() {
  return ['core/embed', 'core/freeform'];
});

block_editor/blocks/directory

此筛选器允许你启用或禁用编辑器中的 WordPress 区块目录资源。

PHP
add_filter('blockstudio/settings/block_editor/blocks/directory', function() {
  return false;
});

block_editor/blocks/categories/allow

此筛选器允许你控制哪些区块分类 slug 保持可用。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/allow', function() {
  return ['text', 'media', 'design'];
});

block_editor/blocks/categories/deny

此筛选器允许你从插入器中移除区块分类 slug。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/deny', function() {
  return ['embed'];
});

block_editor/blocks/categories/rename

此筛选器允许你按 slug 重命名区块分类标签。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/rename', function() {
  return [
    'text' => 'Writing',
    'design' => 'Layout'
  ];
});

block_editor/blocks/categories/order

此筛选器允许你在插入器中排列区块分类 slug 的顺序。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/order', function() {
  return ['my-theme', 'text', 'media'];
});

block_editor/blocks/styles/deny

此筛选器允许你按区块名称注销由 PHP 注册的区块样式。

PHP
add_filter('blockstudio/settings/block_editor/blocks/styles/deny', function() {
  return [
    'my-theme/card' => ['outline'],
    'my-theme/media' => ['framed']
  ];
});

block_editor/blocks/legacy_widgets/hide

此筛选器允许你从旧版小工具区块中隐藏其他旧版小工具。

PHP
add_filter('blockstudio/settings/block_editor/blocks/legacy_widgets/hide', function() {
  return ['archives', 'calendar'];
});

block_editor/patterns/core

此筛选器允许你启用或禁用 WordPress 核心区块样板。

PHP
add_filter('blockstudio/settings/block_editor/patterns/core', function() {
  return false;
});

block_editor/patterns/remote

此筛选器允许你启用或禁用来自 WordPress 样板目录的远程样板。

PHP
add_filter('blockstudio/settings/block_editor/patterns/remote', function() {
  return false;
});

block_editor/patterns/theme

此筛选器允许你启用或禁用主题提供的区块样板。

PHP
add_filter('blockstudio/settings/block_editor/patterns/theme', function() {
  return false;
});

block_editor/patterns/blockstudio

此筛选器允许你启用或禁用基于 Blockstudio 文件的样板。

PHP
add_filter('blockstudio/settings/block_editor/patterns/blockstudio', function() {
  return false;
});

block_editor/patterns/categories/allow

此筛选器允许你控制哪些样板分类 slug 保持可用。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/allow', function() {
  return ['featured', 'buttons', 'columns'];
});

block_editor/patterns/categories/deny

此筛选器允许你从样板插入器中移除样板分类 slug。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/deny', function() {
  return ['gallery'];
});

block_editor/patterns/categories/rename

此筛选器允许你按 slug 重命名样板分类标签。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/rename', function() {
  return [
    'featured' => 'Featured Layouts'
  ];
});

block_editor/patterns/categories/order

此筛选器允许你在插入器中排列样板分类 slug 的顺序。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/order', function() {
  return ['featured', 'buttons'];
});

block_editor/media/openverse

此筛选器允许你在区块编辑器媒体插入器中启用或禁用 Openverse 媒体分类。

PHP
add_filter('blockstudio/settings/block_editor/media/openverse', function() {
  return false;
});

block_editor/media/image_sizes/allow

此筛选器允许你控制编辑器媒体控件中哪些图像尺寸名称保持可用。

PHP
add_filter('blockstudio/settings/block_editor/media/image_sizes/allow', function() {
  return ['thumbnail', 'large'];
});

block_editor/media/image_sizes/deny

此筛选器允许你从编辑器媒体控件中移除图像尺寸名称。

PHP
add_filter('blockstudio/settings/block_editor/media/image_sizes/deny', function() {
  return ['medium_large'];
});

ai/enable_context_generation

此筛选器允许你为 LLM 工具集成启用或禁用上下文文件生成。启用后,上下文文件会汇集最新的区块数据、当前安装的 Blockstudio 设置、所有相关架构以及 Blockstudio 文档,形成一个供 AI 开发工具使用的信息源。

PHP
add_filter('blockstudio/settings/ai/enable_context_generation', function() {
  return true;
});

block_tags/enabled

此筛选器允许你启用或禁用页面级区块标签渲染。

PHP
add_filter('blockstudio/settings/block_tags/enabled', function() {
  return true;
});

block_tags/prefixes

此筛选器允许你为区块标签注册前缀到命名空间的简写。

PHP
add_filter('blockstudio/settings/block_tags/prefixes', function() {
  return [
    'theme' => ['theme-components', 'bsui']
  ];
});

dev/grab/enabled

此筛选器允许你启用或禁用元素抓取器。

PHP
add_filter('blockstudio/settings/dev/grab/enabled', function() {
  return false;
});

dev/perf

此筛选器允许你启用或禁用性能分析器。

PHP
add_filter('blockstudio/settings/dev/perf', function() {
  return false;
});

dev/canvas/enabled

此筛选器允许你启用或禁用画布。

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', function() {
  return false;
});

dev/canvas/admin_bar

此筛选器允许你在画布上显示或隐藏 WordPress 管理栏。

PHP
add_filter('blockstudio/settings/dev/canvas/admin_bar', function() {
  return true;
});

WPML

blockstudio/wpml/config/label

筛选 wp bs wpml config 写入的每个键的标签。有关上下文数组,请参阅更改标签。

PHP
add_filter('blockstudio/wpml/config/label', function($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

画布

blockstudio/canvas/inventory

此筛选器会调整画布为某个选择项报告的清单。回调会接收清单 DTO、原始选择项和调用时传入的选项。

PHP
add_filter('blockstudio/canvas/inventory', function(array $result, array $selection, array $options) {
  return $result;
}, 10, 3);

blockstudio/canvas/documents

此筛选器会调整画布返回的已渲染文档,其参数与清单筛选器的三个参数相同。

blockstudio/canvas/item_loaded

每加载一条清单记录时,此操作都会触发,并接收清单类型、规范记录 ID 和规范化后的记录。

blockstudio/canvas/source_compiled

为画布编译源文件后,此操作会触发,并接收所选源路径和规范源记录。

捆绑的 UI

blockstudio/ui/directories

此筛选器会调整扫描捆绑 UI 组件时使用的目录。

blockstudio/ui/inventory

此筛选器会调整公开的 UI 系列清单。

blockstudio/ui/examples

此筛选器会调整 UI 示例记录,并接收这些示例及其来源的公开 UI 清单。

拓扑

blockstudio/blocks/topology_refreshed

区块拓扑重建后,此操作会触发。

blockstudio/pages/topology_refreshed

页面拓扑重建后,此操作会触发。

blockstudio/pages/layout_error

页面布局渲染失败时,此操作会触发,以避免错误被静默忽略。

运行时

blockstudio/runtime/initialized

运行时解析完其配置后,此操作会触发。

blockstudio/runtime/changed

解析后的运行时身份发生变化时,此操作会触发;这会改变缓存命名空间和静态预渲染状态。

blockstudio/performance/default_config

此筛选器会调整性能默认值,然后再叠加项目自身的 blockstudio.json 值。

内容

blockstudio/content/orphan_action

此筛选器决定内容同步如何处理不再有来源的记录。

Bootstrap

blockstudio/url

此筛选器会更改用于 Blockstudio 的编辑器和管理资源的公开 URL。Composer 集成必须在加载 Blockstudio 的自动加载文件之前注册它。第二个参数是软件包的物理目录。

PHP
add_filter(
  'blockstudio/url',
  function(string $url, string $directory) {
    return get_stylesheet_directory_uri() . '/vendor/blockstudio/blockstudio/';
  },
  10,
  2
);

运行时缓存

blockstudio/cache/dir

此筛选器会接收解析后的缓存基目录,之后才会追加运行时、编辑器资源或其他缓存作用域。

PHP
add_filter('blockstudio/cache/dir', function(string $directory) {
  return WP_CONTENT_DIR . '/cache/blockstudio';
});

blockstudio/cache/context

此筛选器会向缓存身份添加可序列化的运行时变体。当相同的发现来源可以选择不同的逻辑清单时,请使用它。

PHP
add_filter('blockstudio/cache/context', function($context, string $scope) {
  return [
    'preview' => get_query_var('preview_id'),
    'site' => get_current_blog_id(),
  ];
}, 10, 2);

blockstudio/cache/site_key

此筛选器会更改网络/博客目录身份,适用于有自己租户边界的主机。返回值会在使用前经过净化。

PHP
add_filter(
  'blockstudio/cache/site_key',
  function(string $key, int $networkId, int $blogId) {
    return sprintf('tenant-%d-%d', $networkId, $blogId);
  },
  10,
  3
);

blockstudio/runtime/identity

此筛选器会添加影响运行时作用域中每个对象的主机信息。特定项目的来源指纹应由所属的 API 作为显式依赖传入。

PHP
add_filter(
  'blockstudio/runtime/identity',
  function(array $identity, string $scope) {
    $identity['deployment'] = getenv('RELEASE_SHA') ?: 'local';
    return $identity;
  },
  10,
  2
);

blockstudio/cache/watch_debounce

筛选经过验证的文件监视快照在无需再次执行文件系统 stat 的情况下可重用的秒数。默认情况下,本地和开发环境为 0,其他环境为 20。

PHP
add_filter('blockstudio/cache/watch_debounce', function() {
  return 30;
});

blockstudio/cache/build_wait_budget

筛选请求等待并发构建器发布运行时缓存或刷新已填充选项的时长(以毫秒为单位),超时后请求会降级处理。结构重建的默认值为 5000,选项刷新的默认值为 4000。

PHP
add_filter('blockstudio/cache/build_wait_budget', function() {
  return 2000;
});

blockstudio/cache/populate_debounce

筛选内容、术语、用户或元数据写入突发被合并为一次已填充选项刷新的秒数。静默期后的首次写入会立即刷新;突发期间的最后一次写入会在窗口结束后反映。默认值为 30。返回 0 可在每次写入时刷新。

PHP
add_filter('blockstudio/cache/populate_debounce', function() {
  return 120;
});

blockstudio/cache/populate_ignored_meta_keys

筛选其写入操作永远不会刷新已填充选项的元键。默认情况下,这些键是 WordPress 写入的编辑和登录记录:_edit_lock,在文章打开期间由编辑器和 Heartbeat 刷新;_edit_last,在文章保存时写入,而该保存操作本身已会触发刷新;以及 session_tokens,在登录和注销时写入。对于经常变化但从不影响填充查询的键,请将其添加进来。

PHP
add_filter('blockstudio/cache/populate_ignored_meta_keys', function(array $keys) {
  $keys[] = '_my_view_counter';
  return $keys;
});

blockstudio/cache/max_files_per_scope

筛选每个运行时缓存作用域保留的已发布载荷数量。

PHP
add_filter('blockstudio/cache/max_files_per_scope', function($maximum, $scope) {
  return $scope === 'runtime' ? 50 : $maximum;
}, 10, 2);

blockstudio/cache/compress

筛选缓存载荷是否使用压缩的序列化数据,而不是普通的 PHP 数组。默认情况下,只有不超过 1 MiB 的载荷才使用普通格式,并且目标位置可由活动的 OPcache 共享内存缓存时才会如此。其他进程、被排除的文件以及更大的载荷都会使用压缩。

PHP
add_filter('blockstudio/cache/compress', function($compress, $scope) {
  return $scope === 'runtime' ? false : $compress;
}, 10, 2);

返回 false 也会覆盖大小限制。当 WP-CLI 在不使用 opcache.enable_cli 的情况下为启用了 OPcache 的 Web 工作进程预热文件时,这可能会有帮助,但所有未启用 OPcache 的读取者都会解析生成的数组。除非可以接受额外的内存开销,否则大型共享载荷应继续使用压缩。默认保护措施请参阅缓存载荷格式。

blockstudio/cache/protected_paths

缓存路径保留清理绝不能移除。Blockstudio 会将已安装的早期服务映射中引用的所有文件加入其中。

PHP
add_filter('blockstudio/cache/protected_paths', function(array $paths, string $scope, string $directory) {
  if ('static-prerender' === $scope) {
    $paths[] = $directory . '/pinned.html';
  }
  return $paths;
}, 10, 3);

blockstudio/cache/outcome

此操作会报告共享缓存作用域及其结果,例如 hit、build、miss-stale、stale-last-good 或 write-failure。

PHP
add_action('blockstudio/cache/outcome', function(string $scope, string $reason) {
  my_metrics()->increment("blockstudio.cache.{$scope}.{$reason}");
}, 10, 2);

blockstudio/static_prerender/request_bypass

此筛选器会接收最终的匿名安全判定,以及服务器和 Cookie 输入。返回 true 始终会绕过静态服务和生成。

PHP
add_filter(
  'blockstudio/static_prerender/request_bypass',
  function(bool $bypass, array $server, array $cookies) {
    return $bypass || isset($cookies['commerce_session']);
  },
  10,
  3
);

blockstudio/static_prerender/public_urls

此筛选器会提供或调整供计划任务预热器和显式图工具使用的完整公开 URL 清单。

PHP
add_filter('blockstudio/static_prerender/public_urls', function(array $urls) {
  $urls[] = home_url('/custom-route/');
  return array_values(array_unique($urls));
});

筛选器返回的内容不是最终清单。结果会经过可缓存性检查,移除所有匹配已配置动态路径的项目,以及默认绕过的项目:/wp-admin、/wp-json、/wp-login.php、/xmlrpc.php、包含 /feed/ 的任意路径,以及位于站点主页搜索基路径下的搜索结果(默认值为 /search/)。因此,你添加的 URL 可能会在没有警告的情况下被丢弃。如果预期路由未出现在构建的清单中,请先根据这些规则检查它,再判断筛选器没有运行。

blockstudio/static_prerender/render_internal

此过滤器实现可选的进程内批量传输。返回规范化的结果数组,或保持值不变,以便渲染器使用其配置的HTTP回退方案。结果包含html,并可选包含status、dependencies、virtualHashes和headers;performance.staticPrerender.replayHeaders中指定的标头会与文档一同存储。

PHP
add_filter(
  'blockstudio/static_prerender/render_internal',
  function($result, string $url, array $options) {
    return my_static_renderer()->render($url, $options);
  },
  10,
  3
);

blockstudio/static_prerender/cacheable_html

Blockstudio 验证输出是完整的 HTML 文档、不含无缓存标记,且观察到的响应状态为成功后,此筛选器会作出最终判定。第三个参数是观察到的状态;如果未声明状态,则为 null。

PHP
add_filter('blockstudio/static_prerender/cacheable_html', function(bool $cacheable, string $html, ?int $status) {
  return $cacheable && !str_contains($html, 'data-personalized');
}, 10, 3);

blockstudio/static_prerender/outcome

此操作会报告静态预渲染结果,包括命中、未命中、写入、图写入、过期条目和失败。

PHP
add_action('blockstudio/static_prerender/outcome', function(string $reason) {
  my_metrics()->increment("blockstudio.prerender.{$reason}");
});

blockstudio/tailwind/cache_max_files

筛选编译后的 Tailwind CSS 条目数量上限。默认值为 1000。

PHP
add_filter('blockstudio/tailwind/cache_max_files', function() {
  return 1500;
});

blockstudio/tailwind/cache_max_age

筛选编译后的 Tailwind CSS 条目的最长存留时间(秒)。默认值为 30 天,最短为一小时。

PHP
add_filter('blockstudio/tailwind/cache_max_age', function() {
  return 14 * DAY_IN_SECONDS;
});

管理后台

已启用

此筛选器允许你启用或禁用 工具 > Blockstudio 下的 Blockstudio 管理页面。

PHP
add_filter('blockstudio/admin/enabled', function() {
  return false;
});

资源

editor/canvas/body_class

启用资源重置后,此筛选器会调整复制到区块编辑器画布中的、已净化的前端 body 类。

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

启用

此筛选器允许你禁用特定资源类型的处理和入队。

PHP
add_filter('blockstudio/assets/enable', function($enable, $type, $block) {
  if ($type === 'css' && $block['name'] === 'my/block') {
    return false;
  }
  return $enable;
}, 10, 3);

禁用

此筛选器允许你按 ID 禁用特定资源。与返回数组中的某个 ID 匹配的资源不会在前端渲染。

PHP
add_filter('blockstudio/assets/disable', function($disabled) {
  $disabled[] = 'my-block-style';
  return $disabled;
});

process/scss/import_paths

此筛选器允许你为 SCSS 编译器的 @import 语句添加其他路径。

PHP
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
  $paths[] = get_stylesheet_directory() . '/scss';
  return $paths;
});

process/scss/prelude

此筛选器允许你在编译每个 SCSS 文件之前添加共享的 Sass 代码。

PHP
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);

process/css/content

此筛选器允许你在编译 CSS 文件之前调整其内容。

PHP
add_filter('blockstudio/assets/process/css/content', function($content, $block) {
  return str_replace('old-class', 'new-class', $content);
}, 10, 2);

process/js/content

此筛选器允许你在编译 JS 文件之前调整其内容。

PHP
add_filter('blockstudio/assets/process/js/content', function($content, $block) {
  return $content;
}, 10, 2);

缓冲

已启用

Blockstudio 会缓冲前端响应,以便将正文中渲染的区块样式和脚本标签提升到 head 和 footer 中,并让 Tailwind 扫描完整文档。缓冲意味着在每次前端请求中暂存并扫描整个文档;如果站点未渲染任何 Blockstudio 区块资源,也不使用 Tailwind,则可返回 false,以跳过这两项操作。

PHP
add_filter('blockstudio/buffer/enabled', '__return_false');

管理后台和 Customizer 预览中也会关闭缓冲。从 wp_enqueue_scripts 或更晚的阶段调用 bs_is_buffering(),以确定当前响应是否已缓冲。它会在 template_redirect 作出决定之前返回 false。

输出

此筛选器会在完整缓冲的 HTML 文档发送前接收它。Blockstudio 自身的资源提升会在优先级 1000000 运行,Tailwind 编译会在 999999 运行;因此,若要在这些操作之前查看文档,请提前运行;若要查看最终输出,请在之后运行。

PHP
add_filter('blockstudio/buffer/output', function(string $html) {
  return $html;
}, 2000000);

渲染

依赖项

每当 Blockstudio 渲染区块时,此筛选器会报告所选模板及资源依赖项。它适用于静态导出器和其他进程内依赖项收集器。

PHP
add_filter(
  'blockstudio/render/dependencies',
  function($paths, $name, $block, $isEditor, $isPreview) {
    my_dependency_graph()->add($name, $paths);
    return $paths;
  },
  10,
  5
);

全局

此筛选器允许你在页面输出渲染之前对其进行调整。

PHP
add_filter('blockstudio/render', function($content) {
  return $content;
});

此筛选器允许你在 <head> 标签渲染之前调整其输出。只有当 Blockstudio 缓冲响应时才会运行,参见 bs_is_buffering()。

PHP
add_filter('blockstudio/render/head', function($content) {
  return $content . '<meta name="custom" content="value">';
});

此筛选器允许你在 </body> 渲染之前调整其输出。

PHP
add_filter('blockstudio/render/footer', function($content) {
  return $content . '<script>console.log("loaded")</script>';
});

错误处理

error/logged

记录错误后触发的操作。可用它将错误发送到外部日志服务。

PHP
add_action('blockstudio/error/logged', function($message, $level, $context) {
  if ($level === 'error') {
    my_external_logger($message, $context);
  }
}, 10, 3);

error/exception

处理异常后触发的操作。

PHP
add_action('blockstudio/error/exception', function($exception, $context) {
  my_error_tracker($exception);
}, 10, 2);

数据库

所有数据库钩子都会接收一个 $params 数组。

db/before_create

创建记录前触发的操作。

PHP
add_action('blockstudio/db/before_create', function($params) {
  // $params: block, schema, data, storage
});

db/after_create

创建记录后触发的操作。

PHP
add_action('blockstudio/db/after_create', function($params) {
  // $params: block, schema, record, storage
  wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
});

db/before_update

更新记录前触发的操作。

PHP
add_action('blockstudio/db/before_update', function($params) {
  // $params: block, schema, id, data, storage
});

db/after_update

更新记录后触发的操作。

PHP
add_action('blockstudio/db/after_update', function($params) {
  // $params: block, schema, id, record, storage
});

db/before_delete

删除记录前触发的操作。

PHP
add_action('blockstudio/db/before_delete', function($params) {
  // $params: block, schema, id, storage
});

db/after_delete

删除记录后触发的操作。

PHP
add_action('blockstudio/db/after_delete', function($params) {
  // $params: block, schema, id, storage
});

RPC

所有 RPC 钩子都会接收一个 $params 数组。

rpc/before_call

调用 RPC 函数前触发的操作。

PHP
add_action('blockstudio/rpc/before_call', function($params) {
  // $params: block, function, params
});

rpc/after_call

调用 RPC 函数后触发的操作。

PHP
add_action('blockstudio/rpc/after_call', function($params) {
  // $params: block, function, params, result
});