使用block.json配置ACF区块：如何恢复插入器图标悬停预览

针对你遇到的ACF区块插入器悬停预览失效问题，以下是基于block.json的具体解决步骤和配置补充：

1. 修正example字段的结构 #

你之前在example/attributes中添加的代码可能未匹配ACF区块的数据存储结构。ACF区块的自定义字段数据默认存放在attributes.data下，因此需要将示例数据嵌套在data字段内，同时建议添加viewportWidth指定预览窗口宽度，保证预览效果完整。

示例block.json配置：

{
  "name": "custom/your-block-name",
  "title": "你的区块名称",
  "category": "common",
  "icon": "admin-comments",
  "acf": {
    "mode": "preview",
    "renderTemplate": "blocks/your-block/your-block-template.php"
  },
  "example": {
    "viewportWidth": 1200,
    "attributes": {
      "data": {
        "your_acf_field_key_1": "示例标题文本",
        "your_acf_field_key_2": "https://example.com/preview-banner.jpg",
        "your_acf_field_key_3": true
      }
    }
  }
}

注意：your_acf_field_key需替换为你实际使用的ACF字段键名。

2. 确保PHP模板兼容预览模式 #

插入器预览时，区块尚未保存到数据库，ACF的get_field()无法获取真实数据，因此需要在模板中加入降级逻辑，读取example中的示例数据作为 fallback：

示例PHP模板代码：

<?php
// 优先获取真实字段数据，无数据时使用示例数据
$field_title = get_field('your_acf_field_key_1') ?? $block['attributes']['data']['your_acf_field_key_1'];
$field_banner = get_field('your_acf_field_key_2') ?? $block['attributes']['data']['your_acf_field_key_2'];
?>

<div <?php echo get_block_wrapper_attributes(); ?>>
  <h2><?php echo esc_html($field_title); ?></h2>
  <img src="<?php echo esc_url($field_banner); ?>" alt="预览横幅">
</div>

3. 检查ACF区块注册代码 #

确保functions.php中的注册代码直接指向block.json所在的文件夹，避免混用旧版数组注册方式：

add_action('acf/init', 'register_custom_acf_blocks');
function register_custom_acf_blocks() {
  // 注册单个区块
  acf_register_block_type(__DIR__ . '/blocks/your-block');
  
  // 批量注册多个区块可使用循环
  // $block_dirs = glob(__DIR__ . '/blocks/*', GLOB_ONLYDIR);
  // foreach ($block_dirs as $dir) {
  //   acf_register_block_type($dir);
  // }
}

4. 清除缓存并刷新编辑器 #

完成配置修改后，务必执行以下操作：

• 清空WordPress页面缓存（若使用缓存插件）
• 刷新Gutenberg编辑器页面，或重新加载后台
• 必要时重新登录后台，确保配置生效

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