如何在自定义WordPress PHP模板中预加载ACF区块至区块编辑器

1. 自动预加载Hero区块到页面顶部 #

针对默认「页面」类型，通过block_editor_settings_all过滤器设置区块模板，让新建页面自动加载Hero区块，同时锁定模板结构，防止Hero被移动或其他区块插入到它上方。

将以下代码添加到functions.php中：

function set_page_block_template($settings, $context) {
    // 仅针对页面类型的编辑器
    if ($context->post->post_type === 'page') {
        // 设置区块模板：第一个是你的Hero区块，后面是可编辑的内容区域
        $settings['template'] = array(
            array('your-namespace/hero'), // 替换成你Hero区块block.json里的name字段值
            array('core/paragraph', array(
                'placeholder' => '开始添加页面内容...'
            ))
        );
        // 锁定模板结构：用户只能编辑区块内容，不能修改模板的区块顺序或删除指定区块
        $settings['templateLock'] = 'contentOnly';
    }
    return $settings;
}
add_filter('block_editor_settings_all', 'set_page_block_template', 10, 2);

注意：替换your-namespace/hero为你Hero区块block.json中name字段的实际值，比如区块命名为acf/hero就填这个。

2. 完善Hero区块的锁定配置 #

调整/blocks/hero/block.json的配置，确保Hero区块不能被多次添加、重命名或设为可复用，同时强化锁定：

{
    "name": "acf/hero", // 你的区块命名空间和名称
    "title": "Hero区块",
    "description": "页面顶部的Hero区域",
    "category": "common",
    "icon": "cover-image",
    "keywords": ["hero", "顶部"],
    "acf": {
        "mode": "edit",
        "renderTemplate": "hero.php"
    },
    "supports": {
        "anchor": true,
        "align": false,
        "lock": true, // 开启锁定支持
        "multiple": false, // 禁止添加多个Hero区块
        "renaming": false,
        "reusable": false
    },
    "attributes": {
        "lock": {
            "type": "object",
            "default": {
                "remove": true, // 禁止移除
                "move": false // 禁止移动该区块
            }
        }
    }
}

3. 为现有页面自动补全Hero区块 #

上述设置仅对新建页面生效，如果要让已存在的页面自动添加Hero区块（未添加过的情况），可将以下代码添加到functions.php：

function add_hero_to_existing_pages($post_content, $post) {
    // 仅针对页面类型，且内容中没有Hero区块时添加
    if ($post->post_type === 'page' && strpos($post_content, '<!-- wp:acf/hero') === false) {
        // 拼接Hero区块到内容开头
        $hero_block = '<!-- wp:acf/hero -->
<div class="wp-block-acf-hero"></div>
<!-- /wp:acf/hero -->';
        $post_content = $hero_block . $post_content;
    }
    return $post_content;
}
add_filter('the_content', 'add_hero_to_existing_pages', 10, 2);

注意：同样替换acf/hero为你区块的实际名称。

关键说明 #

• templateLock: 'contentOnly'会锁定模板的区块结构，用户只能编辑每个区块的内容，不能调整区块顺序、删除模板指定的区块，也不能在Hero上方插入其他区块。
• 区块本身的move: false设置会进一步防止用户尝试移动Hero区块。
• multiple: false确保编辑器中只能添加一个Hero区块。

内容的提问来源于stack exchange，提问作者Phil Penny