菜鸟打印标记语言规范 ​

1、简介 ​

菜鸟打印标记语言是菜鸟官方定义的一套用于描述打印内容的标准，其定义了一套标准规范，通过这套标记语言，可以：

• 确保优质的打印效果。我们没有选用已有的HTML标记语言，是由于HTML是为了屏幕渲染为目标而设计的，我们是为打印而设计的，设计目标不同在很多细节的处理上会完全不一样。
• 高效传输。服务器向打印服务客户端传递的数据并非最终打印页面，而是标记语言的内容，由打印服务根据数据进行绘制，可有效减少数据传输量。
• 屏蔽硬件差异。

如果熟悉HTML语言或者JavaScript，那么很容易就会熟悉菜鸟打印标记语言，我们在设计该套语言标准的时候尽量参考HTML规范，且相较HTML来说更加的精简。

本规范中除文本外的其他元素，单位均支持毫米（mm）和磅（pt）,默认单位是mm(毫米),mm可以省略，如width=20.5,下文如不做特别说明，单位一律是mm（毫米）。 坐标系以左上角为起点（0，0）。

1.1 元素概览 ​

打印标记语言所包含的元素如下：

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>

<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样式)

4、text(文本) ​

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

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

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

效果如下图：

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

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

<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 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样式)

5、line(线条) ​

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

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

<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样式)

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>

<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样式)

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>

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

<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 ratioMode(比例模式) ​

条形码的比例模式，keepRatio保持比例、 ignoreRatio忽略比例，即条码会填充所在区域。

7.6 primary(MaxiCode特有属性) ​

生成条码需要到的部分核心信息，邮编+国家代号+服务商等级

7.7 mode(MaxiCode特有属性) ​

取值2到6，1被废弃，取值含义如下：

2：主要信息为一个结构化收件人信息加上一个数字型态的邮递编号，次要信息至多可编入84个字元(character)。mode=2

3：主要信息为一个结构化收件人信息加上一个文数字型态的邮递编号，次要信息至多可编入84个字元。mode=3

4：主要信息加上次要信息至多可编入93个字元。模式4是标准符号，其指示在主要信息部分采用EEC，而在次要信息部分采用SEC，这种模式下共有93个资料字码。mode=4

5：主要信息加上次要信息至多可编入77个字元。模式5是全EEC模式，其指示在主要信息及次要信息部份全部采用EEC，符号有77个资料字码。mode=5

6：主要信息加上次要信息至多可编入93个字元。模式6为扫瞄器编程模式，其指示符号表示的信息是用于扫瞄器编程，主要信息采用EEC，次要信息采用SEC。mode=6

参考(style样式)

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" allowFailure="false"/>
</layout>

<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" allowFailure="false"/>
</layout>

效果如下图：

8.1 width(宽度) ​

图片的宽度，如width=“5.5”。

8.2 height(高度) ​

图片的高度，如height=“4.5”。

8.3 style（样式） ​

详见(style样式)

8.4 src(图片路径url) ​

图片的资源路径，字符串型。如src="http://www.taobao.com/test.jpg"

8.5 allowFailure（图片下载失败是否允许） ​

false-打印会报错 true-忽略失败

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>

<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支持的属性 ​

• table必须指定width属性，单位毫米（mm）。
• table不支持height属性 ，table的高度会根据表头的高度和各行的总高度来做自动适应，如果指定了height属性，也会被忽略

9.2.2 table支持的style ​

• 表头和单元格的边框样式支持设置1个或两个值，第一个值表示横线的宽度或样式，第二个值表示竖线的宽度或样式；如果设置一个值，表示横竖样式一致
• headerBorderWidth和headerBorderStyle不设置时，默认采用cellBorderWidth和cellBorderStyle
• cellBorderWidth和cellBorderStyle不设置时，默认线条宽度是1pt，样式是solid（实线）

9.3 tr（行） ​

tr目前暂不支持属性

9.4 th（表头） ​

9.4.1 th属性 ​

• th支持width属性，用于指定列宽，该属性为必选项
• width属性支持如下两种类型：
  • 百分比：30%， 占整个表格宽度的30%
  • 固定值：单位为mm
• 为兼容旧的表格定义，table里面可以不包含表头行，但是对新创建的模板，table元素推荐加上表头行

9.4.2 style(样式) ​

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

9.5 td（单元格） ​

9.5.1 td属性 ​

• 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样式)

9.6 表格对分页的支持 ​

• 如果指定了表头，则分页时，每页都会带上表头
• 分页是以行为单位，如果改行有单元格设置了rowspan属性，则相关的行都要在一页上打印

10、header/footer(页眉页脚) ​

页眉页脚只有isv自定义模板才有权限编辑。 编辑其中添加页眉页脚默认的高度是30；选中页眉或页脚，可以向里面插入元素，且元素的坐标点都是相对页眉或页脚

10.1 header(页眉) ​

页眉始终位于页面的顶部，页眉的宽度始终是模板页面的宽度，只可以改变页眉的高度。

10.1.1 header支持的属性 ​

• header必须指定height属性，单位毫米（mm）。
• header不支持width属性 ，页眉的宽度始终是模板页面的宽度，如果指定了width属性，也会被忽略

<header height="40" >
...
</header>

<header height="40" >
...
</header>

10.2 页脚(footer) ​

页脚始终位于页面的底部，页脚的宽度始终是模板页面的宽度，只可以改变页脚的高度。

10.2.1 header支持的属性 ​

10.3 页码(pageIndex) ​

展示自定义模板的页码，此标签只能放在页脚标签中使用 支持currentPageNumber(当前页码)和totalPageNumber(总页码)属性，根据分页自动计算。示例如下：

<footer height="20" >
     <layout width="100" height="10" left="180" top="1"  style="overflow:visible;">
     <pageIndex format="第currentPageNumber页 共totalPageNumber页" style="fontSize:10;"></pageIndex>
     </layout>
</footer>

<footer height="20" >
     <layout width="100" height="10" left="180" top="1"  style="overflow:visible;">
     <pageIndex format="第currentPageNumber页 共totalPageNumber页" style="fontSize:10;"></pageIndex>
     </layout>
</footer>

11、style(样式) ​

样式不是画布的基础元素，用来描述基础元素的展现形式。

样式由一组属性组成，每个属性有一个值，属性名称和值通过冒号分开。如property:value。

多个样式属性之间使用分号分开，属性之间的空格会被忽略。如style=“alpha:0.6; align:left;”。

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

11.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）。

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

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

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

11.3 字体 ​

fontColor(字体颜色) ​

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

fontFamily(字体类型) ​

字体类型，字符串型。默认为宋体。省略则用默认宋体。如果选择的字体当前系统不支持，则使用默认的宋体。

• a. 宋体的效果图如下(fontFamily:宋体)：

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

fontSize(字体大小) ​

字体大小，单位为磅，如fontSize:12pt，字体大小缺省值为8pt。

需特别注意，单位不能是mm（毫米）。

fontWeight(字体粗细) ​

设置文本字体的粗细，枚举型，light、normal、bold，如“fontWeight: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。

  效果图如下：

11.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）枚举值。

• a.横排效果图如下图(orientation:horizontal)
• b.竖排效果如下图(orientation:vertical)

11.5 线条与边框 ​

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

• a. 如borderStyle: solid dashed dotted solid

  上线条实线，右线条破折线，下线条点线，左线条实线。

• b. 如borderStyle:solid dashed dotted

  上线条实线，左右线条破折线，下线条点线。

• c. 如borderStyle:solid dashed

  上下线条实线，左右线条破折线。

• d. 如borderStyle:solid

  上下左右线条实线。

11.6 其他样式 ​

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。