在WordPress中编程创建ACF古腾堡块时如何正确编码特殊字符？

核心原因 #

问题出在块数据构建阶段的转义逻辑错误：直接对整个块数据数组使用wp_slash会破坏结构，而未针对HTML字段单独处理转义，导致serialize_blocks生成的JSON格式不合法（缺少反斜杠的u0022就是JSON转义不完整的表现），进而引发单引号字段保存异常。

解决方案 #

1. 单独处理HTML字段的转义

不要对getBlockData返回的整个数组使用wp_slash，仅针对块属性或innerHTML中的HTML字符串单独转义：

class StageSmall extends Block {
    protected $old_block_data;

    public function __construct($old_block_data) {
        $this->old_block_data = $old_block_data;
    }

    public function getBlockData() {
        // 从旧块提取原始HTML内容
        $raw_html = $this->old_block_data['innerHTML'];
        
        // 仅对HTML内容做转义，适配JSON格式要求
        $escaped_html = wp_slash($raw_html);

        return [
            'blockName' => 'my-plugin/stage-small',
            'attrs' => [
                'content' => $escaped_html,
                // 其他属性按需添加
            ],
            'innerBlocks' => [],
            // 若HTML是块的内部内容，直接赋值给innerHTML字段
            // 'innerHTML' => $escaped_html,
        ];
    }
}

2. 复杂HTML内容的自动转义方案

如果HTML包含大量特殊字符（单引号、嵌套引号等），可以通过json_encode自动处理转义，再去除首尾多余的引号：

// 替代wp_slash的方案
$escaped_html = substr(wp_json_encode($raw_html), 1, -1);

3. 完整导入流程规范

确保块序列化和文章插入的流程无需额外转义操作：

// 旧块映射逻辑
function migrateOldBlockName($old_block_data) {
    $block_map = [
        'old-plugin/stage-small' => StageSmall::class,
        // 其他块映射规则
    ];
    $block_class = $block_map[$old_block_data['blockName']] ?? null;
    return $block_class ? (new $block_class($old_block_data))->getBlockData() : $old_block_data;
}

// 处理旧内容并生成新内容
$old_blocks = parse_blocks($old_post_content);
$new_blocks = array_map('migrateOldBlockName', $old_blocks);
$new_post_content = serialize_blocks($new_blocks);

// 直接插入文章，无需额外转义post_content
wp_insert_post([
    'post_title' => $imported_title,
    'post_content' => $new_post_content,
    'post_status' => 'publish',
]);

关键注意点 #

• 避免对整个块数据数组使用wp_slash：会导致数组键名被错误转义，破坏块结构的合法性
• 依赖serialize_blocks的原生JSON序列化：只要块数据的字符串字段转义正确，该函数会自动生成合法的JSON格式
• 核心字段（如post_title）的转义由wp_insert_post自动处理，无需额外操作

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