https://open.taobao.com/docs/doc.htm?spm=a219a.7629140.0.0.edQuIb&treeId=409&articleId=106976&docType=1
雲打印交互協議
簡介
- 菜鳥打印組件是以獨立進程和打印機交互，而非作為瀏覽器插件進行打印。
- 瀏覽器或其他客戶端需要通過WebSocket協議與菜鳥打印組件進行通信，支持javascript，java，c/c++，python等常用的語言。
- 若ISV的ERP系統是B/S結構，需要使用以下版本的瀏覽器來更好的支持WebSocket:
- chrome 45及以上（建議使用chrome的最新版本）
協議格式說明
- 請求協議頭:通常，與菜鳥打印組件進行交互，需要發送如下格式的請求協議頭:
|
1
2
3
4
5
|
{
"cmd"
:
"command"
,
"requestID"
:
" unique requestID "
,
"version"
:
"1.0"
}
|
字段說明:
| 字段名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
| cmd | string | 請求的命令名稱 | 是 |
| requestID | string | 請求的ID，用於唯一標識每個請求，每個客戶端自己保證生成唯一ID，如UUID | 是 |
| version | string | 協議當前版本，當前為“1.0” | 是 |
- 響應協議頭:菜鳥打印組件會返回如下格式的響應頭給請求方。
|
1
2
3
4
|
{
"cmd"
:
"command"
,
"requestID"
:
"unique requestID"
}
|
字段說明:
| 字段名 | 類型 | 說明 |
|---|---|---|
| cmd | string | 請求的命令名稱 |
| requestID | string | 發送請求中的ID,原封不動返回，使客戶端能識別出哪個請求對應的響應 |
協議詳解
1. 請求打印機列表協議(getPrinters)
請求協議格式如下:
|
1
2
3
4
5
|
{
"cmd"
:
"getPrinters"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
}
|
響應協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
{
"cmd"
:
"getPrinters"
,
//需要響應的命令名稱，響應獲取打印機列表的響應
"requestID"
:
"123458976"
,
"defaultPrinter"
:
"XX快遞打印機"
,
"printers"
:[
{
"name"
:
"XX快遞打印機"
,
"status"
:
"enable "
,
"type"
:
"thermal"
},
{
"name"
:
"YY物流打印機"
,
"status"
:
"disable"
,
"type"
:
"thermal"
}
]
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| defaultPrinter | string | 默認打印機 |
| name | string | 打印機的名字 |
| status | string | 打印機狀態 : enable可用; disable不可用 |
| type | string | 打印機類型 : thermal為熱敏打印機; other為除熱敏打印機以外的其他類型 |
2. 請求打印機配置協議(getPrinterConfig)
請求協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"getPrinterConfig"
,
"printer"
:
"菜鳥打印機"
,
"version"
:
"1.0"
,
"requestID"
:
"123456789"
}
|
響應協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
{
"cmd"
:
"getPrinterConfig"
,
"requestID"
:
"123456789"
,
"status"
:
"success/failed"
,
"msg"
:
"如果出錯，錯誤原因"
,
"printer"
:{
"name"
:
"打印機名稱"
,
"needTopLogo"
:
false
,
"needBottomLogo"
:
false
,
"horizontalOffset"
:
1
,
"verticalOffset"
:
2
,
"forceNoPageMargins"
:
true
,
// v0.2.8.3 新增字段
"paperSize"
:{
"width"
:
100
,
"height"
:
180
}
}
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| status | string | 標示命令成功或失敗，取值“success”或者“failed” |
| msg | string | 如果出錯，錯誤原因 |
| name | string | 打印機名稱 |
| needTopLogo | bool | 是否需要模板上聯的快遞logo,true為需要,false為不需要 |
| needBottomLogo | bool | 是否需要模板下聯的快遞logo,true為需要,false為不需要 |
| horizontalOffset | float | 水平偏移量 |
| verticalOffset | float | 垂直偏移量 |
| forceNoPageMargins | bool | 強制設置頁面無空邊，true為強制設置頁面無空邊，false為由打印機驅動決定 |
| paperSize | object | 打印機紙張的寬度和高度，單位是毫米,整形值 |
3. 彈窗模式配置打印機協議(printerConfig)
請求協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"printerConfig"
,
"printer"
:
"中通專用打印機"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
}
|
響應協議格式如下:
|
1
2
3
4
5
6
7
|
{
"cmd"
:
"printerConfig"
,
"requestID"
:
"123458976"
,
"printer"
:
"中通專用打印機"
,
"status"
:
"success"
,
//配置成功還是失敗
"msg"
:
"if failed ,some tips, if success,nothing"
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| printer | string | 要配置的打印機 |
| status | string | 消息處理結果,success:成功; failed:失敗 |
| msg | string | 如果成功，則為空;如果失敗，則為失敗原因 |
4. 重置打印機配置協議(resetPrinterPreferences)
此協議是將當前用戶的打印機設置重置為系統全局缺省值，如將打印機首選項配置的偏移、紙張尺寸等重置為系統全局缺省值。
此協議當前對奇銳系列的打印機無效。
請求協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"resetPrinterPreferences"
,
//重置打印機配置命令
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"printer"
:
"菜鳥專用打印機"
}
|
字段名 |類型 |說明 |是否必須
printer |string |打印機名 |是
響應協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"resetPrinterPreferences"
,
//需要響應的命令名稱，響應重置打印機配置命令的響應
"requestID"
:
"123458976"
,
"status"
:
"success"
,
//重置打印機配置成功還是失敗
"msg"
:
"if failed ,some tips, if success,nothing"
}
|
字段名 | 類型 | 說明
printer | string | 打印機名稱
status | string | 標示命令成功或失敗，取值“success”或者“failed”
msg| string | 如果出錯，錯誤原因
5. API模式配置打印機協議(setPrinterConfig)
請求協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
{
"cmd"
:
"setPrinterConfig"
,
"requestID"
:
"123458976"
,
"version"
:”
1.0
”,
"printer"
:
{
"name"
:
"菜鳥模板專用打印機"
"needTopLogo"
:
true
,
"needBottomLogo"
:
false
,
"horizontalOffset"
:
0.5
,
"verticalOffset"
:
0.7
,
"forceNoPageMargins"
:
true
,
// v0.2.8.3 新增字段
"paperSize"
:{
"width"
:
100
,
"height"
:
180
}
}
}
|
| 字段名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
| name | string | 打印機名 | 是 |
| needTopLogo | bool | 是否需要模板上聯的快遞logo,true為需要,false為不需要;默認為true | 否 |
| needBottomLogo | bool | 是否需要模板下聯的快遞logo,true為需要,false為不需要;默認為true | |
| horizontalOffset | float | 設置水平偏移量 | 否 |
| verticalOffset | float | 設置垂直偏移量 | 否 |
| forceNoPageMargins | bool | 強制設置頁面無空邊，true為強制設置頁面無空邊，false為由打印機驅動決定 | |
| paperSize | int | 設置打印機紙張的寬度和高度，單位是毫米 | 否 |
響應協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"setPrinterConfig"
,
"requestID"
:
"123458976"
,
"status"
:
"success"
,
"msg"
:
"if failed ,some tips, if success,nothing"
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| status | string | 消息處理結果。success:成功;failed:失敗 |
| msg | string | 如果成功，則為空;如果失敗，則為失敗原因 |
注:如果要保持某個配置不變，應省略對應的配置字段。
6. 發送打印/預覽數據協議(print)
注：因為打印機質量乘次不齊，建議 1 個 task 使用 一個 document，可以有效避免重打問題；
非加密請求協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
{
"cmd"
:
"print"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"task"
: {
"taskID"
:
"7293666"
,
"preview"
:
false
,
"printer"
:
""
,
"previewType"
:
"pdf"
,
"firstDocumentNumber"
:
10
,
"totalDocumentCount"
:
100
,
"documents"
: [{
"documentID"
:
"0123456789"
,
"contents"
: [{
"data"
: {
"recipient"
: {
"address"
: {
"city"
:
"杭州市"
,
"detail"
:
"良睦路999號樂佳國際大廈2號樓小郵局"
,
"district"
:
"余杭區"
,
"province"
:
"浙江省"
,
"town"
:
""
},
"mobile"
:
"13012345678"
,
"name"
:
"菜鳥網絡"
,
"phone"
:
"057112345678"
},
"routingInfo"
: {
"consolidation"
: {
"name"
:
"杭州"
,
"code"
:
"hangzhou"
},
"origin"
: {
"name"
:
"杭州"
,
"code"
:
"POSTB"
},
"sortation"
: {
"name"
:
"杭州"
},
"routeCode"
:
"123A-456-789"
},
"sender"
: {
"address"
: {
"city"
:
"杭州市"
,
"detail"
:
"文一西路1001號阿里巴巴淘寶城5號小郵局"
,
"district"
:
"余杭區"
,
"province"
:
"浙江省"
,
"town"
:
""
},
"mobile"
:
"13012345678"
,
"name"
:
"阿里巴巴"
,
"phone"
:
"057112345678"
},
"shippingOption"
: {
"code"
:
"COD"
,
"services"
: {
"SVC-COD"
: {
"value"
:
"200"
},
"TIMED-DELIVERY"
: {
"value"
:
"SEVERAL-DAYS"
},
"PAYMENT-TYPE"
: {
"value"
:
"ON-DELIVERY"
},
"SVC-INSURE"
: {
"value"
:
"1000000"
},
"SVC-PROMISE-DELIVERY"
: {
"promise-type"
:
"SAMEDAY_DELIVERY"
}
},
"title"
:
"代收貨款"
},
"waybillCode"
:
"0123456789"
},
"signature"
:
"19d6f7759487e556ddcdd3d499af087080403277b7deed1a951cc3d9a93c42a7e22ccba94ff609976c5d3ceb069b641f541bc9906098438d362cae002dfd823a8654b2b4f655e96317d7f60eef1372bb983a4e3174cc8d321668c49068071eaea873071ed683dd24810e51afc0bc925b7a2445fdbc2034cdffb12cb4719ca6b7"
,
"templateURL"
:
"http://cloudprint.cainiao.com/cloudprint/template/getStandardTemplate.json?template_id=101&version=4"
},
{
"data"
: {
"value"
:
"測試字段值需要配合自定義區變量名"
},
}]
}]
}
}
|
加密請求協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
{
"cmd"
:
"print"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"task"
: {
"taskID"
:
"7293666"
,
"preview"
:
false
,
"printer"
:
""
,
"previewType"
:
"pdf"
,
"firstDocumentNumber"
:
10
,
"totalDocumentCount"
:
100
,
"documents"
: [{
"documentID"
:
"0123456789"
,
"contents"
: [{
"encryptedData"
:
"AES:sqZphfylZBNd8EHQAFCfgYmP69kdZ1iQomiXHR11Dr38FHIp9OYQ/47HUcTzUgu2YQ66yX1Kc3ZGELxU8LJpCy8HQ5UUYVbaSF6N+ClfI3UsItD/w90abYo3rMjiISe59jlU7P7XadDlSHRVTsW1lzUQeW2b7umBbrf5nsQhmgnsRs4Xd71/T5Xs0odYZOrXuodfoohygkbMkDb/X7EpGYwn+nK1LwxI16kf5GQbHfnUN4S1NTHK6KQSOYjwU1G5O5jdknszEB3bHx1EwNHg4XccOb8Oppryjd99yZkGMWIhJd2ctn9ipxBD+deCyu4dL9V3G3N16pJ8yv7KWMo5TJqNeIQSr8XE9fjDIeJ4MUAkFM4ykPH2Ta9uJgchOPn7Fg4phTesr2d+PnQUNFIAP/jMNdyT00/d/TnMa/XqyHfdsn1612K3ea7WU6km99FIb3a8L+TSFqRl4Km77j3bRld9FXW/evf8IAWQCTfrfYYn26dzrAcbBbmV80nVLAc//X1eWefanQZtN6L3qgjrdlkgJfO4v/TWBa6TUT8zOA0lbrCO/mnbclHVMeiWKp9Mr8QUa4uf57vasNsTZZ6nW/FnLUa+9V3IkiazpR6oR2SJzgWxnCF1y7haCaUHxiwYw0JDL41eaXeT9wkOYLVFSIeWrCznanWxLy6/D04cEinMK3v7bkedp0ly7vPiJXhkTV+eQ7eQfuIsknIO7msMt8f/+erA1o8LXShYP3THeU8a5w4ULmq4Iw8/n0MKTvM1MbvFu5/b5R5LZJxcTmgCJHhqa85kI5DuBfaEtksNKB8VuuV2Avlmz52jU0FFCSTbRkGLyVHyNTV5U/TyYnwiyiC0BY1fEN051CkgRxEIRpUFdLtEPb1RUy8MVmFBRONM335mslSzpmPz4FzrNSe1mRxcD2LzXQ8ueKbAnppfLVuU1v9Veg6ReEZUdqEdtfUWobBpQD/JFntXrYAOl5t2ZPfp/vejMY61P3AuCydTzdnsivvzUSuZQ+ilNBxlieHgCwl9NUYpqa1CARXAcHW9k3h3rqHBMJebI5/rLqwCT7XkZo7WAX0IorxmnYKvsxpXFRgykNdyQoXKEev+jLGr2ilePxZOqg0FnhA/qhhh3V4GEIsdGE/FfS+IEGLgR2VFnDVqS+/6yg6Z/Q3/Z/4Ao7HnbfZEezczv3Zh0HXw/vW9cW7JyaoGc074XFSMlpqEaBoCxulvmSJewWX7T/6SSWOe2zpLAphyGBHlwjb3+HrpbfZYMkHpzqztnx1KxRijw3ZyftKo2IBDmGmlbteufqsinJQSkc2biS0aCNF4nWmMEpCusJH+1fo+h5FFxC6D4qq964NLlpYo9506O6wEdSLMtyjwUjGc0awrCOCBqCmCQKcmKJ99NsghyxtK4Xj3brec87mCaUow/8agH3F/cR+cR7i+0kedyCSy/LcgU9Y="
,
"signature"
:
"MD:jcPOktTeXcdW3+arHpaOBA=="
,
}]
}]
}
}
|
下面將進一步說明菜鳥打印組件是如何將這些動態獲取的數據填充到模板中的（下面所描述的解析工作均是菜鳥打印組件自動完成，這里只是為了加深理解而進行的說明）。
1、在上述報文中，自定義模板數據為:
- url:https://cloudprint.cainiao.com/template/802，對應的就是一個動態模板，將這個url發送給菜鳥打印組件后，打印組件會自動解析下載這個模板，其內容如下:。可以看到，有一個動態變量"<%=_data.goodsInfo%>"。（注:這是一個虛擬的url，真實的url應該調用top接口獲得）
|
1
2
3
4
5
6
7
8
|
<layout left=
"35.17"
top=
"10.81"
width=
"26"
height=
"6"
editor:_for_=
"element_text_D79E4BA7828B4241"
>
<text
value=
"<%=_data.goodsInfo%>"
style=
"wrap:true;direction:horizontal;letterSpacing:0;fontSize:9;lineHeight:5;fontItalic:false;fontFamily:宋體;fontUnderline:false;valign:top;align:left;fontWeight:false"
/>
</layout>
</page>
|
- data:也就是要打印的數據，這些會替換模板中的變量。在data中，變量goodsInfo的值為“我是你要的商品芭比娃娃。。。”。
2、那么將上述報文發送給菜鳥打印組件后，生成的模板數據如下:
|
1
2
3
4
5
6
7
8
|
<layout left=
"35.17"
top=
"10.81"
width=
"26"
height=
"6"
editor:_for_=
"element_text_D79E4BA7828B4241"
>
<text
value=
"我是你要的商品芭比娃娃。。。"
style=
"wrap:true;direction:horizontal;letterSpacing:0;fontSize:9;lineHeight:5;fontItalic:false;fontFamily:宋體;fontUnderline:false;valign:top;align:left;fontWeight:false"
/>
</layout>
</page>
|
3、可以看到，原始的動態模板中的value值被替換為了“我是你要的商品芭比娃娃。。。”，打印組件將會打印生成后的靜態模板。
| 字段名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
| taskID | string | 打印機任務ID，每個打印任務會分配不同的且唯一的ID | 是 |
| notifyType | array | 打印通知類型:“render”, “print” [“render”] : 僅渲染響應 notify [“print”] : 僅出紙響應 notify “render”, “print” : 渲染完成會響應 notify && 出紙完成后會響應 notify [] : 不允許 注:如果notifyType沒有指定，默認為[“render”, “print”] |
否 |
| preview | bool | 是否預覽.true為預覽,false為打印 | 是 |
| previewType | string | 屬性取值“pdf” or “image” 預覽模式，是以pdf還是image方式預覽，二選一，此屬性不是必選，默認以pdf預覽。 | 否 |
| firstDocumentNumber | int | task 起始 document 序號 | 否 |
| totalDocumentCount | int | task document 總數 | 否 |
| printer | string | 打印機名，如果為空，會使用默認打印機 | 否 |
| templateURL | string | 模板文件url | 是 |
| signature | string | 模板與數據的簽名 | 否 |
| documents | array | 文檔數組，每個數據表示一頁 | 是 |
| documentID | string | 文檔的唯一ID，對於菜鳥標准面單來講，就是面單號;如果是自定義模板，需要保證唯一 | 是 |
| data | Json Object | 模板需要的打印數據 | 是 |
“previewType”:“pdf/image”,//如果是預覽模式，是以pdf還是image方式預覽，二選一，此屬性不是必選，默認以pdf預覽。
響應協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
{
"cmd"
:
"print"
,
"requestID"
:
"123458976"
,
"taskID"
:
"1"
,
"status"
:
"success"
,
//如果是打印，表示打印任務提交成功，如果是預覽，表示預覽PDF文件生成成功
//如果是預覽並且預覽模式是previewType:image，會返回這個屬性，表示預覽圖片的URL地址，如果是打印命令，不返回此屬性
"previewImage"
: [
http:
//127.0.0.1/preview1.jpg,
http:
//127.0.0.1/preview2.jpg,
http:
//127.0.0.1/preview3.jpg
]
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| taskID | string | 打印機任務ID，每個打印任務會分配不同的且唯一的ID |
| status | string | 如果是打印，表示打印任務提交成功，如果是預覽，表示預覽PDF文件生成成功 |
| previewURL | string | 可預覽的PDF文件URL路徑 |
| previewImage | string[] | 預覽image的URL路徑，是一個字符串數組 |
備注:
* 如果是打印命令，只是表示將打印任務提交到打印隊列，會快速返回。
* 如果是預覽命令，需要將預覽文件生成，才會返回，需要一段等待時間。
7. 請求任務打印狀態協議(getTaskStatus)
請求協議格式如下:
|
1
2
3
4
5
6
7
8
9
|
{
"cmd"
:
"getTaskStatus"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"taskID"
:[
"12311"
,
"12312"
]
}
|
| 字段名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
| taskID | json數組 | 打印機任務ID列表 | 是 |
響應協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
{
"cmd"
:
"getTaskStatus"
,
"requestID"
:
"123458976"
，
"printStatus"
:[
{
"taskID"
:
"12312"
,
"detailStatus"
:[
{
"documentID"
:
"9890000112011"
,
"status"
:
"success"
,
"msg"
:
"if failed ,some tips, if success or pending nothing"
,
"printer"
:
"中通打印機A"
}
]
}
]
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| taskID | string | 打印機任務ID，每個打印任務會分配不同的且唯一的ID |
| documentID | string | 文檔的唯一ID，對於菜鳥標准面單來講，就是面單號;如果是自定義模板，需要保證唯一 |
| status | string | 任務狀態:success成功;failed失敗;pending，提交到打印機打印隊列 |
| msg | string | 如果任務狀態為成功或掛起為空，如果任務狀態為失敗，則為失敗原因。 |
| printer | string | 負責打印的打印機名 |
8. 獲取文檔打印狀態協議(getDocumentStatus)
請求協議格式如下:
|
1
2
3
4
5
6
7
8
9
|
{
"cmd"
:
"getDocumentStatus"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"documentIDs"
:[
"9789173491296"
,
"9890000112011"
]
}
|
| 字段名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
| documentIDs | array | 文檔的唯一ID數組 | 是 |
響應協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
{
"cmd"
:
"getDocumentStatus"
,
"requestID"
:
"123458976"
,
"printStatus"
:[
{
"documentID”:”
9890000112011
”,
"status"
:
"success"
,
"msg"
:
"if failed then tips, if success or pending then nothing"
,
"printer"
:
"中通打印機A"
}
……
]
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| documentID | string | 文檔的唯一ID，對於菜鳥標准面單來講，就是面單號;如果是自定義模板，需要保證唯一 |
| status | string | 面單狀態:success成功;failed失敗;pending，提交到打印機打印隊列 |
| msg | string | 如果任務狀態為成功或掛起為空，如果任務狀態為失敗，則為失敗原因。 |
| printer | string | 負責打印的打印機名 |
9. 打印結果通知協議(notifyPrintResult)
通知協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
{
"cmd"
:
"notifyPrintResult"
,
"printer"
:
"中通打印機A"
,
"taskID"
:
"1"
,
"taskStatus"
:
"printed"
,
"printStatus"
:[
{
"documentID”:”
9890000112011
”,
"status"
:
"success"
,
"msg"
:"
if
failed,some tips,
if
success ,nothing”,
"detail"
:
"錯誤信息的補充描述"
}
]
}
|
| 字段名 | 類型 | 說明 |
|---|---|---|
| documentID | string | 文檔的唯一ID，對於菜鳥標准面單來講，就是面單號;如果是自定義模板，需要保證唯一 |
| taskStatus | string | 任務狀態: failed : 失敗; rendered: 渲染完成 printed : 出紙完成 注：當打印出紙之后才會發送通知並且只通知一次 |
| status | string | 任務狀態:success成功;failed 失敗,canceled 取消 （當一個任務中的一個文檔打印失敗，任務中其他的文檔打印狀態為“canceled”狀態） |
| msg | string | 如果任務狀態為成功或掛起為空，如果任務狀態為失敗，則為失敗原因概要。 |
| detail | string | 錯誤信息的補充描述 |
| printer | string | 負責打印的打印機名 |
| taskID | string | 任務ID，每個打印任務會分配不同的且唯一的ID |
10. 獲取全局配置信息(getGlobalConfig)
請求協議格式如下:
|
1
2
3
4
5
|
{
"cmd"
:
"getGlobalConfig"
,
"requestID"
:
"12345678901"
,
"version"
:
"1.0"
}
|
響應協議格式如下:
|
1
2
3
4
5
6
7
|
{
"cmd"
:
"getGlobalConfig"
,
"requestID"
:
"12345678901"
,
"status"
:
"success"
,
"msg"
:
"return nothing when success, return some tips when failed"
,
"notifyOnTaskFailure"
:
true
}
|
字段解釋:
| 字段名 | 類型 | 說明 |
|---|---|---|
| status | string | 表示命令成功或失敗，取值“success”或者“failed” |
| msg | string | 如果出錯，錯誤原因 |
| notifyOnTaskFailure | bool | 打印任務失敗時是否需要通知（彈出對話框提醒用戶打印失敗原因並默認暫停當前打印機的打印），true為需要，false為不需要 |
11. 設置全局配置信息(setGlobalConfig)
請求協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"setGlobalConfig"
,
"requestID"
:
"12345678901"
,
"version"
:
"1.0"
,
"notifyOnTaskFailure"
:
true
}
|
響應協議格式如下:
|
1
2
3
4
5
6
|
{
"cmd"
:
"setGlobalConfig"
,
"requestID"
:
"12345678901"
,
"status"
:
"success"
,
"msg"
:
"return nothing when success, return some tips when failed"
}
|
字段解釋:
| 字段名 | 類型 | 說明 |
|---|---|---|
| status | string | 表示命令成功或失敗，取值“success”或者“failed” |
| msg | string | 如果出錯，錯誤原因 |
| notifyOnTaskFailure | bool | 打印任務失敗時是否需要通知（彈出對話框提醒用戶打印失敗原因並默認暫停當前打印機的打印），true為需要，false為不需要 |
返回頁首
12. 獲取打印組件版本信息(getAgentInfo)
請求協議格式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
{
"cmd"
:
"getAgentInfo"
,
"requestID"
:
"12345678901"
,
"version"
:
"1.0"
}
響應協議格式如下:
{
"cmd"
:
"getAgentInfo"
,
"requestID"
:
"12345678901"
,
"status"
:
"success"
,
"msg"
:
"return nothing when success, return some tips when failed"
,
"version"
:
"0.2.8.3"
// 打印組件版本
}
|
字段解釋:
| 字段名 | 類型 | 說明 |
|---|---|---|
| status | string | 表示命令成功或失敗，取值“success”或者“failed” |
| msg | string | 如果出錯，錯誤原因 |
| version | string | 版本號 |
注意事項
在用JavaScript，C#，C++，delphi，JAVA使用webSocket的過程中，要以全局對象的形式存在，不要每次發送交互請求去創建一個對象，做到webSocket對象重用，和打印組件保持長連接。不然會導致各種意想不到的問題!
在同打印組件交互過程中的json報文，如果文本中包含了特殊字符，比如常見的回車，引號等，需要對特殊字符做轉義，詳細請參考: http://www.json.org/json-zh.html 。
使用示例
1 JavaScript使用示例
var webSocket;
//備注:webSocket 是全局對象，不要每次發送請求都去創建一個，做到webSocket對象重用，和打印組件保持長連接。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
function doConnect()
{
//如果是https的話，端口是13529
//socket = new WebSocket('wss://localhost:13529');
// 打開Socket
socket.onopen = function(event)
{
// 監聽消息
socket.onmessage = function(event)
{
console.log(
'Client received a message'
,event);
};
// 監聽Socket的關閉
socket.onclose = function(event)
{
console.log(
'Client notified socket has closed'
,event);
};
};
}
/***
*
* 獲取請求的UUID，指定長度和進制,如
* getUUID(8, 2) //"01001010" 8 character (base=2)
* getUUID(8, 10) // "47473046" 8 character ID (base=10)
* getUUID(8, 16) // "098F4D35"。 8 character ID (base=16)
*
*/
function getUUID(len, radix) {
var chars =
'0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
.split(
''
);
var uuid = [], i;
radix = radix || chars.length;
if
(len) {
for
(i =
0
; i < len; i++) uuid[i] = chars[
0
| Math.random()*radix];
}
else
{
var r;
uuid[
8
] = uuid[
13
] = uuid[
18
] = uuid[
23
] =
'-'
;
uuid[
14
] =
'4'
;
for
(i =
0
; i <
36
; i++) {
if
(!uuid[i]) {
r =
0
| Math.random()*
16
;
uuid[i] = chars[(i ==
19
) ? (r &
0x3
) |
0x8
: r];
}
}
}
return
uuid.join(
''
);
}
/***
* 構造request對象
*/
function getRequestObject(cmd) {
var request =
new
Object();
request.requestID=getUUID(
8
,
16
);
request.version=
"1.0"
;
request.cmd=cmd;
return
request;
}
/***
* 獲取自定義區數據以及模板URL
* waybillNO 電子面單號
*/
function getCustomAreaData（var waybillNO）{
//獲取waybill對應的自定義區的JSON object，此處的ajaxGet函數是偽代碼
var jsonObject = ajaxGet(waybillNO);
var ret =
new
Object();
ret.templateURL=jsonObject.content.templateURL;
ret.data=jsonObject.content.data;
return
ret;
}
/***
* 獲取電子面單Json 數據
* waybillNO 電子面單號
*/
function getWaybillJson（var waybillNO）{
//獲取waybill對應的json object，此處的ajaxGet函數是偽代碼
var jsonObject = ajaxGet(waybillNO);
return
jsonObject;
}
/**
* 請求打印機列表demo
* */
var request = getRequestObject(
"getPrinters"
);
webSocket.send(JSON.stringify(request));
/**
* 彈窗模式配置打印機
* */
var request = getRequestObject(
"printerConfig"
);
webSocket.send(JSON.stringify(request));
/**
* 打印電子面單
* printer 指定要使用那台打印機
* waybillArray 要打印的電子面單的數組
*/
function doPrint(var printer,var waybillArray)
{
var request = getRequestObject(
"print"
);
request.task =
new
Object();
request.task.taskID = getUUID(
8
,
10
);
request.task.preview =
false
;
request.task.printer = printer;
var documents =
new
Array();
for
(i=
0
;i<waybillArray.length;i++) {
var doc =
new
Object();
doc.documentID = waybillArray[i];
var content =
new
Array();
var waybillJson = getWaybillJson(waybillArray[i]);
var customAreaData = getCustomAreaData(waybillArray[i]);
content.push(waybillJson,customAreaData);
doc.content = content;
documents.push(doc);
}
socket.send(JSON.stringify(request));
}
/**
* 響應請求demo
* */
websocket.onmessage = function (event) {
var response = eval(event.data);
if
(response.cmd ==
'getPrinters'
) {
getPrintersHandler(response);
//處理打印機列表
}
else
if
(response.cmd ==
'printerConfig'
) {
printConfigHandler(response);
}
};
|
2 C++使用示例
c++ Demo使用動態鏈接庫的方式。
2.1 動態鏈接庫
PrinterManager提供以下接口,調用約定 stdcall 方式:
|
1
2
3
4
|
int
initPrinterManager(
const
char
*url);
void
setRecvDataCallback(_onMessage_func func);
int
sendMessage(
const
char
*message);
int
closePrinterManager();
|
說明:需要輸入url的地址才能正常調用initPrinterManager，否則報錯;
參數:const char *url指向WEBSOCKET的地址，如“ws://127.0.0.1:13528”
返回值:整型，成功返回0，返回-1表示初始化失敗，返回-2表示重復初始化錯誤，返回-3表示未輸入url
注意:每載入一次dll，只調用一次initPrinterManager()，重復調用返回-1.
void setRecvDataCallback(_onMessage_func func);
功能:設定回調函數，此回調函數作用:如果接收到數據則調用回調函數
返回值:無
傳入參數:_onMessage_func func:函數指針，類型為typedef void(_onMessage_func)(const char message)，
C++中對應回調函數例子:
void handle_message(const char* message)
{
printf(“>>> %s\n”, message);
}
int sendMessage(const char *message);
功能:發送數據給打印客戶端
返回值:整型，成功返回0，返回-1表示websocket未連接
傳入參數:const char *message:字符串類型(傳入的字符串必須確保已經是UTF-8編碼)
int closePrinterManager()
功能:關閉websocket
返回值:整型，成功返回0，返回-1表示websocket在調用前已關閉或未初始化
注意:不要重復關閉，否則返回-1.
以獲取打印機列為例:
獲取打印機列表命令如下:
|
1
2
3
4
5
|
{
"cmd"
:
"getPrinters"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
}
|
DEMO中采用cJSON開源庫作為生成JSON數據的工具:
|
1
2
3
4
5
6
7
8
9
10
11
|
string getRequestObject()
{
cJSON *root;
root = cJSON_CreateObject();
cJSON_AddStringToObject(root,
"cmd"
,
"getPrinters"
);
cJSON_AddStringToObject(root,
"requestID"
,
"123458976"
);
cJSON_AddStringToObject(root,
"version"
,
"1.0"
);
string str = string(cJSON_Print(root));
cJSON_Delete(root);
return
str;
}
|
構造打印指令代碼如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
string getPrintRequestObject()
{
cJSON *root;
root = cJSON_CreateObject();
cJSON_AddStringToObject(root,
"cmd"
,
"print"
);
cJSON_AddStringToObject(root,
"requestID"
,
"123458976"
);
cJSON_AddStringToObject(root,
"version"
,
"1.0"
);
cJSON *task = cJSON_CreateObject();
cJSON_AddStringToObject(task,
"taskID"
,
"1"
);
cJSON_AddFalseToObject(task,
"preview"
);
cJSON *documents = cJSON_CreateObject();
cJSON_AddStringToObject(documents,
"ducumentID"
,
"9890106027"
);
cJSON *contents = cJSON_CreateArray();
//data為電子面單數據，TOP接口返回數據可直接獲得
cJSON_AddItemToArray(contents, cJSON_CreateString(data.c_str()));
cJSON_AddItemToObject(documents,
"contents"
, contents);
cJSON_AddItemToObject(task,
"documents"
, documents);
cJSON_AddItemToObject(root,
"task"
, task);
//調用cJSON_PrintBuffered則去除換行符
string str = string(cJSON_Print(root));
cJSON_Delete(root);
return
str;
}
|
詳細用法請下載示例代碼查看。
返回頁首
3 JAVA使用示例
java使用websocket需要引入第三方庫 下載地址 。
|
1
2
3
4
5
|
<dependency>
<groupId>org.java-websocket</groupId>
<artifactId>Java-WebSocket</artifactId>
<version>
1.3
.
0
</version>
</dependency>
|
自己創建一個websocket管理類，需要繼承自第三方類庫的WebSocketClient:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
import
java.net.URI;
import
java.net.URISyntaxException;
import
org.java_websocket.client.WebSocketClient;
import
org.java_websocket.drafts.Draft;
import
org.java_websocket.drafts.Draft_17;
import
org.java_websocket.handshake.ServerHandshake;
public
class
WebSocketClientManager
extends
WebSocketClient {
static
WebSocketClientManager webSocket =
null
;
public
static
void
main(String[] args)
throws
URISyntaxException {
webSocket =
new
WebSocketClientManager(
new
URI(uri),
new
Draft_17());
//建立連接
webSocket.connect();
}
public
WebSocketClientManager(URI serverUri, Draft draft) {
super
(serverUri, draft);
}
@Override
public
void
onOpen(ServerHandshake serverHandshake) {
//獲取打印機列表
String getPrinterListCmd =
"{\"requestID\":\"12345678901234567890\",\"verson\":\"1.0\",\"cmd\":\"getPrinters\"}"
;
webSocket.send(getPrinterListCmd);
//發送打印任務
String printCmd =
"打印任務報文，內容過長此處不粘貼"
;
webSocket.send(printCmd);
}
//WebSocket回調函數
@Override
public
void
onMessage(String message) {
//TODO 對打印服務返回的數據進行處理
System.out.println(message);
}
@Override
public
void
onClose(
int
i, String s,
boolean
b) {
}
@Override
public
void
onError(Exception e) {
}
}
|
4 C#使用示例
使用C#官方提供的 websocket 庫，根據上面說明的菜鳥打印協議進行開發。
5 DELPHI使用示例
delphi通過動態調用C++ DLL來實現，只需要一個PrinterManager.dll，文件即可調用，所有調用接口約定 stdcall 方式，請下載相關源代碼 和 動態庫。
動態接口說明如下:
|
1
2
3
4
|
int
initPrinterManager();
void
setRecvDataCallback(_onMessage_func func);
int
sendMessage(
const
char
*message);
int
closePrinterManager();
|
1、int initPrinterManager();
功能:初始化websocket，無需輸入IP和端口，自動連接打印客戶端
返回值:整型，成功返回0，返回-1表示初始化失敗，返回-2表示重復初始化錯誤
注意:每載入一次dll，只調用一次initPrinterManager()，重復調用返回-1.
2、void setRecvDataCallback(_onMessage_func func);
功能:設定回調函數，此回調函數作用:如果接收到數據則調用回調函數
返回值:無
傳入參數:_onMessage_func func:函數指針，類型為
typedef void(_onMessage_func)(const char message)，
C++中對應回調函數例子:
void handle_message(const char* message)
{
printf(“>>> %s\n”, message);
}
3、int sendMessage(const char *message);
功能:發送數據給打印客戶端
返回值:整型，成功返回0，返回-1表示websocket未連接，返回-2表示消息不是UTF-8格式
傳入參數:const char *message:字符串類型(傳入的字符串必須確保已經是UTF-8編碼)
4、:int closePrinterManager()
功能:關閉websocket
返回值:整型，成功返回0，返回-1表示websocket在調用前已關閉或未初始化
注意:不要重復關閉，否則返回-1.
DELPHI下使用方式如下:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
|
unit Unit1;
interface
uses Windows, Messages, SysUtils, Classes, Graphics,Controls, Forms, Dialogs,StdCtrls;
type
PbackFunc = procedure(message1:pchar); Stdcall;
TForm1 =
class
(TForm)
Button1: TButton;
procedure Button1Click(Sender: TObject);
function tbnewcainiao(sid, sappkey, smemo: string): string;
private
{ Private declarations }
public
{ Public declarations }
end;
var
Form1: TForm1;
implementation
{$R *.DFM}
procedure TForm1.Button1Click(Sender: TObject);
var s:string;
begin
s:=tbnewcainiao(
'111'
,
'111'
,
'222'
);
//showmessage(s);
end;
//測試打印客戶端
function TForm1.tbnewcainiao(sid, sappkey, smemo: string): string;
//打印客戶端的回調函數
procedure handle_message(
const
pardata:pAnsiChar);stdcall;
begin
//注:回調函數由子線程調用，不可重復調用showmessage（）函數
//showmessage(pardata);
exit;
end;
var apiDDLibHandle:integer;
initPrinterManager: Function():integer;
// stdcall;
closePrinterManager: Function():integer;
sendMessage: Function(cs:PANSIChar):integer;Stdcall;
setRecvDataCallback: PbackFunc;
nr:AnsiString;
newi:integer;
begin
try
apiDDLibHandle:=
0
;
apiDDLibHandle:=LoadLibrary(
'PrinterManager.dll'
);
//下面兩行是打開
@initPrinterManager
:=GetProcAddress(apiDDLibHandle,pchar(
'initPrinterManager'
));
if
@initPrinterManager
<>nil then
showmessage(inttostr(initPrinterManager()));
//下面是回調函數
@setRecvDataCallback
:=GetProcAddress(apiDDLibHandle,pchar(
'setRecvDataCallback'
));
if
@setRecvDataCallback
<>nil then
setRecvDataCallback(
@handle_message
);
showmessage(
'已發回調函數'
);
//下面是發消息
nr:=
'{"cmd":"getPrinters","requestID":"123458976","version":"1.0"}'
;
//nr:='abcdefg';
showmessage(
'已發消息: '
+nr);
@sendMessage
:=GetProcAddress(apiDDLibHandle,pchar(
'sendMessage'
));
newi:=sendMessage(pAnsiChar(nr));
sleep(
1000
);
//下面是關閉
@closePrinterManager
:=GetProcAddress(apiDDLibHandle,pchar(
'closePrinterManager'
));
if
@apiDDLibHandle
<>nil then
closePrinterManager();
FreeLibrary(apiDDLibHandle);
//釋放動態庫
except
end;
end;
end.
|
2017 cainiao.com 版權所有，菜鳥網絡保留修改權利。
FAQ
關於此文檔暫時還沒有FAQ
1 開放的接口
-
2.1 商家不使用自定義區
-
2.2 商家基本都使用預設的自定義區
-
2.3 商家對自定義區有特殊需求
利用TOP接口，可以獲取模板數據和面單數據（取號）,ISV在獲取這些數據之后，可以發送給打印客戶端進行打印。
1 開放的接口
目前開放的TOP接口包括：
模板獲取相關接口
| 接口名稱 | 說明 | 詳細參考 |
|---|---|---|
| cainiao.cloudprint.stdtemplates.get | 獲取所有公共的菜鳥標准電子面單模板（無需商家信息） | 詳細文檔參考 |
| cainiao.cloudprint.mystdtemplates.get | 獲取用戶使用的菜鳥電子面單模板（需要商家信息，商家在模板編輯器中使用了模板之后才會獲取到） | 詳細文檔參考 |
| cainiao.cloudprint.customareas.get | 獲取商家的模板自定義區(需要商家信息，商家在模板編輯器中使用了模板之后才會獲取到) | 詳細文檔參考 |
| cainiao.cloudprint.isvtemplates.get | 獲取商家使用了哪些ISV的自定義模板（需要商家信息，商家在模板編輯器中選擇使用ISV的模板之后才能獲取到） | 詳細文檔參考 |
| cainiao.cloudprint.isv.resources.get | 獲取isv定義的資源（包括打印項、isv模板、isv預設的自定義區） | 詳細文檔參考 |
- 電子面單取號接口
請參考：//open.taobao.com/docs/doc.htm.htm?spm=a219a.7629140.0.0.AOUR3v&treeId=17&articleId=104859&docType=1
2 不同場景下的接口使用建議
為了更快速的接入，我們整理了一些常見的使用情形供isv接入時參考。
2.1 商家不使用自定義區
- 這種情況的接入最簡單，但也最少。
- 對isv來講，只需調用cainiao.cloudprint.stdtemplates.get獲取標准模板信息，然后取電子面單號即可。
- 對商家商家來講，不需要額外菜鳥模板編輯器去選擇使用的模板。
2.2 商家基本都使用預設的自定義區
- 在這種場景下，很多商家需要使用自定義區，但對自定義區的內容幾乎很少變動，這種接入方式也比較簡單。
- 對isv來講：可以在模板編輯器中預設好幾個自定義區（不是打印項）,然后調用接口獲得之后（依次調用:xxxxx），展示在ERP系統中，給商家使用即可；
- 商家此時也可不用登陸菜鳥模板編輯器去選擇使用的模板，可以減少商家的工作量。
2.3 商家對自定義區有特殊需求
客戶(商家)對待自定義區的特殊需求有很多，隨意組合很多打印項，還有的要求能循環打印內容（比如買家的商品列表），通過isv預設自定義區無法覆蓋這部分高級需求。
對isv來說，不再需要預設自定義區，而是提供各個有獨立功能打印項即可，商家可以自由組合；(這種情況依次調用接口：xxxxx)
對商家來說：需要登錄菜鳥模板編輯器選擇使用的模板，在模板上創建自定義區，選擇要搭配的打印項。
isv可以提供帶有循環功能的打印項，在模板編輯中打開代碼模式。一個示例為：提供“商品列表”這么一個打印項，商家選擇這個打印項之后就會循環輸出所有商品名，則打印項的示例代碼如下：
|
1
2
3
4
5
6
7
8
9
|
<%
for
(var i=
0
;i<_data.goods.length;i++){
%>
<text
value=
"<%=_data.goods[i].name%>"
editor:_printName_=
"請輸入內容"
style=
"fontFamily:宋體;"
/>
<%}%>
|
3 沙箱環境的對接（重要）
如果條件允許，盡量直接使用線上環境的接口，如果使用的是沙箱環境，那么就需要按照如下配置進行修改。
在開放平台的接口說明中，沙箱環境的http請求地址一般是使用http://gw.api.tbsandbox.com/router/rest，對於其他的接口來說這是沒問題的。但對於菜鳥打印組件所開放的top接口來說，是有問題的。這是因為我們開放的top接口返回結果中包含模板的url，在正常的沙箱環境中，我們域名會被重寫為http://cloudprint.tbsandbox.com開頭，但這個域名無法通過電子面單的校驗。
請按如下方式進行環境的配置，同時需要注意的是，下面的這些修改僅僅是針對沙箱環境調試階段，線上無需做任何更改：
3.1 更改沙箱環境的http請求地址
原有的沙箱http請求為http://gw.api.tbsandbox.com/router/rest.請將其改為： http://proxy.api.tbsandbox.com/router/rest
3.2 綁定hosts文件
42.156.238.99 cloudprint.daily.taobao.net
2017 cainiao.com 版權所有。菜鳥網絡保留修改權利。
FAQ
關於此文檔暫時還沒有FAQ采用雲打印組件后，快遞標准面單的上聯部分采用菜鳥提供的模板，自定義區采用商家自己設計的格式。因此，只需轉換與遷移商家自定義區即可。
模板遷移
整個模板遷移分為兩步：模板轉換和自定義區導入
lodop自定義區轉換服務
- 提供了一個url的模板轉換程序，該服務用於將原有的lodop的自定義區轉換成菜鳥官方模板。
|
1
|
http:
//cloudprint.cainiao.com/cloudprint/lodop/convert2cainiao.json?lodopData=lodop_data&charSet=GBK&cdata=true&displayContent=true&hasVar=true&specialTag=true
|
-
參數：
-
lodopData：
為lodop的加密自定義區內容，請將原有的lodop自定義區進行urlEncode之后再轉換（建議使用js的urlEncodeComponent函數進行編碼，因為lodop的代碼有+ /等特殊字符） -
charSet：
默認是GBK，基本不用改 -
displayContent
用於控制value或CDATA中內容是否以內容顯示，默認為true，可以不用改； -
cdata：默認為false，如果有特殊字符的建議為true
這個參數控制最終生成的模板格式，如果cdata為false，則表示變量內容保存在value中；如果cdata為true，則表示變量內容保存在[!CDATA[]]中，如下圖所示：12 -
hasVar:
如果為true，最終生成的變量內容為：<![CDATA[<%=_data.param%>]]>，否則為<![CDATA[param]]> -
對於非lodop格式的模板，isv需要自己開發一個轉換程序來轉成菜鳥的自定義區模板，格式如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
<?xml version=
"1.0"
encoding=
"UTF-8"
?>
<layout id=
"CUSTOM_AREA"
xsi:schemaLocation=
"http://cloudprint.cainiao.com/print http://cloudprint-docs-resource.oss-cn-shanghai.aliyuncs.com/lpml_schema.xsd"
left=
"0"
top=
"150"
width=
"100"
height=
"30"
style=
"overflow:hidden;"
>
<layout left=
"1.058"
top=
"0"
width=
"51.594"
height=
"8.731"
editor:_for_=
"element_text_-407992064437985761"
style=
""
>
<text
value=
""
editor:_printName_=
"顯示名稱"
style=
""
>
<![CDATA[<%=_data.param%>]]>
</text>
</layout>
</layout>
|
注意事項（重要）：1、變量放在CDATA中；2、“editor:for”這個字段的格式生成為：element_text_隨機數值；3、第二層的layout中top高度目前要減去150，是相對高度.
注：有些isv的模板轉換出來變量為為純數字或者中文，請確認你們是否有變量轉換表，請替換！
自定義區導入接口：
提供了一個top接口用於將轉換后的模板遷移到菜鳥系統中:
cainiao.cloudprint.templates.migrate
該接口需要傳入標准模板的id，因為每個標准自定義區都依附在標准模板上，標准模板id的獲取可以通過cainiao.cloudprint.stdtemplates.get接口獲得（以cp維度）
自定義區更新接口
在將自定義區遷移到菜鳥系統中后，可以通過如下接口對自定義區的內容進行更新
cainiao.cloudprint.customarea.update
該接口需要傳入要更新的自定義區id
FAQ
關於此文檔暫時還沒有FAQ雲打印
1 url跳轉優化方案
ISV模板編輯器跳轉到菜鳥的官方編輯器，為了簡化商家的使用成本（跳過身份選擇頁以及所使用的服務），對url跳轉方案進行了優化
|
1
|
http:
//cloudprint.cainiao.com/cloudprint/templates.htm?identity=xxx&appKey=xxx
|
url中新增兩個參數identity和appKey。其中identity為身份，包括seller和isv，對於商家來說，就固定為seller；這樣商家在登陸后，就不用選擇自己的身份以及使用的服務。
2 千牛免登
對於千牛平台的系統，除了上述的url跳轉優化外，還可以進一步跳過登錄頁面：
2.1 跳轉到模板選擇頁
可以使用如下的跳轉地址：
|
1
|
http:
//cloudprint.cainiao.com/cloudprint/templates.htm?identity=seller&appKey=xxx
|
其中：identity和appKey的含義同第二節“url跳轉優化方案”；xxx需要根據實際值進行替換，其余部分固定
2.2 跳轉到模板編輯頁
可以使用如下的跳轉地址：
以商家身份跳轉
|
1
|
http:
//cloudprint.cainiao.com/cloudprint/editor.htm?identity=xxx&appKey=xxx&id=xxx&resource_type=2
|
說明：
- xxx需要根據實際值進行替換，否則會跳轉錯誤，其余部分固定；
- appKey為商家訂閱的應用key；
- identity固定為seller
- id為cainiao.cloudprint.mystdtemplates.get接口返回的user_template_id
resource_type固定為2
以isv身份跳轉
|
1
|
http:
//cloudprint.cainiao.com/cloudprint/editor.htm?identity=isv&appKey=xxx&id=xxx&resource_type=3
|
說明：
- xxx需要根據實際值進行替換，否則會跳轉錯誤，其余部分固定；
- identity固定為isv
- appKey為isv自身擁有的應用key
id為cainiao.cloudprint.mystdtemplates.get接口返回的user_template_id
resource_type固定為3
額外說明
當所指定的appKey並非被已登錄的用戶所訂購時，會報錯；請填寫正確的appKey；
identity只能取isv和seller兩個枚舉值
FAQ
關於此文檔暫時還沒有FAQ1、簡介
2、page(頁)
4、text(文本)
5、line(線條)
6、rect(矩形)
10、style(樣式)
1. 簡介
菜鳥打印標記語言是菜鳥官方定義的一套用於描述打印內容的的標准，其定義了一套標准規范，通過這套標記語言，可以：
- 確保優質的打印效果。我們沒有選用已有的HTML標記語言，是由於HTML是為了屏幕渲染為目標而設計的，我們是為打印而設計的，設計目標不同在很多細節的處理上會完全不一樣。
- 高效傳輸。服務器向打印服務客戶端傳遞的數據並非最終打印頁面，而是標記語言的內容，由打印服務根據數據進行繪制，可有效減少數據傳輸量。
- 屏蔽硬件差異。
如果熟悉HTML語言或者java script，那么很容易就會熟悉菜鳥打印標記語言，我們在設計該套語言標准的時候盡量參考HTML規范，且相較HTML來說更加的精簡。
本規范中**除文本外的其他元素，單位均支持毫米（mm）和磅（pt）,默認單位是mm(毫米),mm可以省略，如width=20.5,下文如不做特別說明，單位一律是mm（毫米）。**
坐標系以左上角為起點（0，0）。
1 元素概覽
打印標記語言所包含的元素如下：
| 元素 | 說明 |
|---|---|
| page | 代表的是打印紙的長度和寬度 |
| layout | 打印紙上控制布局使用 |
| text | 用來標記文本元素 |
| line | 用來標記線條元素 |
| rect | 用來標記矩形元素 |
| barcode | 條碼二維碼標記元素 |
| image | 圖片標記元素 |
2、page(頁)
頁面屬性，用於描述打印紙張的信息,是整個xml的根節點。
2.1 width(寬度)
紙張的寬度，如width=100.5。
2.2 height(高度)
紙張的高度，如height=80。
2.3 splitable(分頁)
模板是否支持分頁打印，布爾型，如果不設置，默認值為splitable=“false”
3、layout(布局)
畫布的基礎元素，其他元素都需要放在布局元素內。布局支持二種類型，水平布局和垂直布局，layout中也可以嵌套其它layout，示例：
|
1
2
|
<layout left=
"1.8"
top=
"2.2"
width=
"8.3"
height=
"2.5"
id=
"1"
>
</layout>
|
采用相對父節點的坐標進行描述
效果如下圖：
3.1 id(主鍵ID)
布局的主鍵ID，ID類型，如id=“1”。
3.2 left(左上角X坐標)
布局的左上角絕對X坐標，如left=“1.8”。
3.3 top(左上角Y坐標)
布局的左上角絕對Y坐標，如top=“2.2”。
3.4 width(寬度)
布局的寬度，如width=“8.3”。
3.5 height(高度)
布局的高度，如height=“2.5”。
3.6 ref(引用布局)
引用的布局的主鍵ID，IDREF類型，把被引用的布局屬性全部復制過來，當前布局可以重新設置屬性去覆蓋引用過來的布局屬性。如ref=“1”。
3.7 orientation(布局方向)
支持水平（horizontal）和垂直（vertical）二種布局模式，默認為水平布局。
a. 水平布局如下圖(如orientation=“horizontal”)：
水平布局中的元素，都以水平模式排列。
b. 垂直布局如下圖(如orientation=“vertical”)：
垂直布局中的元素，都以垂直模式排列。
3.8 style(樣式)
layout可用的style屬性如下， 詳細含義請查看(style樣式)
| 屬性名 | 說明 |
|---|---|
| zIndex | 圖層 |
| overflow | 超出處理 |
| backgroundColor | 背景色 |
| borderWidth | 邊框寬度 |
| borderStyle | 邊框樣式 |
| margin | 元素外邊距 |
| padding | 元素內邊距 |
4. text(文本)
畫布的基礎元素，文本自身無邊框，只有里面的文本內容。
如果只是簡短文本並且文本中沒有特殊字符可以如下方式使用：
|
1
|
<text width=
"5.6"
value=
"菜鳥網絡"
style=
"fontSize:16"
/>
|
效果如下圖：
如果文本比較長或者有換行需求，可以使用
|
1
2
3
4
|
<text width=
"5.6"
style=
"fontSize:16"
>
line
1
line
2
</text>
|
注意：每一行文本前后的空白字符都會被保留。
如果文本中有特殊字符，如“，&，‘，<,>等等xml規范中的特殊字符，可以如下方式使用,這種方式文本中的特殊字符不會被轉義：
|
1
2
3
|
<text width=
"5.6"
style=
"fontSize:16"
>
<![CDATA[some text, &,",',<,> ... 菜鳥網絡]]>
</text>
|
備注：如果text內容中要輸出“<%”或“%>”，需要添加“"做轉義，也即”<\%“或”%>" 。
4.1 width(寬度)
文本框的寬度，如width=“10.5”，如省略則由layout確定寬度。
4.2 height(高度)
文本框的高度，如height=“10”，如省略則由layout確定文本框的高度。
4.3 value(值)
文本顯示的內容，字符串型，如value=“菜鳥網絡”。
4.4 style(樣式)
text可用的style屬性如下， 詳細含義請查看(style樣式)
| 屬性名 | 說明 |
|---|---|
| alpha | 透明度 |
| align | 水平對齊 |
| valign | 垂直對齊 |
| rotation | 旋轉角度 |
| direction | 文字書寫方向 |
| orientation | 文本排版方向 |
| fontColor | 字體顏色 |
| backgroundColor | 背景色 |
| fontFamily | 字體類型 |
| fontSize | 字體大小，如fontSize:8。可以取值為“auto”,此時會根據文本框大小進行字體縮放 |
| fontWeight | 字體粗細 |
| fontItatlic | 字體是否斜體 |
| fontUnderline | 字體是否有下划線 |
| lineHeight | 行高 |
| letterSpacing | 字符間距 |
| wrap | 多選文本還是單行文本 |
5.line(線條)
畫布的基本元素，線條用來畫從一個起點到一個終點之間的連線。
示例：
|
1
|
<line startX=
"3.2"
startY=
"5.5"
endX=
"10.2"
endY=
"6.5"
style=
"lineType:solid"
/>
|
效果如下圖(藍色為所畫線條)：
5.1 startX(起始點X坐標)
線條起始點X坐標，如startX=30.5。
5.2 startY(起始點Y坐標)
線條起始點Y坐標，如startY=20.95。
5.3 endX(終點X坐標)
線條終點X坐標，如endX=79.85。
5.4 endY(終點Y坐標)
線條終點Y坐標，如endY=78。
5.5 style(樣式)
詳見(style樣式)
| 屬性名 | 說明 |
|---|---|
| lineColor | 線條顏色 |
| lineWidth | 線條寬度 |
| lineType | 線條的樣式 |
6. rect(矩形)
畫布的基礎元素，用來描繪一塊區域。如
|
1
2
3
|
<layout left=
"1.8"
top=
"2.2"
width=
"8.3"
height=
"2.5"
>
<rect width=
"3.3"
height=
"1.5"
style=
"borderStyle:solid"
/>
</layout>
|
效果圖如下：
6.1 width(寬度)
矩形的寬度，如width=“30.3”。
6.2 height(高度)
矩形的高度，如height=“1.5”。
6.3 style(樣式)
參考(style樣式)
| 屬性名 | 說明 |
|---|---|
| rotation | 旋轉角度 |
| fillColor | 填充色 |
| borderWidth | 邊框寬度 |
| borderStyle | 邊框樣式 |
7.barcode(條碼與二維碼)
畫布的基礎控件，條形碼根據數據生成的圖片。
示例：
|
1
2
3
|
< layout left=
"1.8"
top=
"2.2"
width=
"8.3"
height=
"3.5"
>
<barcode width=
"2.5"
height=
"7.0"
value=
"123987af"
type=
"code128a"
style=
"hideText:true"
/>
</layout>
|
如果barcode中有特殊字符，如“，&，‘，<,>等等xml規范中的特殊字符，可以如下方式使用,這種方式文本中的特殊字符不會被轉義：
|
1
2
3
|
<barcode width=
"2.5"
height=
"7.0"
type=
"code128a"
style=
"hideText:true"
>
<![CDATA[123987af<>!&*$#]]>
</barcode>
|
備注：如果要輸出“<%”或“%>”，需要添加“"做轉義，也即”<\%“或”%>" 。
效果圖如下：
7.1 width(寬度)
條形碼的寬度,如width=“2.5”。
7.2 height(高度)
條形碼的高度，如height=“7.0”。
7.3 value(數據)
條形碼的數據，字符串，如value=“123987af”。
7.4 type(條碼類型)
條形碼的類型，枚舉值,如type=“code128a”。
7.5 primary(MaxiCode特有屬性)
生成條碼需要到的部分核心信息，郵編+國家代號+服務商等級
7.6 mode(MaxiCode特有屬性)
取值2到6，1被廢棄，取值含義如下：
2：主要信息為一個結構化收件人信息加上一個數字型態的郵遞編號，次要信息至多可編入84個字元(character)。
3：主要信息為一個結構化收件人信息加上一個文數字型態的郵遞編號，次要信息至多可編入84個字元。
4：主要信息加上次要信息至多可編入93個字元。模式4是標准符號，其指示在主要信息部分采用EEC，而在次要信息部分采用SEC，這種模式下共有93個資料字碼。
5：主要信息加上次要信息至多可編入77個字元。模式5是全EEC模式，其指示在主要信息及次要信息部份全部采用EEC，符號有77個資料字碼。
6：主要信息加上次要信息至多可編入93個字元。模式6為掃瞄器編程模式，其指示符號表示的信息是用於掃瞄器編程，主要信息采用EEC，次要信息采用SEC。
| 類型 | 碼式 |
|---|---|
| 條形碼 | code128a，code128b，code128c，upca，code11，postnet，Code39,Code93,UPC-A,UPC-E,FIM,EAN-8,EAN-13,Plessey,Telepen,ITF-14,Interleaved 2 of 5,MaxiCode,Data Matrix |
| 二維碼 | qrcode，pdf417 |
參考(style樣式)
| 屬性名 | 說明 |
|---|---|
| rotation | 旋轉角度 |
| hideText | 是否顯示文本 |
8.image(圖片)
畫面的基礎控件，插入靜態圖片資源。
示例：(真實的圖片)
|
1
2
3
|
<layout left=
"1.8"
top=
"2.2"
width=
"8.3"
height=
"3.5"
>
</layout>
|
效果如下圖：
8.1 width(寬度)
圖片的寬度，如width=“5.5”。
8.2 height(高度)
圖片的高度，如height=“4.5”。
8.3 src(圖片路徑url)
圖片的資源路徑，字符串型。如src="http://www.taobao.com/test.jpg"。
8.4 style（樣式）
詳見(style樣式)
| 屬性名 | 說明 |
|---|---|
| alpha | 透明度 |
| rotation | 旋轉角度 |
9、table(表格)
9.1 定義表格的標簽
- 定義表格需要使用四個標簽：
- table：表格
- tr：行
- th: 表頭
- 只能包含一個文本元素
- td：單元格
- 只能包含一個元素（該元素可以是layout，也可以是文本，圖片，二維碼，線條，矩形）。
以下示例是一個簡單帶表頭的，2 * 2 表格，其中 fieldx 是一個元素，可以是layout，也可以是文本，圖片，二維碼，線條，矩形元素。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
<table width=
"80"
>
<tr>
<th width=
"40"
> header1 </th>
<th width=
"40"
> header2 </th>
</tr>
<tr>
<td> field1.
1
</td>
<td> field1.
2
</td>
</tr>
<tr>
<td> field2.
1
</td>
<td> field2.
2
</td>
</tr>
</table>
|
9.2 table(表格)
9.2.1 table支持的屬性
| 屬性名 | 說明 |
|---|---|
| left | X坐標 |
| top | Y坐標 |
| width | 表格寬度 |
- table必須指定width屬性，單位毫米（mm）。
- table不支持height屬性 ，table的高度會根據表頭的高度和各行的總高度來做自動適應，如果指定了height屬性，也會被忽略
9.2.2 table支持的style
| 樣式名 | 說明 |
|---|---|
| borderWidth | 外邊框線條寬度 |
| borderStyle | 外邊框樣式 |
| headerBorderWidth | 表頭線條寬度 |
| headerBorderStyle | 表頭線條樣式 |
| cellBorderWidth | 單元格線條寬度 |
| cellBorderStyle | 單元格線條樣式 |
- 表頭和單元格的邊框樣式支持設置1個或兩個值，第一個值表示橫線的寬度或樣式，第二個值表示豎線的寬度或樣式；如果設置一個值，表示橫豎樣式一致
- headerBorderWidth和headerBorderStyle不設置時，默認采用cellBorderWidth和cellBorderStyle
- cellBorderWidth和cellBorderStyle不設置時，默認線條寬度是1pt，樣式是solid（實線）
9.3 tr（行）
tr目前暫不支持屬性
9.4 th（表頭）
9.4.1 th屬性
| 屬性名 | 說明 |
|---|---|
| width | 列寬 |
| height | 高度 |
- th支持width屬性，用於指定列寬，該屬性為必選項
- width屬性支持如下兩種類型：
- 百分比：30%， 占整個表格寬度的30%
- 固定值：單位為mm
- 為兼容舊的表格定義，table里面可以不包含表頭行，但是對新創建的模板，table元素推薦加上表頭行
9.4.2 style(樣式)
th可用的style屬性如下， 詳細含義請查看(style樣式)
| 樣式名 | 說明 |
|---|---|
| padding | 元素內邊距 |
9.5 td（單元格）
9.5.1 td屬性
| 屬性名 | 說明 |
|---|---|
| width | 單元格寬度 |
| height | 單元格高度 |
| rowspan | 跨行 |
| colspan | 跨列 |
- colspan：一個單元格可以跨多列 可選
- rowspan：一個單元格可以跨多行 可選
- width：單元格的寬度,可選,單位毫米（mm），不建議設置該屬性，因為在對於列的th上已經設置了width。如果設置td的width，則存在如下兩種情況：
- td的width小於th指定的列寬，則td的width設置被忽略
- td的width大於th指定的列寬，則列寬用td的width來替代
- height：單元格的高度,可選,單位毫米（mm），默認情況下，不需要指定height屬性，單元格的高度根據內容自適應。該行的行高取最大的單元格的高度，如果指定了height屬性，則存在如下兩種情況：
- td的height小於該行的行高，則td的height設置被忽略
- td的height大於該行的行高，則該行的行高用td的height來替代
9.5.2 style(樣式)
td可用的style屬性如下， 詳細含義請查看(style樣式)
| 樣式名 | 說明 |
|---|---|
| padding | 元素內邊距 |
9.6 表格對分頁的支持
- 如果指定了表頭，則分頁時，每頁都會帶上表頭
- 分頁是以行為單位，如果改行有單元格設置了rowspan屬性，則相關的行都要在一頁上打印
10.style(樣式)
樣式不是畫布的基礎元素，用來描述基礎元素的展現形式。樣式由一組屬性組成，每個屬性有一個值，屬性名稱和值通過冒號分開。如property:value。多個樣式屬性之間使用分號分開，屬性之間的空格會被忽略。如style=“alpha:0.6; align:left;”。
元素框的最內部分是實際的內容，直接包圍內容的是內邊距。
10.1 邊距
-
margin（外邊距）
外邊框距離其他控件的距離。 - a. margin:1 2 3 4，表示上邊框外邊距1毫米，右邊框外邊距2毫米，下邊框外邊距3毫米，左邊框外邊距4毫米。
-
b. margin:1 2 3，表示上邊框外邊距1毫米，左右邊框外邊距2毫米，下邊框外邊距3毫米。
-
c. margin:1 2，表示上下邊框外邊距1毫米，左右邊框外邊距2毫米。
-
d. margin:1 ，表示上下左右邊框外邊距1毫米。
備注：如果單位是pt則不能省略，單位建議使用毫米（mm）。
-
-
padding（內邊距）
邊框距離實際內容的距離。
- a. padding:1 2 3 4，表示上邊框內邊距1毫米，右邊框內邊距2毫米，下邊框內邊距3毫米，左邊框內邊距4毫米。-
b. padding:1 2 3，表示上邊框內邊距1毫米，左右邊框內邊距2毫米，下邊框內邊距3毫米。
-
c. padding:1 2，表示上下邊框內邊距1毫米，左右邊框內邊距2毫米。
-
d. padding:1 ，表示上下左右邊框內邊距1毫米。
備注：如果單位是pt則不能省略，單位建議使用毫米（mm）。
-
10.2 對齊方式
-
align(水平對齊)
枚舉值，包括 左對齊（left），居中（center），右對齊（right）
-
a. 左對齊的效果如下(align:left)
左圖為一個layout中多個基礎控件的對齊效果圖，右圖為一個文本框中的文字對齊效果圖。
-
b. 居中對齊的效果如下(align:center)
左圖為一個layout中多個基礎控件的對齊效果圖，右圖為一個文本框中的文字對齊效果圖。
-
c. 右對齊的效果如下(align:right)：
左圖為一個layout中多個基礎控件的對齊效果圖，右圖為一個文本框中的文字對齊效果圖。
-
-
valign(垂直對齊)
垂直對齊方式，枚舉值(top為上對齊，middle為居中，bottom為下對齊)。- a. 上對齊的效果圖如下(valign:top)：
左圖為一個layout中多個基礎控件的對齊效果圖，右圖為一個文本框中的文字對齊效果圖。
- a. 上對齊的效果圖如下(valign:top)：
- b. 居中對齊的效果圖如下(valign:middle)：
左圖為一個layout中多個基礎控件的對齊效果圖，右圖為一個文本框中的文字對齊效果圖。
|
1
2
|
- c. 下對齊的效果圖如下(valign:bottom)：
左圖為一個layout中多個基礎控件的對齊效果圖，右圖為一個文本框中的文字對齊效果圖。
|
10.3 字體
-
fontColor(字體顏色)
字體顏色，字符串類型，顏色由一個十六進制符號來定義，這個符號由紅色、綠色、藍色的值組成(RGB)。每種顏色的最小值是0(十六進制：#00)，最大值255(十六進制：#FF)。格式為#rrggbb。如fontColor:#120FAC。
默認為黑色 fontColor:#000000。 -
fontFamily(字體類型)
字體類型，字符串型。默認為宋體。省略則用默認宋體。如果選擇的字體當前系統不支持，則使用默認的宋體。
- a. 宋體的效果圖如下(fontFamily:宋體)：
|
1
|
- b. 楷體的效果圖如下(fontFamily:華文行楷)：
|
-
fontSize(字體大小)
字體大小，單位為磅，如fontSize:12pt，字體大小缺省值為8pt。
需特別注意，單位不能是mm（毫米）。 -
fontWeight(字體粗細)
設置文本字體的粗細，枚舉型，light、normal、bold，如“fontWeight:bold”。
常用取值 描述 light 定義較細的字符。 normal 默認值，定義標准的字符。 bold 定義粗體字符。 -
fontItalic(斜體)
字體斜體， bool類型(true為斜體，false為正常)。默認為正常。如fontItalic:false。
-
fontUnderline(下划線)
字體下划線，bool類型(true為有下划線，false為無下線划)。默認為無下划線。如fontUnderline:false。
-
letterSpacing(字符間距)
字符串增加或減少字符間的空白，支持百分比和絕對值兩種類型，默認單位是絕對值類型中的pt（磅）：
-
百分比：100%為正常間距，150%為正常間距的1.5倍，如“letterSpacing:150%”。
-
絕對值：單位為pt(磅)或者mm（毫米），正常值為0，建議使用pt作為單位，如“letterSpacing:3pt”，表示將正常字符間距拉寬3pt。
效果圖如下：
-
10.4 文本
-
wrap(多行文本)
是否要自動換行標識，bool類型（ true為多行文本，false為單行文本），默認為多行文本。-
a. 多行文本的效果圖如下（wrap:true）
- b. 單行文本的效果圖如下(wrap:false)
-
-
hideText(隱藏文本)
是否在條形碼或二維碼下面顯示文本，bool類型（true為隱藏文本，false為顯示文本），默認為隱藏文本。
-
lineHeight(行高)
行高為一行的高度，包括文本的字體實際高度和上下空白高度，支持兩種類型：
* 百分比：如 150% 是默認高度的1.5倍；
* 固定值：浮點型，單位 mm 和 pt 均可，缺省為mm，如“lineHeight:10mm”；
效果圖如下：
-
direction(文本方向)
文本的方向，枚舉值，如“direction:ltr”,默認值為“ltr”，只在text元素上生效。-
a. 從左到右效果圖如下圖(direction: ltr)
-
b. 從右到左效果如下圖(direction :rtl)
-
-
orientation(文本的排版方向)
表示文本的橫排（horizontal）和豎排（vertical）枚舉值。
取值 |描述
—-|—-
horizontal |文本水平排版。
vertical |文本垂直排版。-
a.橫排效果圖如下圖(orientation: horizontal)
-
b.豎排效果如下圖(orientation :vertical)
-
線條與邊框
-
lineColor(線條顏色)
線條的顏色，字符串類型，顏色由一個十六進制符號來定義，這個符號由紅色、綠色、藍色的值組成(RGB)。每種顏色的最小值是0(十六進制：#00)，最大值255(十六進制：#FF)。格式為#rrggbb。如lineColor: #00FF00。
默認為黑色 lineColor:#000000。 -
lineWidth(線條寬度)
線條的寬度，單位pt和mm均可，缺省為pt，建議使用pt，如“lineWidth:3pt”。
-
lineType(線條類型)
線條的類型，枚舉值(solid為實線，dashed為破折線，dotted為點線)。-
a. 實線效果如下圖(“lineType:solid”)
-
b. 破折線效果如下圖(“lineType:dashed”)
-
c. 點線效果如下圖(“lineType:dotted”)
-
-
borderWidth(邊框寬度)
單位pt和mm均可，缺省為pt，建議使用pt。
- a. borderWidth:1pt 2pt 3pt 4pt，表示上邊框寬度1pt，右邊框寬度2pt，下邊框寬度3pt，左邊框寬度4pt。
-
b. borderWidth:1pt 2pt 3pt，表示上邊框寬度1pt，左右邊框寬度2pt，下邊框的寬度3pt。
-
c. borderWidth:1pt 2pt，表示上下邊框寬度1pt，左右邊框寬度2pt。
-
d. borderWidth:1pt ，表示上下左右邊框寬度1pt。
-
-
borderStyle(邊框樣式)
邊框樣式，取值為枚舉值（solid/dashed/dotted）。
取值 |描述
—-|—-
solid |實線條
dashed |破折線
dotted |點線條。-
a. 如borderStyle: solid dashed dotted solid
上線條實線，右線條破折線，下線條點線，左線條實線。
-
b. 如borderStyle:solid dashed dotted
上線條實線，左右線條破折線，下線條點線。
-
c. 如borderStyle:solid dashed
上下線條實線，左右線條破折線。
-
d. 如borderStyle:solid
上下左右線條實線。
-
10.5 其他樣式
-
zIndex(圖層)
控制元素的上下順序，整數型，數值越大則圖層越高，離用戶越近。
只有layout元素上有zIndex屬性，如果缺省默認為0。
zIndex取值范圍為:[-2147483648,2147483647]。 -
alpha(透明度)
控件的透明度百分比，浮點型，值范圍0至1，0為完全透明，1為完全不透明。如alpha:0.6。
-
rotation(旋轉)
順時針旋轉角度，浮點型，單位為度。如rotation:90.5。效果圖如下：
-
overflow(超出處理)
布局內的元素超出布局的處理方式，枚舉值（hidden隱藏，visible顯示），缺省為overflow:visible。
-
a. 隱藏效果如下圖(如overflow:hidden)
-
b. 顯示效果如下圖(如overflow:visible)
-
-
backgroundColor(背景色)
背景色，字符串類型，顏色由一個十六進制符號來定義，這個符號由紅色、綠色、藍色的值組成(RGB)。每種顏色的最小值是0(十六進制：#00)，最大值255(十六進制：#FF)。
格式為#rrggbb，默認白色 backgroundColor:#FFFFFF。
2018 cainiao.com 版權所有。
未經允許，不得進行任何形式的修改、傳播等行為。菜鳥網絡保留修改權利。
FAQ
關於此文檔暫時還沒有FAQ模板繪制
這里的模板是指依據菜鳥打印標記語言規范設計出來的面單模板。為了更加快速的進行模板設計與生成，可采用菜鳥官方提供的模板編輯器（菜鳥模板編輯器）。
模板設計
- 通過視圖方式進行控件拖拽的方式來生成模板（此時會自動生成代碼）
- 通過在代碼編輯頁面中直接鍵入符合菜鳥模板標記語言的代碼來生成模板（此時會自動根據代碼繪制出視圖）
模板內容
模板內容分為兩種：靜態內容和動態內容。
- 靜態內容：在模板繪制的過程中，值就確定的內容我們稱之為靜態內容。在編輯器中進行模板設計的時候就可以將內容輸入進去。
-
動態內容：在繪制模板的過程中，我們經常希望只放入一個占位符，其內容將在實際打印時才能確定，我們稱之為動態內容。為了支持這種動態內容，在模板中可以通過編寫ECMAScript(參考鏈接)腳本來達到生成動態內容的目的。同時對ECMAScript的解析采用了目前業界最先進的V8引擎，具有極高的性能，在打印服務生成打印文件前，會對ECMAScript的代碼進行解析並替換為實際值。
動態內容的編寫
動態內容可以嵌入類似js的代碼，在模板中可以通過如下的方式嵌入動態代碼:
- 動態語句: 以“<%”開始，以“%>”結束，如<% if(true) %>。
- 變量引用: 以“<%=”開始，以“%>”結束，如“<%=data.address%>”，表示將會用data.address的實際值在模板中進行填充。允許使用自定義的變量。可參考：(鏈接)。
- 如果內容中要輸出“<%”或者“<%=”，需要添加“"做轉義，也即”<\%"。
- 包含文件: <%@ include “filepath/file.js” %>。“filepath/file.js”必須是符 合URL格式的路徑，如：
- <%@ include “http://cloudprint.cainiao.com/template/print.js” %>
- <%@ include “print.js”%> //包含了一個控件內置的js文件
~ - 內置變量：模板包含如下幾個內置變量
| 變量名 | 說明 |
|---|
_data | 該變量表示模板的數據內容，即發送打印數據中的data
_config | 該變量表示模板的一些配置信息，詳見"_config變量"
_out | 內部使用，暫時不對外開放，菜鳥可能會做修改。
_context| 打印任務的上下文信息
注：
開頭的變量名都保留給控件使用，請不要在模板中定義開頭的變量名字。
- _config變量
| 成員 | 說明 |
|---|---|
| needTopLogo | 是否需要模板上聯的快遞logo（可由打印機配置中更改）； |
| needBottomLogo | 是否需要模板下聯的快遞logo（可由打印機配置中更改） |
- _context變量
| 成員 | 說明 |
|---|---|
| formatStartTime(fmt) | 任務開始打印時間，fmt參數是時間格式化模式 |
| documentNumber() | 當前打印的頁數 |
注：fmt支持如下格式化模式：
- 年(y)可以用2或4個占位符
- 月(M)可以用1或2個占位符
- 日(d)可以用1或2個占位符
- 時(h)12小時制,可以用1或2個占位符
- 時(H)24小時制,可以1或2個占位符
- 分(m)可以用1或2個占位符
- 秒(s)可以用1或2個占位符
- 毫秒(S)只能用1個占位符（是1-3位的數字）
- 周(E)可以用1或2或3個占位符
使用示例如下：
_context.formatStartTime(“yyyy-MM-dd hh:mm:ss.S”)==> 2006-07-02 08:09:04.423
_context.formatStartTime(“yyyy-MM-dd E HH:mm:ss”) ==> 2009-03-10 二 20:09:04
_context.formatStartTime(“yyyy-MM-dd EE hh:mm:ss”) ==> 2009-03-10 周二 08:09:04
_context.formatStartTime(“yyyy-MM-dd EEE hh:mm:ss”) ==> 2009-03-10 星期二 08:09:04
_context.formatStartTime(“yyyy-M-d h:m:s.S”) ==> 2006-7-2 8:9:4.18
_context.formatStartTime(“yyyy-MM-dd hh:mm:ss”) ==> 2006-07-02 08:09:04
_context.formatStartTime(“yyyy/MM/dd hh:mm:ss”) ==> 2016/07/08 03:20:52
_context.formatStartTime(“yyyy-MM-dd”) ==> 2006-07-02
_context.formatStartTime(“hh:mm:ss”) ==> 08:09:04 -
動態代碼示例如下，這個例子是將獲得的打印數據（data）中的所有對象依次輸出。
|
1
2
3
4
5
6
|
<layout left=
"6"
top=
"5"
width=
"20"
height=
"20"
style=
"borderStyle:solid;"
>
<text width=
""
value=
"動態數據顯示"
/>
<%
for
(i=
0
;i++;i<_data.arrayObject.lenth) {%>
<text width=
""
value=
"<%=_data.arrayObject[i].value%>"
style=
"fontSize:12"
/>
<%}%>
</layout>
|
數據：
|
1
2
3
4
5
|
[
[
"收件人"
],
[
"發件人"
],
[
"收貨地址"
]
]
|
動態代碼解析之后的靜態代碼為：
|
1
2
3
4
5
6
|
<layout left=
"6"
top=
"5"
width=
"20"
height=
"20"
style=
"borderStyle:solid;"
>
<text width=
""
value=
"動態數據顯示"
/>
<text width=
""
value=
"收件人"
style=
"fontSize:12"
/>
<text width=
""
value=
"發件人"
style=
"fontSize:12"
/>
<text width=
""
value=
"收貨地址"
style=
"fontSize:12"
/>
</layout>
|
模板布局說明
模板中所有元素都采用相對坐標，即相對其父節坐標來表示。如下圖所示，這是一個典型的模板布局示意圖，其中：
- 最外面黑色矩形表示完整的一個畫布，即page。P0表示其左上角的x，y坐標，記為（0，0）。
- P1為layout1的左上角x，y坐標，記為（5，35），表示相對page左上角的x，y距離
- 其他layout的坐標含義以此類推
- Layout6，layout7坐標P6，P7相對於layout5的坐標P5進行定位。
模板布局示意圖
注：layout可用來靈活控制整體布局，主要作用如下：
- 可以解決固定坐標和固定大小的控件（由layout的left和top確定坐標，如果控件的width和height有值，則由控件的width和height確定寬度和高度，如果無則由layout的width和height確定寬度和高度）
- 可以解決不固定坐標但固定大小的控件（由控件的width和height來確定寬度和高度，layout自動計算控件的left和top坐標）
- 可以解決不固定坐標且不固定大小的控件（由layout自動計算控件的left和top坐標,，以及自動計算控件的寬度和高度）
模板設計示例
以中通為例，典型的模板效果圖如下所示：
注：
- 模板內以下划線"_"開始的屬性為菜鳥模板的內置變量
- 模板內以edit:開頭的屬性為模板編輯器中使用的私有屬性，非標記語言元素
如果模板中需要預留商家自定義區，商家自定義區中不需要page元素，最外層有且只有一個layout，且這個最外層的layout需要要有屬性id=”CUSTOM_AREA”。
標准板示例：
|
1
2
3
4
5
6
7
8
|
<?xml version=
"1.0"
encoding=
"UTF-8"
?>
<layout left=
"0"
top=
"0"
width=
"100"
height=
"150"
style=
"zIndex:1;overflow:visible;"
>
<rect style=
""
></rect>
</layout>
<layout ref=
"CUSTOM_AREA"
left=
"1"
top=
"150"
width=
"100"
height=
"30"
style=
"overflow:hidden;"
>
</layout>
</page>
|
商家自定義區示例：
|
1
2
3
4
5
6
7
8
9
|
<?xml version=
"1.0"
encoding=
"UTF-8"
?>
<layout xmlns=
"http://cloudprint.cainiao.com/print"
id=
"CUSTOM_AREA"
left=
"0"
top=
"140"
width=
"100"
height=
"40"
>
<layout left=
"1"
top=
"0"
width=
"100"
height=
"10"
>
<text value=
"自定義區域內容測試"
/>
</layout>
<layout left=
"1"
top=
"10"
width=
"100"
height=
"10"
>
<text value=
"custom area test"
/>
</layout>
</layout>
|
示例模板代碼可參考：
http://cloudprint.cainiao.com/template/standard/101
2017 cainiao.com 版權所有。菜鳥網絡保留修改權利。