convertTemplate 模板转换器

简介

convertTemplate（v2.2.0）把 打印模板 JSON、业务数据 与 多语言表 合成 打印机可消费的指令数组（text、image、columns、qrcode、barcode、dividing、cutPaper、beep 等）。内置 占位符替换（{{path.to.field}}）、文案键国际化（{{key|l}}）、显隐与排除条件、表格列 / 嵌套列 / 循环行、字体档位（s/m/l/xl… 映射到像素字号）、以及可选的 行号包装、模板字段 UUID 映射、结尾 切纸 / 蜂鸣。

何时使用

• 小票/标签等 先配置模板、再灌数据 的打印链路，需要把设计态结构变成底层指令
• 需要与 多语言模板（template.lang）或默认语言回退（含 en → en-US 前缀匹配）对齐
• 需要 按数据动态显隐 区块（show、hideFields、excludeFields）或 按 loopKey 展开列表
• 调试模板与数据对应关系时，打开 enableUUID 拿到 templatePath ↔ UUID ↔ renderData 映射

示例

// 挂载以工程为准，例如：
const instructions = convertTemplate(
    {
        type: "normal", // 或 "printPic" 等；影响二维码/条码等输出形态
        template: {
            list: [
                { type: "text", param: { text: "{{shopName}}", size: "m", align: 0 } },
                { type: "divider", param: { style: 1 } },
            ],
            lang: { "zh-CN": { WELCOME: "欢迎" } },
            defaultLang: "zh-CN",
        },
        data: { shopName: "测试门店" },
        langKey: "zh-CN",
    },
    {
        fontSize: undefined, // 可选，覆盖默认字号档位
        enableBuzz: false,
        enableLineNumbers: false,
        enableUUID: false,
        columnIndent: "", // 列缩进策略相关
    }
);

// instructions 为指令数组；若 enableUUID，同引用上可能挂 instructions._uuidMappings

API

convertTemplate(config, options = {})

执行完整转换；内部 try/catch，失败返回 [] 并 console.error。

• config (object)：
  • type (string)：输出模式。例如 printPic 下二维码/条码等为扁平结构；默认路径下文本文图等常包一层 params。
  • template (object)：
    • list (array | string)：组件列表；若为 JSON 字符串会先 JSON.parse。
    • lang (object | string)：多语言表，字符串则先解析。
    • defaultLang (string, 可选)：langKey 缺省时使用。
    • 其中 type === "config" 的项不参与打印输出，可用于 param.enableLineNumbers 等开关（与 options.enableLineNumbers 叠加生效逻辑以源码为准）。
  • data (object)：模板占位符数据源；必填（与 list 一并校验，缺则返回 []）。
  • langKey (string, 可选)：选用 template.lang 的键；支持前缀回退（如 en 匹配 en-US）。
• options (object, 可选)：
  • fontSize (object)：档位字号，覆盖内置 DEFAULT_FONT_CONFIG（small / middle / large / extraLarge / xxl / xxxl）。
  • enableBuzz (boolean)：末尾是否追加 beep。
  • columnIndent (number|string)：列缩进样式（与 generateIndent 逻辑相关）。
  • marginLeft (number)：上下文保留字段。
  • enableLineNumbers (boolean)：为指令包一层行号列（部分类型如 cutPaper / beep / dividing 不包装）。
  • enableUUID (boolean)：为模板路径生成 templateUUID 并收集映射。
  • qrCodeGenerator (function, 可选)：未传时尝试 max.converter?.qrCode（带图标二维码等扩展在源码中多为注释占位）。

返回: 指令数组（Array）。若 enableUUID 为真，转换器会在 同一数组引用上挂载 _uuidMappings（含 uuidToTemplate / templateToUuid），供调试或回写；不影响打印机按数组元素遍历的常规用法。

末尾会 追加 cutPaper；在 enableBuzz 时追加 beep。

模板与占位符（约定）

| 语法 | 含义 | |------|------| | {{a.b}} | 从 data 取嵌套字段；仅 string / number 会输出，否则置空 | | {{key|l}} | 从当前解析后的 lang 对象取 key（同上类型限制） | | 无 {{ | 原文本直接输出 |

字号缩写：s / m / l / xl / xxl / xxxl 映射到完整档位键，再解析为像素值（缺省回退 24）。

分割线 divider.param.style：0 空白、1 实线（stroke）、2 虚线（dot）；输出类型名为 dividing。

支持的模板 type（组件）

| type | 说明 | |--------|------| | text | 文本；支持 bold、align、size、边距 upline / bottomBlank | | column | 表格列：表头、按 dataKey 数组展开行、嵌套 level、按 fields 覆写粗体/字号 | | columnInColumn | 嵌套列容器，子项可为 text / image / staticImage / divider / row / column | | image | Base64 图（可带 data: 前缀，输出会去掉前缀） | | staticImage | URL 经占位符解析后走图片逻辑 | | divider | 分割线 → dividing | | qr | 二维码；已是 data:image/png;base64 时转图片指令；否则 printPic 为 qr，否则 qrcode + params | | brcode | 条形码（源码中类型名为 brcode）；printPic 下扁平字段，含 format: symbology 等 | | config | 配置项，不产生指令 |

循环：组件上 loopKey 存在时，对 data[loopKey] 数组逐项展开子转换。

显隐：show === false 不打印；hideFields（列中任一字段在 data 有值则显示该组件）；excludeFields（有值则排除）。具体语义以 PrintConditionChecker 为准。

内部结构（便于读源码）

• ConversionContext：解析 template / lang，持有 fontConfig、行号计数、UUID 双映射表、createUUIDMapping / getUUIDMappings。
• TemplateConverter：遍历 template.list，分发组件、处理 loopKey、行号包装、挂载 _uuidMappings、追加结束指令。
• ComponentConverter：各基础组件 → 指令；非 printPic 且非列子项时多将内容包在 params 内。
• ColumnProcessor：列头、数据行、单行多列权重（仅一列有值时拉满该列权重）、嵌套 columnInColumn / rows。
• StyleProcessor：字号、对齐默认、边距（divider 与其它类型对 upline/bottomBlank 处理略有差异）。
• TemplateUtils：parseTemplateData、getNestedValue、generateIndent 等。
• PrintConditionChecker：shouldPrint 及 hide/exclude 规则。

注意：TemplateUtils.shouldBold 当前实现等价于 !!bold，未使用 obj / lang 参数。
版本号在源码内常量 VERSION 与文件头注释一致；升级时请同步维护。