# 打印面单

相关文档:微信小店「打印组件」使用指南

发送指令给打印组件,打印对应的面单

# 注意事项

# 基础

# 请求参数

# 主结构体 PrintRequest

参数 类型 是否必填 描述
command String 指令类型,固定为 'print'
version String 版本号,必传,固定为 '2.0'
requestID String 请求唯一标识,调用方保证唯一,示例:'1234'
taskList Array,Object PrintTask 打印任务列表,包含一个或多个打印任务
printType Number 打印类型,默认为 1。 1:打印固定高度面单 。2:打印任意自定义内容(需传 size 参数,printInfo 为 base64 格式 html)
size Object size 纸张尺寸,printType 为 2 时必传,或面单裁切 / 尺寸非 130*76 时必传
printer String 选中的打印机,对应打印机的 printer.name,示例:'KM_202_NEW'

# PrintTask

参数 类型 是否必填 描述
taskID String 任务唯一标识,调用方保证唯一,示例:'1234'
printInfo String 打印报文,获取打印报文 接口返回的 print_info;printType 为 2 时为 base64 格式 html
printNum Object PrintNum 打印计数信息
splitControl Number 分页控制,可不传,默认 0 。 0:自动分页 。 1:禁止分页。 2:强制分页(内容在第二页)。
showDeliveryLogo Number 快递公司 logo 展示,可不传,默认 1。 0:不展示。 1:展示。
customInfo Object CustomInfo 自定义模板信息
extendData Object 面单补充信息,用于覆盖寄件人信息

# PrintNum

参数 类型 是否必填 描述
curNum Number 打印计数 - 当前张数,示例:1
sumNum Number 打印计数 - 总张数,示例:2

# CustomInfo

参数 类型 是否必填 描述
templateUrl String 自定义模板 url,示例:'https://mmec-shop-1258344707.cos.ap-shanghai.myqcloud.com/shop/public/2023-11-10/a80c0110-3fb8-4190-bdcc-10124b7dd0ce.html'
data Object 模板数据字段(模板中用三个花括号占位,支持换行)

# ExtendData

参数 类型 是否必填 描述
sender Object Sender 寄件人信息

# Sender

参数 类型 是否必填 描述
address Objec AddressInfo 寄件人地址
userName String 寄件人姓名,示例:"张三"
telNumber String 寄件人手机号码,示例:"1311111111"

# AddressInfo

参数 类型 是否必填 描述
provinceName String 省份名称,示例:"广东省"
cityName String 城市名称,示例:"广州市"
countyName String 区县名称,示例:"海珠区"
detailInfo String 详细地址,示例:"TiT 创意园"

# Size

参数 类型 是否必填 描述
width Number 纸张宽度(单位:毫米),示例:76
height Number 纸张高度(单位:毫米),示例:130

# 请求示例

{
const ws = new WebSocket('ws://127.0.0.1:12705');
ws.onopen = () => {
    console.log('与打印组件建立连接成功: ');
    ws.send(JSON.stringify({
        command: 'print',
        version: '2.0', // 必传
        requestID: '1234', // String, 调用方保证唯一
        taskList: [{
            taskID: '1234', // String, 调用方保证唯一
            printInfo: '', // String, [获取打印报文]接口返回的print_info
            printNum: {
                curNum: 1, // 打印计数-当前张数
                sumNum: 2, // 打印计数-总张数
            },
            splitControl: 0 // 可不传, 默认为0, 根据自定义内容自动分页;1,禁止分页;2;强制分页, 内容打印在第二页
            showDeliveryLogo: 0, // 可不传, 默认为1, 传0时不展示快递公司logo
            // 自定义模板信息,没有自定义模板需求可不传
            // 参考模板url:https://mmec-shop-1258344707.cos.ap-shanghai.myqcloud.com/shop/public/2023-11-10/a80c0110-3fb8-4190-bdcc-10124b7dd0ce.html
            customInfo: {
                templateUrl: 'https://mmec-shop-1258344707.cos.ap-shanghai.myqcloud.com/shop/public/2023-11-10/a80c0110-3fb8-4190-bdcc-10124b7dd0ce.html', // 自定义模板url
                // 模板里面定义的数据字段
                // 模板里使用{{{}}},数据可以通过<br>换行
                data: {
                    shopName: "测试小店",
                    productInfo: [
                        {name: "商品1", count: 1, code: "asd", description: "商品描述"},
                        {name: "商品2", count: 2, code: "zxc123", description: "商品<br>描述"}
                    ],
                    imgSrc: "https://www.tencent.com/img/index/tencent_logo.png",
                    productQRcode: "https://www.tencent.com/zh-cn/",
                    productBarcode: "product1"
                }
            },
            // 面单补充信息,用来覆盖寄件人信息,没有这种需求可以不传
            extendData: {
                sender: {
                    address: {
                        provinceName: "广东省",
                        cityName: "广州市",
                        countyName: "海珠区",
                        detailInfo: "TiT创意园"
                    },
                    userName: "张三",
                    telNumber: "1311111111"
                }
            },
        }],
        printType: 1, // Number 打印类型,默认为 1,打印固定高度的面单;如果为2,则打印任意自定义内容,需要传递 size 参数指定纸张尺寸,printInfo 改为传递 base64 格式的 html
        size: {
          width: 76, // 纸张尺寸,单位毫米,printType 为 2 时必传,若是出现面单裁切或面单大小非130*76,则必须传入size
          height: 130
        },
        printer: '_KM_202_NEW_', // 选中的打印机,printer.name
    }))
};

ws.onmessage = (e) => {
    const resp = JSON.parse(e.data || '{}')
    if (resp.command === 'print') {
        console.log('打印结果: ', resp);
        }]
}

# 返回参数

# 主结构体 PrintRequest

参数 类型 是否必填 描述
requestID String 与请求中的 requestID 一致,用于匹配请求与响应,示例:"1234"
command String 指令类型,固定为 "print"
results Array,Object PrintResult 打印任务结果列表,与请求中 taskList 一一对应

# PrintResult

参数 类型 是否必填 描述
taskID String 与请求中的 taskID 一致,标识具体打印任务,示例:"1234"
success Boolean 任务执行结果,true = 打印成功,false = 打印失败
failureReason String 失败原因描述,成功时为空字符串,示例:""

# 返回示例

{
  "requestID": "1234",
  "command": "print",
  "results": [{
      "taskID": "1234",
      "success": true,
      "failureReason": ""
  }]
}

# 自定义模板示例

<div>
  <style>
    .title {
      font-weight: 700;
      /* 长度单位px, 数值等于 mm * 10, 如面单上10mm,为100px */
      height: 100px; 
    }
  </style>
  <div class="title">
  店铺名称 {{ shopName }}!
  </div>
  {{#productInfo}}
  <div>{{name}},{{count}},{{code}}, {{{description}}}</div>
  {{/productInfo}}
  <img src="{{imgSrc}}" width="300" height="50"/>
  <!-- bar-code配置信息见下文 -->
  <bar-code content="{{productBarcode}}" width="300" height="60" config='{"displayValue": true, "textAlign": "left"}' ></bar-code>
  <qr-code content="{{productQRcode}}" width="120" height="120" ></qr-code>
</div>

# 自定义模板语法示例

模板基于mustache.js模板引擎。

# Variables

最基本的标签类型是简单变量。一个 标签会渲染当前上下文中key为name的值。如果没有这样的key,将不会渲染任何内容。 所有变量默认情况下都会进行 HTML 转义。如果你想渲染未转义的 HTML,请使用三个大括号:{ { { name } } } 。你也可以使用 & 来取消转义一个变量。

Data:

{
  "name": "Chris",
  "company": "<b>GitHub</b>"
}

Template:

* {{name}}
* {{age}}
* {{company}}
* {{{company}}}
* {{&company}}

Output:

* Chris
*
* &lt;b&gt;GitHub&lt;/b&gt;
* <b>GitHub</b>
* <b>GitHub</b>

模板中可用a.b的表示方法,来引用data中的属性。 Data:

{
  "name": {
    "first": "Michael",
    "last": "Jackson"
  },
  "age": "RIP"
}

Template:

* {{name.first}} {{name.last}}
* {{age}}

Output:

* Michael Jackson
* RIP

# Sections

根据对应key的值,文本将被渲染零次或多次。 一个section以一个井号开始,以一个斜杠结束。如一个 person section,由 { { #person } } 开始,由 { { /person } } 结束。两个标签之间的文本被称为该section的 "文本块"。一个section的行为由其值决定。

# False Values or Empty List

如果 person 的key不存在,或其值为null, undefined, false, 0, NaN,空字符串或空数组,这个文本块不会被渲染。

Data:

{
  "person": false
}

Template:

Shown.
{{#person}}
Never shown!
{{/person}}

Output:

Shown.

# Non-Empty Lists (循环)

  • 如果key person 存在且其值不为 null、undefined,false或空列表,该文本块将会被渲染一次或多次。
  • 当值为列表时,该列表中的每个项都将会被渲染。通过这种方式,我们可以循环渲染列表。

Data:

{
  "stooges": [
    { "name": "Moe" },
    { "name": "Larry" },
    { "name": "Curly" }
  ]
}

Template:

{{#stooges}}
<b>{{name}}</b>
{{/stooges}}

Output:

<b>Moe</b>
<b>Larry</b>
<b>Curly</b>

当值是一个字符串列表,可以用 . 表示当前项。

Data:

{
  "musketeers": ["Athos", "Aramis", "Porthos", "D'Artagnan"]
}

Template:

{{#musketeers}}
* {{.}}
{{/musketeers}}

Output:

* Athos
* Aramis
* Porthos
* D'Artagnan

# Inverted Sections (取反)

可以用 { { ^section } } 开始一个取反的文本块, 即仅当其值为null、undefined、false、NaN或空列表时,才会渲染取反部分的文本。

Data:

{
  "repos": []
}

Template:

{{#repos}}<b>{{name}}</b>{{/repos}}
{{^repos}}No repos :({{/repos}}

Output:

No repos :(

更多语法可参考mustache.js

# 条形码配置示例

  <bar-code content="{{productBarcode}}" width="300" height="60" config='{"displayValue": true, "textAlign": "left"}' ></bar-code>
参数 类型 描述
width number 条形码整体宽度
height number 条形码整体高度
config string 条形码配置,JSON格式

# 条形码常用配置

选项 默认值 类型 描述
format "auto" (CODE128) String 条码类型
width 2 Number 单条条码宽度
height 100 Number 条码高度
displayValue false Boolean 条码下方是否显示值
text undefined String 覆盖条码下方显示值
fontOptions "" String "bold" 加粗, “italic” 斜体, “bold italic” 加粗且斜体
font "monospace" String 字体
textAlign "center" String 文字的水平位置: "center" 居中, “left” 靠左, “right” 靠右
textPosition "bottom" String 文字的垂直位置 “bottom” 条码下方,“top” 条码上方
textMargin 2 Number 条码与文字之间的间距
fontSize 20 Number 文字字号
background "#ffffff" String (CSS color) 背景颜色
lineColor "#000000" String (CSS color) 条码颜色
margin 10 Number 条码与四周的间距
marginTop undefined Number 条码与上方的间距
marginBottom undefined Number 条码与下方的间距
marginLeft undefined Number 条码与左边的间距
marginRight undefined Number 条码与右边的间距

更多语法可参考JsBarcode