WordPress ACF 输出带 HTML 的字段内容方法

在 WordPress 中使用 Advanced Custom Fields（ACF）时，若 `the_sub_field()` 导致 HTML 标签被转义或未渲染，应改用 `get_sub_field()` 获取原始值，再通过 `echo` 安全输出，确保 HTML 结构正常解析。

在 ACF 的重复字段（Repeater）、灵活内容（Flexible Content）或关系字段（Relationship）等嵌套上下文中，开发者常需在循环内获取子字段值。此时一个关键误区是误用 the_sub_field() —— 该函数直接输出（echo）值并返回 void，而非返回字符串。因此，以下代码存在两个问题：

<?php $process_title = the_sub_field('process_title'); ?>

• the_sub_field() 立即输出字段内容（可能含 HTML），同时赋值给 $process_title 的是 null；
• 后续 echo $process_title 实际输出空值，而原始 HTML 已在赋值时“提前打印”，脱离预期 DOM 结构，常表现为内容出现在页面顶部、引号包裹纯文本，或被 HTML 实体编码（如 <h1> 变成 &lt;h1&gt;）。

✅ 正确做法是使用 get_sub_field()：它返回字段原始值（含未转义 HTML），由开发者自主控制何时、何地、如何输出：

<?php $process_title = get_sub_field('process_title'); ?>
<?php if (!empty($process_title)) : ?>
    <div class="process-title">
        <h1 class="process-heading">
            <?php echo $process_title; ?>
        </h1>
    </div>
<?php endif; ?>

⚠️ 注意事项：

• get_sub_field() 返回的是原始字符串，若字段内容来自用户输入且含不可信 HTML，建议配合 wp_kses_post() 进行白名单过滤，防止 XSS：

  <?php echo wp_kses_post($process_title); ?>

• 切勿在 if 条件中直接调用 the_sub_field()（如 if (the_sub_field('x'))），因其无返回值，条件恒为 false；
• 在 ACF Pro 的 Flexible Content 或 Repeater 循环中，务必确认当前处于有效的 have_rows() / the_row() 上下文，否则 get_sub_field() 将返回 false。

总结：牢记口诀——“the_* 系列用于直出，get_* 系列用于赋值”。当需要将字段值参与逻辑判断、拼接、过滤或嵌入特定 HTML 结构时，必须选用 get_sub_field()（或 get_field()、get_row_layout() 等对应 getter 函数），才能确保 HTML 标签被浏览器正确解析与渲染。