在 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>）。
✅ 正确做法是使用 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; ?>⚠️ 注意事项：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 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 标签被浏览器正确解析与渲染。
立即学习“前端免费学习笔记（深入）”；
