跳转到正文

钩子

可用于自定义页面、样式、站点模板和 HTML 解析器的筛选器和操作。

解析器

blockstudio/block_tags/builders

注册供区块标签和元素映射自定义区块使用的区块数组构建器。每个区块的回调都会接收一个属性数组和原始内部内容。

PHP
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
    $builders['acf/hero'] = function( array $attrs, string $inner_content ) {
        $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );

        return array(
            'blockName'    => 'acf/hero',
            'attrs'        => $attrs,
            'innerBlocks'  => $inner_blocks,
            'innerHTML'    => '',
            'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
        );
    };

    return $builders;
}, 10, 2 );

blockstudio/block_tags/renderers 和 blockstudio/parser/renderers 接收同一个注册表。它们在 blockstudio/block_tags/builders 之后按此顺序运行,并且可以替换同一区块的早期构建器。

blockstudio/parser/element_mapping

覆盖默认的 HTML 元素到区块的映射。默认情况下,标准 HTML 元素(如 <h1>、<p> 和 <img>)会映射到核心 WordPress 区块。使用此筛选器可将任意元素指向其他区块。

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['h1']  = 'custom/heading';
    $mapping['h2']  = 'custom/heading';
    $mapping['p']   = 'custom/paragraph';
    $mapping['img'] = 'custom/image';

    return $mapping;
}, 10, 2 );

如果 <p> 映射到一个已注册的非核心 Blockstudio 区块,且该区块具有 content richtext 属性,其内部 HTML 会复制到该属性中,包括同时采用元素映射的 code 和 img 等内联标签。只有一个图像子元素的段落会变成 <img> 所映射到的区块。嵌套区块标签或区块级 HTML 仍按常规方式解析内部区块。

页面

blockstudio/pages/paths

筛选用于扫描页面模板的目录。

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_template_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

blockstudio/pages/manifest_scan_interval

筛选旧版、7.6.2 之前的清单缓存的最长有效期;升级时,该缓存可为持久化集合运行时提供初始数据。常规请求使用持久化的集合配置,不会定期重新扫描页面根目录。更改集合清单后,请运行 wp bs pages sync 或调用 Blockstudio\Pages::reconcile()。

PHP
add_filter( 'blockstudio/pages/manifest_scan_interval', function() {
    return 10;
} );

blockstudio/pages/create_post_data

创建新页面前筛选文章数据。

PHP
add_filter( 'blockstudio/pages/create_post_data', function( $post_data, $page_data ) {
    $post_data['post_author'] = 1;
    return $post_data;
}, 10, 2 );

blockstudio/pages/update_post_data

更新现有页面前筛选文章数据。

PHP
add_filter( 'blockstudio/pages/update_post_data', function( $post_data, $post, $page_data ) {
    return $post_data;
}, 10, 3 );

blockstudio/pages/synced

所有页面同步完成后触发的操作。

PHP
add_action( 'blockstudio/pages/synced', function( $registry ) {
    // $registry is the Page_Registry instance
} );

blockstudio/pages/post_created

创建页面文章后触发的操作。

PHP
add_action( 'blockstudio/pages/post_created', function( $post_id, $page_data ) {
    // Do something after page creation
}, 10, 2 );

blockstudio/pages/post_updated

更新页面文章后触发的操作。

PHP
add_action( 'blockstudio/pages/post_updated', function( $post_id, $page_data ) {
    // Do something after page update
}, 10, 2 );

模式

blockstudio/patterns/paths

筛选用于扫描模式模板的目录。

PHP
add_filter( 'blockstudio/patterns/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-patterns';
    $paths[] = MY_PLUGIN_PATH . '/patterns';
    return $paths;
} );

blockstudio/patterns/registered

所有模式注册完成后触发的操作。

PHP
add_action( 'blockstudio/patterns/registered', function( $registry ) {
    // $registry is the Pattern_Registry instance
} );

站点模板

blockstudio/site_templates/template_paths

筛选用于扫描 template.json 文件的目录。

PHP
add_filter( 'blockstudio/site_templates/template_paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/site-templates';
    return $paths;
} );

blockstudio/site_templates/part_paths

筛选用于扫描 part.json 文件的目录。

PHP
add_filter( 'blockstudio/site_templates/part_paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/site-parts';
    return $paths;
} );

blockstudio/site_templates/paths

同时筛选两个发现路径列表。该值包含 templates 和 parts 数组。

PHP
add_filter( 'blockstudio/site_templates/paths', function( $paths ) {
    return $paths;
} );

blockstudio/site_templates/template_candidates

清单和逻辑源树解析完成后,筛选源文件候选项。

PHP
add_filter(
    'blockstudio/site_templates/template_candidates',
    function( $candidates, $directory, $manifest ) {
        $candidates[] = $directory . '/template.custom.php';
        return $candidates;
    },
    10,
    3
);

blockstudio/site_templates/templates

筛选注册表 API 返回的完整模板。

PHP
add_filter( 'blockstudio/site_templates/templates', function( $templates ) {
    return $templates;
} );

blockstudio/site_templates/parts

筛选注册表 API 返回的模板部件。

PHP
add_filter( 'blockstudio/site_templates/parts', function( $parts ) {
    return $parts;
} );

blockstudio/site_templates/template_content

在 Blockstudio 将模板源字符串解析为区块前对其进行筛选。

PHP
add_filter( 'blockstudio/site_templates/template_content', function( $content, $template ) {
    return $content;
}, 10, 2 );

blockstudio/site_templates/part_content

在 Blockstudio 将模板部件源字符串解析为区块前对其进行筛选。

PHP
add_filter( 'blockstudio/site_templates/part_content', function( $content, $part ) {
    return $content;
}, 10, 2 );

blockstudio/site_templates/parser

筛选用于单个已编译模板或部件的 Blockstudio\Html_Parser 实例。返回一个 Html_Parser;其他值会回退到默认解析器。

PHP
add_filter(
    'blockstudio/site_templates/parser',
    function( $parser, $item ) {
        return $parser;
    },
    10,
    2
);

blockstudio/site_templates/discovered

冷启动发现和编译流程完成后、重建的注册表持久化之前触发的操作。

PHP
add_action( 'blockstudio/site_templates/discovered', function( $registry ) {
    // Inspect the rebuilt Site_Template_Registry.
} );

blockstudio/site_templates/registered

基于文件重建的站点编辑器模板注册表持久化后触发的操作。

PHP
add_action( 'blockstudio/site_templates/registered', function( $registry ) {
    // $registry is the Site_Template_Registry instance
} );

命中热注册表缓存时,不会触发 discovered 和 registered 操作。