label-html-replacer

独立的 HTML 模板替换库。它接收导出的 HTML 字符串和后端 JSON 数据，返回已经填充文本、JsBarcode 条形码和 qrcode 二维码的 HTML 字符串。

支持的模板标记

<!--BARCODE;type=CODE128;field=age;width=40;height=10;hri=true;align=left;hriPrefix=前缀+-->
<!--BARCODE;type=EAN13;field=name;width=40;height=30;hri=true;align=left-->
<!--QRCODE;field=qrcode;width=14.5;height=14.5;ecc=L-->
<!--BARCODE;type=CODE128;field=;value=ABC123;width=40;height=10;hri=true;align=left-->
<!--QRCODE;field=;value=https://example.com/manual;width=14.5;height=14.5;ecc=L-->
{{text}}

条码/二维码标记会被替换为与设计器导出效果一致的 SVG；外层 HTML 和 .el 的毫米尺寸不会改变。使用 field=字段名 时从后端数据取值；field 为空时可用 value=静态内容 直接生成手工内容。二维码纠错等级支持 L/M/Q/H，未指定时默认使用 L。hri=true/false 控制一维码可读文字是否显示，hriPrefix（可选）仅作显示，不会传入 JsBarcode 编码，扫码结果仍是原始字段值或手工内容；EAN13 前缀独立显示在数字下方，其他码制放在文字前。动态列表中的数组字段按单元格顺序读取，并且每个动态列表独立从数组第 0 项开始；多个列表可以安全共用同一个数组字段。

CODE128/CODE39 的可读文字与条纹共用标记指定的 height：渲染时先为文字、间隔和底部留白分配高度，再绘制条纹，动态列表最后一行也不会依赖向下溢出显示文字。正常字号保持 hriFontSize 指定的 pt 值；字号过大时只缩小实际显示字号，为条纹至少保留 20% 高度，不修改模板参数或编码数据。很矮的条码仍需结合实际打印设备验证可扫描性。

EAN13 布局与尺寸诊断

按 GS1 General Specifications 的 EAN13 几何规则，三组共六条守护条向下延长 5X（X 为最窄模块的实际宽度），与字号独立；隐藏文字也保持 5X。保留历史总宽 115 个模块，避免改变同宽元素的 X：95 个编码模块、左侧至少 11X / 右侧至少 7X 静区，剩余 2X 供左/中/右对齐分配。

hriFontSize 使用 pt，默认字号按 10X 的 em 大小及可用字高适配，数字逐位放在固定的 7X 槽位中，不使用 hriStretch。字号超出槽位或字高时只缩小显示并在属性面板提示，绝不因改字号压短普通条。前缀占独立下一行，极长前缀单独缩小以避免越界。

常规零售 EAN13 的 X 范围为 0.264–0.660 mm，标称普通条高为 22.85 × X / 0.330 mm，不包含守护条延长及文字。旧的矮框仍按有限高度显示，并报告条高不足；不会自动改变模板、扩大外框或将其视为合规。连 5X 延长量都无法容纳的极矮框无法渲染，沿用替换器的 strict/onError 错误处理。几何提示不等于扫码或印刷质量认证。

独立库调用者可在打印前使用同源诊断（尺寸支持数字或标记中的数字字符串）：

import { ean13Layout } from 'label-html-replacer'

const layout = ean13Layout({ widthMm: 40, heightMm: 14, hriFontSize: 8 })
console.log(layout.warnings, layout.requiredHeight) // 条高不足、建议框高（mm）

renderable 只表示能否在框内画出图形，不表示符合印刷规范；几何警告不会注入最终 HTML，也不会自动通过 onError 报告，调用方可按 warnings 自行决定是否允许打印。

浏览器项目

npm install label-html-replacer

包内置 TypeScript 声明文件，TypeScript 项目不需要另行安装 @types/label-html-replacer：

import { replaceHtmlFromFiles } from 'label-html-replacer'

const htmlString = replaceHtmlFromFiles(templateHtml, dataJson)

import { replaceHtmlFromFiles } from 'label-html-replacer'

const templateHtml = await fetch('/template.html').then((response) => response.text())
const dataJson = await fetch('/data.json').then((response) => response.text())

const htmlString = replaceHtmlFromFiles(templateHtml, dataJson)
document.querySelector('#preview').srcdoc = htmlString

也可以直接传入接口已经解析好的对象：

const htmlString = replaceHtmlFromFiles(templateHtml, {
  name: 6974770353557,
  age: 6974770353557,
  qrcode: '69747703535576974770353557',
  text: '6974770353557',
  jobs: ['doctor', 'engineer'],
})

对于不使用打包器的页面，先构建库，再引入 dist/replace-html.iife.js：

<script src="./replace-html.iife.js"></script>
<script>
  const htmlString = HtmlTemplateReplacer.replaceHtmlFromFiles(templateHtml, dataJson)
</script>

Node.js

import { replaceHtmlFromFiles } from 'label-html-replacer'

const htmlString = replaceHtmlFromFiles(templateHtml, dataJson)

当前仓库的命令行入口仍然可以读取文件：

node replace-html.js template.html data.json output.html

API

• replaceHtmlFromFiles(templateHtml, dataJson, options)：接收 HTML 字符串和 JSON 字符串/对象，返回 HTML 字符串。
• replaceHtmlContent(html, data, options)：接收已经解析的数据对象，返回 HTML 字符串。
• replaceHtmlFromString：replaceHtmlFromFiles 的语义别名。
• parseMetadataComments(html)：提取 BARCODE/QRCODE 注释及其字符串属性。
• renderBarcode(type, value, options)：直接生成条码或二维码 SVG；一维码可传 hri 和 hriPrefix，其中前缀只影响 HRI 显示。

options.strict 默认为 false，缺失值或非法条码会将对应内容替换为空；设为 true 时抛出编码错误。options.onError(info) 可记录错误信息。