Docxtemplater 中访问根作用域数据的解决方案

在使用 Docxtemplater 处理复杂文档模板时，开发者经常会遇到作用域访问的问题。本文将深入探讨如何正确访问模板中的根作用域数据，特别是在嵌套循环结构中。

问题背景

当处理包含多层嵌套数据的文档模板时，我们经常需要在子作用域中访问根作用域的数据。例如，在一个包含应用列表和问题列表的数据结构中，每个问题都关联到一个应用，我们可能需要在问题循环中引用完整的应用列表。

典型数据结构

{
  applications: [
    { id: 'app1-id', name: '应用1' },
    { id: 'app2-id', name: '应用2' }
  ],
  issues: [
    {
      id: 'issue1-id',
      application_id: 'app1-id',
      name: '问题1',
      applications: [...] // 可能包含部分应用数据
    }
  ]
}

常见问题场景

在模板中，当我们尝试在问题循环内访问完整的应用列表时，可能会遇到以下问题：

1. 直接使用 {#applications} 会优先访问当前问题对象中的 applications 属性
2. 尝试使用 {#root.applications} 可能无法按预期工作
3. 需要根据当前问题的 application_id 过滤出对应的应用

解决方案

Docxtemplater 提供了自定义解析器的能力，我们可以通过配置表达式解析器来实现跨作用域访问。

1. 自定义解析器配置

const expressionParser = require("docxtemplater/expressions.js");

const doc = new Docxtemplater(zip, {
  parser: expressionParser.configure({
    evaluateIdentifier(tag, scope, scopeList, context) {
      // 处理以双下划线开头的标签，表示访问父作用域
      const matchesParent = /^(_{2,})(.*)/g;
      if (matchesParent.test(tag)) {
        const parentCount = tag.replace(matchesParent, "$1").length - 1;
        tag = tag.replace(matchesParent, "$2");
        
        if (parentCount >= 1) {
          // 向上查找指定层级的父作用域
          for (let i = scopeList.length - 1 - parentCount; i >= 0; i--) {
            const s = scopeList[i];
            if (s.hasOwnProperty(tag) && s[tag] != null) {
              const property = s[tag];
              return typeof property === "function" 
                ? property.bind(s) 
                : property;
            }
          }
        }
      }
      // 默认行为
      return scope[tag];
    }
  })
});

2. 模板语法调整

在模板中，我们可以使用双下划线前缀来访问父作用域：

{#issues}
问题名称: {name}
关联应用: {#__applications | where:'id == application_id'}{name}{/}
{/issues}

3. 过滤器实现

为了支持上述功能，我们需要实现 where 过滤器：

const whereCache = {};
expressionParser.filters.where = (input, query) => {
  if (!input) return input;
  
  // 缓存编译结果提高性能
  let get = whereCache[query];
  if (!get) {
    get = expressionParser.compile(query);
    whereCache[query] = get;
  }
  
  return input.filter((item) => get(item));
};

最佳实践

1. 明确作用域层级：在设计模板时，清晰地规划数据的作用域层级关系
2. 使用有意义的命名：避免在不同层级使用相同的属性名
3. 性能优化：对于频繁使用的过滤器（如 where），使用缓存机制
4. 错误处理：在自定义解析器中添加适当的错误处理逻辑

总结

通过自定义 Docxtemplater 的表达式解析器，我们可以灵活地控制作用域访问行为，解决嵌套数据结构中的模板渲染问题。这种方法不仅适用于当前场景，还可以扩展到其他需要跨作用域访问的复杂模板需求中。