1. 文档介绍

本文档详细说明基于 JSON 格式的两种打印排版规则：票据打印（如小票、收款）和 标签打印（如商品标签、物流标签）。通过定义标准化的 JSON 属性，可灵活控制打印内容的类型、样式、位置等参数，适用于热敏打印机、标签打印机等设备。

注意事项：
  • 图片类（png/bmp）需遵守大小限制：png 不超过 60K，bmp 不超过 6K
  • 条码类（bc128/CODE128）需遵守字符规则：CODE128A 支持 14 个数字/大写字母，CODE128C 仅支持纯数字
  • 坐标单位：标签打印中 1mm = 8 dot（dot 为打印机最小像素单位）

2. JSON 票据打印排版

票据打印适用于小票、收款等场景，支持标题、文本、图片、条码、二维码、表格、分割线等元素，核心通过 JSON 属性定义打印内容和样式。

2.1 核心属性一览表

属性名 值类型 取值范围/说明 适用场景
type string
  • title：小票标题（默认居中，字体放大1倍）
  • text：普通文本（支持字符串/数组）
  • png：PNG图片（Base64编码或URL，≤60K）
  • bmp：BMP图片（Base64编码或URL，≤6K）
  • qrcode：二维码（最大512字节，size默认"04"）
  • bc128/bc128a：CODE128A（14个数字/大写字母）
  • bc128c：CODE128C（纯数字字符串）
  • div_line："-"分割线（支持居中插入内容）
  • div_star："*"分割线（支持居中插入内容）
  • cut：切刀指令（cont="0"全切，"1"半切）
  • plugin：开钱箱指令
 所有打印元素
align string left（居左，默认）、center（居中）、right（居右） text、qrcode、bc128、图片
bold boolean true（加粗）、false（不加粗，默认） text
size string
  • text："AB"（A=倍宽0-7，B=倍高0-7，默认"00"）
  • qrcode："01"-"09"（默认"04"，数字越大二维码越大）
  • bc128："AB"（A=宽度1-6，B=高度0-9，H=(B+1)*3mm）
 text、qrcode、bc128
both_sides array 数组含2个字符串：[左对齐内容, 右对齐内容]，如["收款金额", "258.00"] 左右对齐文本（如金额显示）
cont string 打印内容（文本/图片URL/Base64/条码内容/分割线插入内容） 所有打印元素
thead array/object
  • object：{表头1: 列宽占比, 表头2: 列宽占比}，如{"名称":"50%","单价":"15%"}
  • array：直接定义列宽，如["20%","80%"]（无表头文本）
 多列表格（表头）
tbody array 表格内容数组，每个子数组对应一行，如[["番茄炒蛋",24,2,48], ["鸡蛋炒鸭蛋",24,1,24]] 多列表格（内容）

2.2 分场景示例（附效果图说明）

示例2：自定义票据示例

展示自定义票据打印排版的各种元素和效果

{
    "print": [
        {"cont": "标题", "type": "title"},
        {"cont": "文本行", "type": "text"},
        {"cont": "文本行加粗", "type": "text", "bold": true},
        {"cont": "字体放大1倍", "type": "text", "size": "11"},
        {"cont": "字体放大2倍", "type": "text", "size": "22"},
        {"cont": "", "type": "text"},
        {"type": "div_line", "cont": "包含标题的多列"},
        {
            "thead": {"名称": "50%", "单价": "20%", "数量": "20%", "金额": "10%"},
            "tbody": [
                ["番茄炒蛋", 24, 2, 48],
                ["西红柿炒番茄", 24, 7, 168],
                ["鸡蛋炒鸭蛋", 24, 1, 24],
                ["野山椒炒土豆", 24, 3, 72]
            ]
        },
        {"cont": "", "type": "text"},
        {"type": "div_line", "cont": "不含标题的多列"},
        {
            "line_space": 5,
            "thead": ["50%", "15%", "15%", "20%"],
            "tbody": [
                ["番茄炒蛋", 24, 2, 48],
                ["西红柿炒番茄", 24, 7, 168],
                ["鸡蛋炒鸭蛋", 24, 1, 24],
                ["野山椒炒土豆", 24, 3, 72]
            ]
        },
        {"cont": "", "type": "text"},
        {"type": "div_star", "cont": "多列字体放大及分割线"},
        {
            "size": "11",
            "line_div": 1,
            "thead": {"序号": "20%", "名称": "80%"},
            "tbody": [
                [1, "番茄炒蛋+萝卜牛腩+小炒肉+例汤"],
                [2, "123456788888"],
                [3, "鸡蛋炒鸭蛋"]
            ]
        },
        {"cont": "", "type": "text"},
        {"type": "div_star", "cont": "CODE128条码示例"},
        {"cont": "123456789", "type": "bc128", "align": "left", "size": "11"},
        {"cont": "123456789", "type": "bc128", "align": "left", "size": "22"},
        {"cont": "123456789", "type": "bc128", "align": "left", "size": "33"},
        {"type": "div_star", "cont": "CODE39条码示例"},
        {"cont": "123456789", "type": "code39", "align": "left", "hri": 2},
        {"cont": "", "type": "text"},
        {"type": "div_star", "cont": "两列左右对齐示例"},
        {"both_sides": ["收款金额", "258.00"]},
        {"both_sides": ["收款金额", "258.00"], "size": "11"},
        {"cont": "", "type": "text"},
        {"type": "div_star", "cont": "二维码示例"},
        {"cont": "http://www.sw-aiot.com", "type": "qrcode", "align": "center"},
        {"cont": "http://www.sw-aiot.com", "type": "qrcode", "align": "center", "size": "60"},
        {"type": "div_star", "cont": "双排二维码示例"},
        {"cont": ["http://www.sw-aiot.com", "1234567890123bb44"], "type": "qrcode", "align": "right", "size": "06"},
        {"cont": "", "type": "text"},
        {"type": "div_star", "cont": "png图片打印示例"},
        {"type": "png", "cont": "http://linxiaoge.oss-cn-shanghai.aliyuncs.com/ic/add/test.png", "align": "center"},
        {"cont": "1", "type": "cut"}
    ]
}

3. JSON 标签打印排版

标签打印适用于商品标签、物流标签等场景，通过 坐标定位 精确控制每个元素的位置，核心属性包括坐标（x/y）、尺寸（w/h）、旋转（r）等。

3.1 核心属性一览表

属性名 值类型 取值范围/说明 适用场景
type string
  • TEXT：文本（支持加粗bold、放大size）
  • QRCODE：二维码（size范围"01"-"09"）
  • BC128：条码（h高度dot，show是否显示字符）
  • BAR：线条（w宽度，h高度）
  • BITMAP：位图（仅支持1位深度BMP，cont为Base64）
 所有标签元素
x/y int 元素左上角坐标（单位dot，1mm=8dot），如x=20表示距左2.5mm 所有标签元素
w/h int
  • TEXT：w=倍宽1-8，h=倍高1-8
  • QRCODE：w=size（"01"-"09"）
  • BC128：w=宽度1-6，h=高度dot（H=(h+1)*3mm）
  • BAR：w=宽度dot，h=高度dot
 对应元素
r int 旋转角度：0（默认）、90、180、270（顺时针） TEXT、QRCODE、BC128、BAR
cont string 打印内容（文本/条码内容/Base64位图） TEXT、QRCODE、BC128、BITMAP
bold boolean true（加粗）、false（不加粗，默认） TEXT
show int BC128专用：1（显示字符）、0（不显示，默认） BC128

3.2 分场景示例（附效果图说明）

示例1：基础文本 + 线条（边框效果）

通过坐标定位实现商品名称、边框线条的精确排版

{
"SIZE": [76, 130], // 标签尺寸：76mm×130mm（608dot×1040dot）
"DIRECTION": 0,
"DENSITY": 10, // 高浓度（清晰）
"label": [
    // 1. 商品名称（居中放大）
    {
        "type": "TEXT",
        "x": 100,
        "y": 20,
        "w": 2,
        "h": 2,
        "r": 0,
        "cont": "无线鼠标"
    },
    // 2. 边框线（顶部）
    {
        "type": "BAR",
        "x": 20,
        "y": 70,
        "w": 568,
        "h": 2
    },
    // 3. 边框线（底部）
    {
        "type": "BAR",
        "x": 20,
        "y": 970,
        "w": 568,
        "h": 2
    }
]
}
示例2：二维码 + 条码（带字符显示）

展示商品二维码、条码（显示字符）的坐标定位和尺寸设置

{
"SIZE": [76, 130],
"DIRECTION": 0,
"DENSITY": 10,
"label": [
    // 1. 二维码（高容错）
    {
        "type": "QRCODE",
        "x": 20,
        "y": 20,
        "e": "H", // 高容错（适合磨损）
        "w": 6,
        "cont": "https://www.example.com/goods/987654321"
    },
    // 2. 条码（显示字符）
    {
        "type": "BC128",
        "x": 20,
        "y": 350,
        "h": 40,
        "show": 1,
        "narrow": 2,
        "wide": 4,
        "cont": "987654321012"
    }
]
}
示例3：旋转文本 + 位图（Logo）

展示文本旋转（如生产日期贴边显示）、BMP位图的使用方法

{
"SIZE": [76, 130],
"DIRECTION": 0,
"DENSITY": 10,
"label": [
    // 1. 生产日期（旋转90度，贴边显示）
    {
        "type": "TEXT",
        "x": 580,
        "y": 200,
        "w": 0,
        "h": 0,
        "r": 90,
        "cont": "生产日期：2024-03-01"
    },
    // 2. LOGO位图（1位深度BMP）
    {
        "type": "BITMAP",
        "x": 20,
        "y": 20,
        "cont": "Qk06AAAAAAAAADYAAAAoAAAAAQAAAAEAAAABABgAAAAAAAQAAADDDwAAww8AAAAAAAAAAAAA//////////////////////////////////////////////////////8="
    }
]
}

4. 完整示例代码

以下提供两个完整JSON示例，分别对应票据打印和标签打印的实际应用场景。

4.1 票据打印完整示例（超市小票）

{
"title": "商为科技-收款小票",
"text": [
    {
        "cont": "门店名称：XX超市",
        "align": "center",
        "bold": true
    },
    "收银员：张三",
    "单号：20240301001",
    "时间：2024-03-01 10:30:45",
    {
        "cont": "--------------------------------",
        "align": "center"
    },
    {
        "cont": "商品名称          单价 数量 金额",
        "bold": true
    },
    {
        "cont": "番茄炒蛋           24   2    48",
        "size": "01"
    },
    {
        "cont": "鸡蛋炒鸭蛋         24   1    24",
        "size": "01"
    },
    {
        "cont": "米饭               2    2     4",
        "size": "01"
    },
    {
        "cont": "--------------------------------",
        "align": "center"
    },
    {
        "both_sides": ["合计金额", "¥76.00"]
    },
    {
        "both_sides": ["实收金额", "¥100.00"]
    },
    {
        "both_sides": ["找零金额", "¥24.00"]
    },
    "付款方式：微信支付",
    {
        "cont": "备注：欢迎再次光临！",
        "align": "center"
    }
],
"qrcode": {
    "cont": "https://www.example.com/pay/20240301001",
    "size": "05",
    "align": "center"
},
"text": "请使用微信扫码支付",
"plugin": "",
"cut": {
    "cont": "0"
}
}

4.2 标签打印完整示例（商品标签）

{
"SIZE": [76, 130], // 标签尺寸：76mm×130mm（608dot×1040dot）
"DIRECTION": 0,
"DENSITY": 10, // 高浓度（清晰）
"SOUND": 2,
"label": [
// 1. 商品名称（放大2倍）
{
"type": "TEXT",
"x": 20,
"y": 20,
"w": 2,
"h": 2,
"r": 0,
"cont": "无线鼠标"
},
// 2. 品牌（默认字体）
{
"type": "TEXT",
"x": 20,
"y": 60,
"w": 0,
"h": 0,
"r": 0,
"cont": "品牌：XX科技"
},
// 3. 规格（默认字体）
{
"type": "TEXT",
"x": 20,
"y": 80,
"w": 0,
"h": 0,
"r": 0,
"cont": "规格：黑色 | 蓝牙5.0"
},
// 4. 价格（加粗，放大1.5倍）
{
"type": "TEXT",
"x": 20,
"y": 110,
"w": 1,
"h": 1,
"r": 0,
"cont": "售价：¥99.00",
"bold": true
},
// 5. 二维码（链接到商品页）
{
"type": "QRCODE",
"x": 20,
"y": 150,
"e": "H", // 高容错（适合磨损）
"w": 6,
"cont": "https://www.example.com/goods/987654321"
},
// 6. 条码（显示字符）
{
"type": "BC128",
"x": 20,
"y": 350,
"h": 40,
"show": 1,
"narrow": 2,
"wide": 4,
"cont": "987654321012"
},
// 7. 生产日期（旋转90度，贴边显示）
{
"type": "TEXT",
"x": 580,
"y": 200,
"w": 0,
"h": 0,
"r": 90,
"cont": "生产日期：2024-03-01"
},
// 8. 有效期（旋转90度）
{
"type": "TEXT",
"x": 580,
"y": 300,
"w": 0,
"h": 0,
"r": 90,
"cont": "有效期至：2026-02-28"
},
// 9. 底部线条（分隔）
{
"type": "BAR",
"x": 20,
"y": 420,
"w": 560,
"h": 5
}
]
}

5. 常见问题（FAQ）

可能原因及解决方案：

  • 1. 二维码内容过长：BC128条码最大支持512字节，若内容超量，需精简链接或文本（如使用短链接）。
  • 2. 尺寸过小：调整size属性（qrcode的size范围"01"-"09"，默认"04"），建议设置为"05"-"07"以保证清晰。
  • 3. 对齐方式错误：确保align为"center"（居中），避免边缘被截断。

核心原因：混淆mm和dot单位，标签打印的x/y属性单位为dot，且1mm = 8dot。

解决方案：

  • 1. 计算坐标：若需在10mm×10mm位置放置元素，需转换为x=80（10×8）、y=80（10×8）。
  • 2. 调整DIRECTION：若整体偏移，检查DIRECTION是否为0（正常方向），1为反向出纸，可能导致位置颠倒。
  • 3. 检查元素尺寸：文本/条码的放大倍数（w/h）会影响实际占用宽度，需预留足够空间。

解决方案：

  • 1. 列宽占比总和：确保thead的列宽占比总和为100%（如50%+15%+15%+20%=100%），否则会自动调整。
  • 2. 内容长度：若某列内容过长（如商品名称），需缩小字体尺寸（调整size属性）或增加列宽占比。
  • 3. 行间距离：通过line_space属性增加行间距离（单位dot，8dot=1mm），避免内容重叠。

需满足2个核心条件：

  • 1. 位图格式：仅支持位深度为1的BMP图（黑白二值图），可通过Windows画图工具生成：打开图片→另存为→格式选择“单色位图（*.bmp;*.dib）”。
  • 2. Base64编码：确保cont属性的值为BMP图的完整Base64编码（无缺失/多余字符），可通过在线工具（如Base64 Guru）转换。