本文详解如何使用 Handlebars 的 @key 数据变量，无需预处理或 lookup 辅助，直接渲染三层嵌套对象（类别 → 应用 → 告警类型 → 告警数组）为结构化 HTML 表格，适用于邮件通知等动态内容场景。
本文详解如何使用 handlebars 的 `@key` 数据变量，无需预处理或 lookup 辅助，直接渲染三层嵌套对象（类别 → 应用 → 告警类型 → 告警数组）为结构化 html 表格，适用于邮件通知等动态内容场景。
在构建用户订阅类 HTML 邮件（如应用告警汇总）时，后端常以深度嵌套字典形式组织数据：顶层为业务类别（如 “Requests” 和 “Services”），中间层为动态应用名称（如 “Division Map Layers”），底层为告警类型键（如 “Upvotes”、”Tagged Users”），其值为告警对象数组。Handlebars 原生支持这种结构——关键在于善用 @key 数据变量，它能在 {{#each}} 迭代对象时自动捕获当前键名，从而避免冗余的数据扁平化或自定义 Helper。
核心模板逻辑：三层 {{#each}} + @key 驱动标题
Handlebars 不支持直接遍历对象键名（如 JavaScript 的 Object.keys()），但 {{#each obj}} 在作用于普通对象时，会隐式迭代其可枚举属性值；此时 @key 即为对应属性名。我们据此构建三级嵌套循环：
- 第一层 ：遍历根对象（{{#each this}}），@key 为 “Requests” 或 “Services”
- 第二层 ：遍历每个类别下的应用对象（{{#each this}}），@key 为 “Division Map Layers” 等应用名
- 第三层 ：遍历每个应用下的告警类型对象（{{#each this}}），@key 为 “Upvotes”、”Messages” 等类型名
- 第四层（数组）：对 this（即告警数组）再次 {{#each this}}，直接访问 alert_message 和 createdAt
以下是完整、可运行的模板代码（含语义化 CSS）：
<script id="Template" type="text/template"> <div class="mega-menu"> {{#each this}} <div> <!-- 类别标题 --> <div class="main">{{@key}}</div> <!-- 遍历该类别下的所有应用 --> {{#each this}} <div class="app-div"> <!-- 应用标题 --> <div class="app-name">{{@key}}</div> <!-- 遍历该应用下的所有告警类型 --> {{#each this}} <div class="alert-name">{{@key}}</div> <div class="app-div"> <!-- 告警列表表格 --> <table> <thead> <tr> <th style="width: 600px">Message</th> <th style="width: 100px">Date</th> </tr> </thead> <tbody> <!-- 遍历当前告警类型的每条记录 --> {{#each this}} <tr> <td>{{alert_message}}</td> <td>{{createdAt}}</td> </tr> {{/each}} </tbody> </table> </div> {{/each}} </div> {{/each}} </div> {{/each}} </div> </script> <style> .mega-menu {border: 1px solid aquamarine; padding: 8px; font-family: sans-serif;} .main {font-size: 24px; font-weight: bold; color: red; margin-bottom: 16px;} .app-div {margin-left: 20px;} .app-name {font-size: 18px; font-weight: bold; color: blue; margin-bottom: 8px;} .alert-name {font-size: 16px; font-weight: bold; color: green; margin-bottom: 4px;} table {width: 100%; margin-bottom: 8px;} table, th, td {border: 1px solid lightgrey; border-collapse: collapse;} th, td {padding: 2px 4px;} th {font-size: 12px; text-align: left; color: grey;} </style> <script src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.7.7/handlebars.min.js"></script> <script> const template = Handlebars.compile(document.getElementById('Template').innerHTML); // 示例数据（与问题中完全一致）const data = {"Requests": { /* …… */}, "Services": {/* …… */} }; document.body.innerHTML = template(data); </script>注意事项与最佳实践
- ✅ 无需重构数据 ：本方案完美适配原始嵌套字典结构，不强制要求转为数组或添加 name 字段，保持后端数据契约稳定。
- ⚠️ @key 仅在 {{#each}} 中有效 ：切勿在 {{#if}} 或普通表达式中尝试 {{@key}}，它只在迭代上下文中存在。
- ? 避免命名冲突 ：若数据中某层对象本身含有 key 属性（如 {key: “foo”, value: “bar”}），@key 仍指向字典键名，而非该属性值——这是预期行为，无需担心覆盖。
- ? 邮件兼容性增强 ：实际用于 HTML 邮件时，建议将 CSS 内联（使用工具如 Premailer），并为
添加 role=”presentation” 和 cellspacing=”0″ 提升客户端兼容性。
- ? 调试技巧 ：在模板中临时插入 {{log @key}} 或 {{json this}}（需注册 log/json Helper）可快速验证当前层级数据结构。
通过 @key 驱动的嵌套迭代，Handlebars 将复杂字典转化为清晰、可维护的模板逻辑。它不仅解决了多级动态标题的渲染难题，更体现了声明式模板引擎“数据即结构”的设计哲学——让开发者专注描述 what to render，而非 how to traverse。
