菜鸟打印组件-文档

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的最新版本）

协议格式说明

请求协议头:通常，与菜鸟打印组件进行交互，需要发送如下格式的请求协议头:

{
    "cmd":"command",  
    "requestID":" unique requestID ",
    "version":"1.0"
}

字段说明:

字段名	类型	说明	是否必须
cmd	string	请求的命令名称	是
requestID	string	请求的ID，用于唯一标识每个请求，每个客户端自己保证生成唯一ID，如UUID	是
version	string	协议当前版本，当前为“1.0”	是

响应协议头:菜鸟打印组件会返回如下格式的响应头给请求方。

{
    "cmd":"command", 
    "requestID":"unique requestID"
}

字段说明:

字段名	类型	说明
cmd	string	请求的命令名称
requestID	string	发送请求中的ID,原封不动返回，使客户端能识别出哪个请求对应的响应

协议详解

1. 请求打印机列表协议(getPrinters)

请求协议格式如下:

{
    "cmd": "getPrinters",
    "requestID": "123458976",
    "version": "1.0"
}

响应协议格式如下:

{       
    "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)

请求协议格式如下:

{
  "cmd":"getPrinterConfig",
  "printer":"菜鸟打印机",
  "version":"1.0",
  "requestID":"123456789"
}

响应协议格式如下:

{
    "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)

请求协议格式如下:

{   
    "cmd":"printerConfig",
    "printer":"中通专用打印机",
    "requestID":"123458976",
    "version":"1.0"
}

响应协议格式如下:

{       
    "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)

此协议是将当前用户的打印机设置重置为系统全局缺省值，如将打印机首选项配置的偏移、纸张尺寸等重置为系统全局缺省值。

此协议当前对奇锐系列的打印机无效。

请求协议格式如下:

{
    "cmd":"resetPrinterPreferences", //重置打印机配置命令
    "requestID":"123458976",
    "version":"1.0",
    "printer":"菜鸟专用打印机"
}

字段名 |类型 |说明 |是否必须
printer |string |打印机名 |是

响应协议格式如下:

{       
    "cmd":"resetPrinterPreferences", //需要响应的命令名称，响应重置打印机配置命令的响应
    "requestID":"123458976",
    "status":"success", //重置打印机配置成功还是失败
    "msg":"if failed ,some tips, if success,nothing"
}

5. API模式配置打印机协议(setPrinterConfig)

请求协议格式如下:

{
     "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	设置打印机纸张的宽度和高度，单位是毫米	否

响应协议格式如下:

{
     "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，可以有效避免重打问题；

非加密请求协议格式如下:

{
    "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":"测试字段值需要配合自定义区变量名"
                },
                "templateURL": "http://cloudprint.cainiao.com/template/customArea/440439"
            }]
        }]
    }
}

加密请求协议格式如下:

{
    "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==",
                "templateURL": "http://cloudprint.cainiao.com/template/standard/206612"
            }]
        }]
    }
}

下面将进一步说明菜鸟打印组件是如何将这些动态获取的数据填充到模板中的（下面所描述的解析工作均是菜鸟打印组件自动完成，这里只是为了加深理解而进行的说明）。

1、在上述报文中，自定义模板数据为:

url:https://cloudprint.cainiao.com/template/802，对应的就是一个动态模板，将这个url发送给菜鸟打印组件后，打印组件会自动解析下载这个模板，其内容如下:。可以看到，有一个动态变量"<%=_data.goodsInfo%>"。（注:这是一个虚拟的url，真实的url应该调用top接口获得）

<page xmlns:editor="http://cloudprint.cainiao.com/schema/editor" width="100" height="30">
        <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、那么将上述报文发送给菜鸟打印组件后，生成的模板数据如下:

<page xmlns:editor="http://cloudprint.cainiao.com/schema/editor" width="100" height="30">
        <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预览。

响应协议格式如下:

{
    "cmd":"print",
    "requestID":"123458976",
    "taskID":"1",
    "status":"success", //如果是打印，表示打印任务提交成功，如果是预览，表示预览PDF文件生成成功
    "previewURL":"http://127.0.0.1/previewxxx.pdf", //如果是预览，会返回这个属性，表示预览PDF文件的URL地址，如果是打印命令，不返回此属性
//如果是预览并且预览模式是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)

请求协议格式如下:

{
    "cmd":"getTaskStatus",
    "requestID":"123458976",
    "version":"1.0",
    "taskID":[
        "12311",
        "12312"
    ]
}

字段名	类型	说明	是否必须
taskID	json数组	打印机任务ID列表	是

响应协议格式如下:

{
    "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)

请求协议格式如下:

{
    "cmd":"getDocumentStatus",
    "requestID":"123458976",
    "version":"1.0",
    "documentIDs":[
               "9789173491296",
               "9890000112011"
    ]
}

字段名	类型	说明	是否必须
documentIDs	array	文档的唯一ID数组	是

响应协议格式如下:

{
     "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)

通知协议格式如下:

{
     "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)

请求协议格式如下:

{
    "cmd":"getGlobalConfig",
    "requestID":"12345678901",
    "version":"1.0"
}

响应协议格式如下:

{
    "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)

请求协议格式如下:

{
    "cmd":"setGlobalConfig",
    "requestID":"12345678901",
    "version":"1.0",
    "notifyOnTaskFailure":true
}

响应协议格式如下:

{
    "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)

请求协议格式如下:

{
    "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对象重用，和打印组件保持长连接。

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()
{
    socket = new WebSocket('ws://localhost:13528');
    //如果是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 动态链接库

1、下载相关源代码和动态库

PrinterManager提供以下接口,调用约定 stdcall 方式:

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.

以获取打印机列为例:
获取打印机列表命令如下:

{
    "cmd":"getPrinters",
    "requestID":"123458976",
    "version":"1.0"
}

DEMO中采用cJSON开源库作为生成JSON数据的工具:

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;
}

构造打印指令代码如下:

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需要引入第三方库下载地址。

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.3.0</version>
</dependency>

自己创建一个websocket管理类，需要继承自第三方类库的WebSocketClient:

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 {
        String uri = "ws://127.0.0.1:13528";
        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 方式，请下载相关源代码和动态库。

动态接口说明如下:

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下使用方式如下:

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.

FAQ

关于此文档暂时还没有FAQ

TOP接口说明

更新时间：2017/07/17 访问次数：2868

1 开放的接口

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可以提供带有循环功能的打印项，在模板编辑中打开代码模式。一个示例为：提供“商品列表”这么一个打印项，商家选择这个打印项之后就会循环输出所有商品名，则打印项的示例代码如下：

<%
  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

FAQ

关于此文档暂时还没有FAQ

有用(66)

模板迁移方案

更新时间：2017/07/17 访问次数：1639

采用云打印组件后，快递标准面单的上联部分采用菜鸟提供的模板，自定义区采用商家自己设计的格式。因此，只需转换与迁移商家自定义区即可。

模板迁移

整个模板迁移分为两步：模板转换和自定义区导入

lodop自定义区转换服务

提供了一个url的模板转换程序，该服务用于将原有的lodop的自定义区转换成菜鸟官方模板。

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[]]中，如下图所示：

![](http://aligitlab.oss-cn-hangzhou-zmf.aliyuncs.com/uploads/waybill/waybill-print/4055229e866b583c05581b0b45e3919f/cdata.png) 
![](http://aligitlab.oss-cn-hangzhou-zmf.aliyuncs.com/uploads/waybill/waybill-print/6853e88a23de647dab04d46d77d75af0/value.png)

hasVar:
如果为true，最终生成的变量内容为：<![CDATA[<%=_data.param%>]]>，否则为<![CDATA[param]]>
对于非lodop格式的模板，isv需要自己开发一个转换程序来转成菜鸟的自定义区模板，格式如下：

<?xml version="1.0" encoding="UTF-8"?>
        <layout  id="CUSTOM_AREA"
            xmlns="http://cloudprint.cainiao.com/print"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://cloudprint.cainiao.com/print http://cloudprint-docs-resource.oss-cn-shanghai.aliyuncs.com/lpml_schema.xsd"
            xmlns:editor="http://cloudprint.cainiao.com/schema/editor"
             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

云打印编辑器千牛免登

更新时间：2017/12/19 访问次数：1316

1 url跳转优化方案

ISV模板编辑器跳转到菜鸟的官方编辑器，为了简化商家的使用成本（跳过身份选择页以及所使用的服务），对url跳转方案进行了优化

http://cloudprint.cainiao.com/cloudprint/templates.htm?identity=xxx&appKey=xxx

url中新增两个参数identity和appKey。其中identity为身份，包括seller和isv，对于商家来说，就固定为seller；这样商家在登陆后，就不用选择自己的身份以及使用的服务。

2 千牛免登

对于千牛平台的系统，除了上述的url跳转优化外，还可以进一步跳过登录页面：

2.1 跳转到模板选择页

可以使用如下的跳转地址：

http://cloudprint.cainiao.com/cloudprint/templates.htm?identity=seller&appKey=xxx

其中：identity和appKey的含义同第二节“url跳转优化方案”；xxx需要根据实际值进行替换，其余部分固定

2.2 跳转到模板编辑页

可以使用如下的跳转地址：

以商家身份跳转

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身份跳转

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

关于此文档暂时还没有FAQ

有用(0) 我要提问

菜鸟云打印标记语言规范

更新时间：2018/01/05 访问次数：2302

文档 >>> 菜鸟打印交互协议菜鸟模板编辑器

1、简介

2、page(页)

3、layout(布局)

4、text(文本)

5、line(线条)

6、rect(矩形)

7、barcode(条码与二维码)

8、image(图片)

9、table(表格)

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，示例：

<layout left="1.8" top="2.2" width="8.3" height="2.5" id="1">
</layout>

采用相对父节点的坐标进行描述
效果如下图：

3-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”)：
3.7.a-水平布局图
水平布局中的元素，都以水平模式排列。

b. 垂直布局如下图(如orientation=“vertical”)：
3.7.b-垂直布局图
垂直布局中的元素，都以垂直模式排列。

3.8 style(样式)

layout可用的style属性如下，详细含义请查看(style样式)

属性名	说明
zIndex	图层
overflow	超出处理
backgroundColor	背景色
borderWidth	边框宽度
borderStyle	边框样式
margin	元素外边距
padding	元素内边距

4. text(文本)

画布的基础元素，文本自身无边框，只有里面的文本内容。
如果只是简短文本并且文本中没有特殊字符可以如下方式使用：

<text width="5.6" value="菜鸟网络" style="fontSize:16"/>

效果如下图：
4-文本效果图

如果文本比较长或者有换行需求，可以使用

<text width="5.6" style="fontSize:16">
line 1
line 2
</text>

注意：每一行文本前后的空白字符都会被保留。

如果文本中有特殊字符，如“，&，‘，<,>等等xml规范中的特殊字符，可以如下方式使用,这种方式文本中的特殊字符不会被转义：

<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(线条)

画布的基本元素，线条用来画从一个起点到一个终点之间的连线。
示例：

<line startX="3.2" startY="5.5" endX="10.2" endY="6.5"  style="lineType:solid" />

效果如下图(蓝色为所画线条)：

5-线条效果图

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(矩形)

画布的基础元素，用来描绘一块区域。如

<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-矩形效果图

6.1 width(宽度)

矩形的宽度，如width=“30.3”。

6.2 height(高度)

矩形的高度，如height=“1.5”。

6.3 style(样式)

参考(style样式)

属性名	说明
rotation	旋转角度
fillColor	填充色
borderWidth	边框宽度
borderStyle	边框样式

7.barcode(条码与二维码)

画布的基础控件，条形码根据数据生成的图片。
示例：

< 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规范中的特殊字符，可以如下方式使用,这种方式文本中的特殊字符不会被转义：

<barcode width="2.5" height="7.0" type="code128a" style="hideText:true">
<![CDATA[123987af<>!&*$#]]>
</barcode>

备注：如果要输出“<%”或“%>”，需要添加“"做转义，也即”<\%“或”%>" 。

效果图如下：

7-条形码效果图

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(图片)

画面的基础控件，插入静态图片资源。
示例：(真实的图片)

<layout left="1.8" top="2.2" width="8.3" height="3.5">
    <image width="5.5" height="4.5" src="http://www.taobao.com/test.jpg" />
</layout>

效果如下图：

9-图片效果图

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，也可以是文本，图片，二维码，线条，矩形元素。

<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-样式效果图

元素框的最内部分是实际的内容，直接包围内容的是内边距。

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中多个基础控件的对齐效果图，右图为一个文本框中的文字对齐效果图。

10.3.c右对齐1 10.3.c右对齐2

valign(垂直对齐)
垂直对齐方式，枚举值(top为上对齐，middle为居中，bottom为下对齐)。
- a. 上对齐的效果图如下(valign:top)：
  左图为一个layout中多个基础控件的对齐效果图，右图为一个文本框中的文字对齐效果图。

10.4.a上对齐1
10.4.a上对齐2

- b. 居中对齐的效果图如下(valign:middle)：
左图为一个layout中多个基础控件的对齐效果图，右图为一个文本框中的文字对齐效果图。

10.4.b居中对齐1 10.4.b居中对齐2

- c.    下对齐的效果图如下(valign:bottom)：
    左图为一个layout中多个基础控件的对齐效果图，右图为一个文本框中的文字对齐效果图。

10.4.c下对齐1 10.4.c下对齐2

10.3 字体

fontColor(字体颜色)

字体颜色，字符串类型，颜色由一个十六进制符号来定义，这个符号由红色、绿色、蓝色的值组成(RGB)。每种颜色的最小值是0(十六进制：#00)，最大值255(十六进制：#FF)。格式为#rrggbb。如fontColor:#120FAC。
默认为黑色 fontColor:#000000。
fontFamily(字体类型)

字体类型，字符串型。默认为宋体。省略则用默认宋体。如果选择的字体当前系统不支持，则使用默认的宋体。
- a. 宋体的效果图如下(fontFamily:宋体)：

10.10宋体效果图

- b.    楷体的效果图如下(fontFamily:华文行楷)：

10.10.b楷体效果图

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.16字符间距效果图

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”；
效果图如下：

10.15行高效果图

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。

10.2-样式透明度

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

有用(1)

模板设计说明

更新时间：2017/07/10 访问次数：1594

模板绘制

这里的模板是指依据菜鸟打印标记语言规范设计出来的面单模板。为了更加快速的进行模板设计与生成，可采用菜鸟官方提供的模板编辑器（菜鸟模板编辑器）。

模板设计

通过视图方式进行控件拖拽的方式来生成模板（此时会自动生成代码）
通过在代码编辑页面中直接键入符合菜鸟模板标记语言的代码来生成模板（此时会自动根据代码绘制出视图）

模板内容

模板内容分为两种：静态内容和动态内容。

静态内容：在模板绘制的过程中，值就确定的内容我们称之为静态内容。在编辑器中进行模板设计的时候就可以将内容输入进去。
动态内容：在绘制模板的过程中，我们经常希望只放入一个占位符，其内容将在实际打印时才能确定，我们称之为动态内容。为了支持这种动态内容，在模板中可以通过编写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）中的所有对象依次输出。

<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>

数据：

[
    ["收件人"],
    ["发件人"],
    [ "收货地址"]
]

动态代码解析之后的静态代码为：

<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”。
标准板示例：

<?xml version="1.0" encoding="UTF-8"?>
<page xmlns="http://cloudprint.cainiao.com/print" width="100" height="180">
        <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>

商家自定义区示例：

<?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

FAQ

关于此文档暂时还没有FAQ

posted @ 2018-02-06 10:00 特洛伊-Micro 阅读(6732) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

常用取值	描述
light	定义较细的字符。
normal	默认值，定义标准的字符。
bold	定义粗体字符。