# 打印面单
相关文档:微信小店「打印组件」使用指南
发送指令给打印组件,打印对应的面单
# 注意事项
- 调用前,先从 获取打印报文 或 电子面单取号 接口获取返回的
print_info信息; - 调用完此指令成功后,需要自行调用 电子面单打单成功通知 接口通知平台扭转电子面单状态;
- 若需要流转订单发货状态,需要自行调用 订单发货 接口;
- 若出现面单裁切或面单大小非130*76,则必须在size中传入面单大小。可自行调用获取面单标准模板接口获取标准面单模板大小
# 基础
# 请求参数
# 主结构体 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
*
* <b>GitHub</b>
* <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。