模板设计说明

模板绘制

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

模板设计

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

模板内容

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

静态内容：在模板绘制的过程中，值就确定的内容我们称之为静态内容。在编辑器中进行模板设计的时候就可以将内容输入进去。
动态内容：在绘制模板的过程中，我们经常希望只放入一个占位符，其内容将在实际打印时才能确定，我们称之为动态内容。为了支持这种动态内容，在模板中可以通过编写ECMAScript脚本来达到生成动态内容的目的。同时对ECMAScript的解析采用了目前业界最先进的V8引擎，具有极高的性能，在打印服务生成打印文件前，会对ECMAScript的代码进行解析并替换为实际值。

动态内容的编写

动态内容可以嵌入类似js的代码，在模板中可以通过如下的方式嵌入动态代码:

动态语句: 以<%开始，以%>结束，如<% if(true) %>。
变量引用: 以<%=开始，以%>结束，如<%=_data.address%>，表示将会用data.address的实际值在模板中进行填充。允许使用自定义的变量。
注：模板中的 _data 表示 json 数据 data字段（表示数据的根节点）
如果内容中要输出<%或者<%=，需要添加\做转义，也即<\%。
包含文件: <%@ 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()	当前打印的页数
documentCount()	打印总页数

注：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<_data.arrayObject.length;i++) {%>
            <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="动态数据显示" />
        <% for(i=0;i<_data.arrayObject.length;i++) {%>
            <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>

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

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

模板设计说明 ​

模板绘制 ​

模板设计 ​

模板内容 ​

动态内容的编写 ​

模板布局说明 ​

模板设计示例 ​