模板类型

模板文档 PrintDocument 的全部类型，按 @xihan-print/core 的源码列出。当前 schema 版本 PRINT_SCHEMA_VERSION 为 1。

长度单位为 mm，字号与字间距单位为 pt，角度单位为度；颜色写作 #RGB、#RGBA、#RRGGBB、#RRGGBBAA 或 transparent。

文档与页面

PrintSchemaVersion

模板 schema 版本号类型。

类型：typeof PRINT_SCHEMA_VERSION

PaperSpec

纸张。宽高为纵向尺寸，单位 mm；横向时宽高互换。

字段	类型	必填	说明
preset	PaperPresetName	可省	来源预设，自定义纸张不填。
width	number	是
height	number	是

PageBand

页眉或页脚的一个带区。

字段	类型	必填	说明
height	number	是	带区高度，单位 mm。
elements	PrintElement[]	是	带区内的元素，坐标相对纸张左上角。

PageBandSet

页眉或页脚：default 为常规带区，其余为按输出页命中的变体。命中顺序为首页、末页、奇偶页，都未命中时使用 default。

字段	类型	必填	说明
default	PageBand	是
first	PageBand	可省
last	PageBand	可省
odd	PageBand	可省
even	PageBand	可省
singleSheet	SingleSheetPreference	是	输出页既是首页又是末页且两种变体都存在时采用哪一个。

PageNumbering

页码编号规则。

字段	类型	必填	说明
continuous	boolean	是	是否接续上一页面模板的页码；为 false 或没有上一页面模板时从 start 开始。
start	number	是	起始页码。

Watermark

平铺文字水印。

字段	类型	必填	说明
text	string	是	水印文字，支持 {{path}} 占位。
fontFamily	string	可省
fontSize	number	是	字号，单位 pt。
color	Color	是
opacity	number	是	不透明度，0 到 1。
rotation	number	是	逆时针旋转角度。
gapX	number	是	相邻水印的水平间距，单位 mm。
gapY	number	是	相邻水印的垂直间距，单位 mm。

PageGuides

参考线：设计时对位用，不参与分页也不打印；坐标相对纸张左上角（按页面方向换算后的纸张），单位 mm。

字段	类型	必填	说明
x	number[]	是	竖线的横坐标。
y	number[]	是	横线的纵坐标。

PrintPage

页面模板：一份页面模板按数据量排出一张或多张输出页。页眉位于上边距之下，页脚位于下边距之上，两者之间为正文区。

字段	类型	必填	说明
id	string	是	页面标识，在整份文档内唯一。
name	string	可省
paper	PaperSpec	是
orientation	PageOrientation	是
margins	Edges	是	页边距，单位 mm。
header	PageBandSet	是
footer	PageBandSet	是
elements	PrintElement[]	是	正文元素，坐标相对纸张左上角。
numbering	PageNumbering	是
watermark	Watermark	可省
guides	PageGuides	可省
meta	JsonObject	可省
extensions	JsonObject	可省	扩展自己的数据，键是扩展 id。

PrintDocument

打印模板文档。

字段	类型	必填	说明
schemaVersion	PrintSchemaVersion	是
name	string	可省
pages	PrintPage[]	是
meta	JsonObject	可省
extensions	JsonObject	可省	扩展自己的数据，键是扩展 id。

元素

ElementBase

全部元素共有的字段。坐标相对纸张左上角，单位 mm。

字段	类型	必填	说明
id	string	是	元素标识，在整份文档内唯一。
type	TType	是
name	string	可省	设计器中显示的名称。
x	number	是
y	number	是
width	number	是
height	number	是
locked	boolean	可省	是否锁定，锁定的元素在设计器中不可拖动与缩放。
previewOnly	boolean	可省	是否只在设计与预览中显示、不参与打印。
meta	JsonObject	可省	宿主附加数据。
extensions	JsonObject	可省	扩展自己的数据，键是扩展 id；core 只检查它是对象，里面不看。

TextElement

固定尺寸的文本。

继承 ElementBase<'text'> 的字段。

字段	类型	必填	说明
content	TextContent	是
style	TextStyle	是
wrap	boolean	是	是否自动换行。
overflow	TextOverflow	是
rotation	number	是	绕中心顺时针旋转的角度。
box	BoxStyle	可省

LongTextElement

随内容纵向延展并可跨页续排的长文本。

继承 ElementBase<'longText'> 的字段。

字段	类型	必填	说明
content	TextContent	是
style	TextStyle	是
box	BoxStyle	可省

RichTextContent

富文本的内容来源：模板里写死的文档，或从数据字段读取。字段值是 HTML 串时（source 为 html）按白名单换成文档，字段值已是富文本文档对象时 source 为 document。文档是 @xihan-ui/core/rich-text 的 RichTextDocument，其中行内字段的 format 按值格式解释。

类型：| { kind: 'static', document: RichTextDocument } | { kind: 'field', field: string, source: RichTextSource }

RichTextElement

随内容纵向延展并可跨页续排的富文本：段落、标题、列表、分隔线与带样式的文字。

继承 ElementBase<'richText'> 的字段。

字段	类型	必填	说明
content	RichTextContent	是
style	TextStyle	是	基准样式：块与行内的样式在它之上覆写。
box	BoxStyle	可省

TableElement

绑定数组数据、随行数延展并可跨页续排的表格。

继承 ElementBase<'table'> 的字段。

字段	类型	必填	说明
dataField	string	是	数组数据的字段路径。
columns	TableColumn[]	是
header	TableHeader	是
body	TableBody	是
footerRows	TableFooterRow[]	是
maxRowsPerPage	number	可省	每页最多显示的数据行数，缺省按可用高度排满。
fillEmptyRows	boolean	是	数据行不足时是否用空行补齐到每页最大行数或可用高度。
border	TableBorder	是

ImageElement

图片。

继承 ElementBase<'image'> 的字段。

字段	类型	必填	说明
source	ImageSource	是
fit	ImageFit	是
rotation	number	是
box	BoxStyle	可省

LineElement

直线，走向由元素框和方向共同决定。

继承 ElementBase<'line'> 的字段。

字段	类型	必填	说明
direction	LineDirection	是
stroke	Stroke	是

RectElement

矩形。

继承 ElementBase<'rect'> 的字段。

字段	类型	必填	说明
stroke	Stroke	可省	边线，缺省不画边。
fill	Color	可省	填充色，缺省不填充。
radius	number	是	圆角半径，单位 mm。
rotation	number	是

EllipseElement

椭圆，内切于元素框。

继承 ElementBase<'ellipse'> 的字段。

字段	类型	必填	说明
stroke	Stroke	可省
fill	Color	可省
rotation	number	是

BarCodeTextStyle

条码下方文字的样式。

字段	类型	必填	说明
fontFamily	string	可省
fontSize	number	是	字号，单位 pt。

BarCodeElement

一维条码。

继承 ElementBase<'barCode'> 的字段。

字段	类型	必填	说明
format	BarCodeFormat	是	码制，取值见 @xihan-ui/headless 的 BAR_CODE_FORMATS。
content	TextContent	是
showText	boolean	是	是否在条码下方显示编码文字。
textStyle	BarCodeTextStyle	是
color	Color	是
rotation	number	是

MatrixCodeElement

二维码：QR、Data Matrix、PDF417、Aztec。

继承 ElementBase<'matrixCode'> 的字段。

字段	类型	必填	说明
format	MatrixCodeFormat	是
content	TextContent	是
level	MatrixCodeLevel	可省	纠错级别：qr 为 L / M / Q / H，pdf417 为 0–8，aztec 为纠错码字至少占的百分比 5–95，data-matrix 没有级别；缺省取码制的默认值。
color	Color	是
background	Color	可省
quietZone	number	是	四周静区宽度，单位为模块数。
rotation	number	是

PageNumberElement

页码。

继承 ElementBase<'pageNumber'> 的字段。

字段	类型	必填	说明
format	string	是	页码格式：{{path}} 文本模板，可用的宿主变量为 $page（当前页码）与 $pages（所在编号段的总页数），如 第 {{$page}} 页 / 共 {{$pages}} 页。
numeral	NumeralStyle	可省	页码的数字字形，即 @xihan-ui/expression 的 numeral 格式（罗马数字、中文数字）；缺省为阿拉伯数字。
style	TextStyle	是
box	BoxStyle	可省

ExtensionElement

扩展登记的元素：通用字段之外的属性由扩展的原型定义，取值都是 JSON。

继承 ElementBase<string> 的字段。

字段	类型	必填	说明
``	JsonValue | undefined	是

PrintElement

内置元素。

取其一：TextElement、LongTextElement、RichTextElement、TableElement、ImageElement、LineElement、RectElement、EllipseElement、BarCodeElement、MatrixCodeElement、PageNumberElement。

PrintElementType

内置元素类型。

类型：PrintElement['type']

PrintElementOf

按类型取元素接口。

类型：Extract<PrintElement,>

表格

CellStyle

单元格样式。

字段	类型	必填	说明
fontFamily	string	可省
fontSize	number	是	字号，单位 pt。
bold	boolean	是
italic	boolean	是
color	Color	是
background	Color	可省
align	HorizontalAlign	可省	水平对齐，缺省跟随列的对齐方式。
verticalAlign	VerticalAlign	是
padding	number	是	左右内边距，单位 mm。
lineHeight	number	是	单元格文字每一行的高度，单位 mm。

TableFieldCellContent

表体单元格显示行内字段。

字段	类型	必填	说明
kind	'field'	是
field	string	是	行对象内的字段路径。
format	ValueFormat	可省
emptyText	string	可省

TableTemplateCellContent

表体单元格按行对象替换 {{path}} 占位。

字段	类型	必填	说明
kind	'template'	是
template	string	是

TableRowNumberCellContent

表体单元格显示从 1 开始、跨页连续的行序号。

字段	类型	必填	说明
kind	'rowNumber'	是

TableExpressionCellContent

表体单元格以受限表达式计算，表达式中的变量为行对象的顶层字段。

字段	类型	必填	说明
kind	'expression'	是
expression	string	是	受限表达式源码。
format	ValueFormat	可省	计算结果的格式。

TableCellContent

表体单元格内容来源。

取其一：TableFieldCellContent、TableTemplateCellContent、TableRowNumberCellContent、TableExpressionCellContent。

TableColumn

表格列。

字段	类型	必填	说明
id	string	是	列标识，在所属表格内唯一。
title	string	是	表头文本。
width	number	是	列宽，单位 mm。
align	HorizontalAlign	是
content	TableCellContent	是
cellType	TableCellType	是
barCodeFormat	BarCodeFormat	可省	条码码制，cellType 为 barCode 时必填；matrixCode 单元格按 QR 编码。

TableHeader

表头。

字段	类型	必填	说明
visible	boolean	是
repeat	boolean	是	表格跨页时是否在每一页重复表头。
height	number	是	表头行高，单位 mm。
style	CellStyle	是

TableBody

表体。

字段	类型	必填	说明
rowHeight	number	是	行高，单位 mm；rowHeightMode 为 minimum 时作为最小行高。
rowHeightMode	TableRowHeightMode	是
style	CellStyle	是

AggregateCellContent

表尾单元格的汇总内容。

字段	类型	必填	说明
kind	'aggregate'	是
fn	AggregateFunction	是
field	string	可省	参与汇总的行内字段路径；fn 为 count 时可省略，表示统计行数。
scope	AggregateScope	是
format	ValueFormat	可省

TableFooterCellContent

表尾单元格内容：固定文本、根数据字段、根数据模板或汇总值。

取其一：TextContent、AggregateCellContent。

TableFooterCell

表尾单元格。

字段	类型	必填	说明
columnId	string	是	起始列的标识。
colSpan	number	是	向右跨越的列数，至少为 1。
content	TableFooterCellContent	是
align	HorizontalAlign	可省	水平对齐，缺省跟随行样式再跟随起始列。

TableFooterRow

表尾行，可承载固定文字、根数据字段与汇总值。

字段	类型	必填	说明
id	string	是	行标识，在所属表格内唯一。
placement	TableFooterPlacement	是
height	number	是	行高，单位 mm。
style	CellStyle	是
cells	TableFooterCell[]	是

TableBorder

表格网格线。

字段	类型	必填	说明
stroke	Stroke	是
outer	boolean	是	是否画外框。
horizontal	boolean	是	是否画行之间的横线。
vertical	boolean	是	是否画列之间的竖线。

通用类型

Color

颜色：#RGB、#RGBA、#RRGGBB、#RRGGBBAA 或 transparent。

类型：string

Edges

四边距离，单位 mm。

字段	类型	必填	说明
top	number	是
right	number	是
bottom	number	是
left	number	是

Stroke

描边。

字段	类型	必填	说明
width	number	是	线宽，单位 mm。
style	StrokeStyle	是
color	Color	是

BorderSides

四边边框，缺省的一边不画线。

字段	类型	必填	说明
top	Stroke	可省
right	Stroke	可省
bottom	Stroke	可省
left	Stroke	可省

BoxStyle

元素外框样式。

字段	类型	必填	说明
background	Color	可省	背景色，缺省为透明。
border	BorderSides	可省
padding	Edges	可省	内边距，单位 mm。

TextStyle

文本样式。

字段	类型	必填	说明
fontFamily	string	可省	字体族，缺省使用运行时默认字体。
fontSize	number	是	字号，单位 pt。
bold	boolean	是
italic	boolean	是
underline	boolean	是
lineThrough	boolean	是
color	Color	是
align	TextAlign	是
verticalAlign	VerticalAlign	是
lineHeight	number	是	行高，字号的倍数。
letterSpacing	number	是	字间距，单位 pt。

ValueMapEntry

值映射的一项：数据值（按字符串比较）与显示文本，与选择类组件的选项同一形状（不带 disabled）。没有 label 时命中这一项显示为空。

字段	类型	必填	说明
value	string	是
label	string	可省

MapFormat

值映射格式：按数据值查表显示文本。

字段	类型	必填	说明
kind	'map'	是
entries	ValueMapEntry[]	是
fallback	string	可省	未命中任何映射时显示的文本，缺省显示原值。

ExpressionFormat

表达式格式：以受限表达式把值转成显示文本，表达式中以 value 引用待格式化的值。

字段	类型	必填	说明
kind	'expression'	是
expression	string	是	受限表达式源码。

ValueFormat

值格式：数字、百分比、日期与人民币大写即 @xihan-ui/expression 的 FormatSpec，交给注入的格式化器；值映射在本包内完成，表达式格式经表达式接入点。

取其一：FormatSpec、MapFormat、ExpressionFormat。

StaticTextContent

固定文本。

字段	类型	必填	说明
kind	'static'	是
text	string	是

FieldTextContent

绑定单个数据字段。

字段	类型	必填	说明
kind	'field'	是
field	string	是	字段路径，写法同 @xihan-ui/core/json 的 formatJsonPath，如 customer.name、items[0].qty。
format	ValueFormat	可省
emptyText	string	可省	字段值为空时显示的文本。

TemplateTextContent

含 {{path}} 占位的文本模板，占位按数据字段替换。

字段	类型	必填	说明
kind	'template'	是
template	string	是

ExpressionTextContent

以受限表达式计算的文本，表达式中的变量为数据对象的顶层字段。

字段	类型	必填	说明
kind	'expression'	是
expression	string	是	受限表达式源码。
format	ValueFormat	可省	计算结果的格式。

TextContent

文本内容来源。

取其一：StaticTextContent、FieldTextContent、TemplateTextContent、ExpressionTextContent。

StaticImageSource

固定地址的图片。

字段	类型	必填	说明
kind	'static'	是
url	string	是	图片地址：http(s)、data:image、blob 或相对地址。

FieldImageSource

从数据字段读取图片地址。

字段	类型	必填	说明
kind	'field'	是
field	string	是

ImageSource

图片来源。

取其一：StaticImageSource、FieldImageSource。

取值

PageOrientation

页面方向：portrait 纵向，landscape 横向（宽高互换）。

取值见常量 PAGE_ORIENTATIONS：

取值	中文名
portrait	纵向
landscape	横向

PageBandVariant

页眉页脚变体：first 首页、last 末页、odd 奇数页、even 偶数页（按页码奇偶）。

取值见常量 PAGE_BAND_VARIANTS：

取值	中文名
first	首页
last	末页
odd	奇数页
even	偶数页

PageBandKey

页眉页脚的全部带区键，default 为未命中任何变体时使用的带区。

类型：'default' | PageBandVariant

TextAlign

文本水平对齐。

取值见常量 TEXT_ALIGNS：

取值	中文名
left	左
center	居中
right	右
justify	两端对齐

HorizontalAlign

单元格水平对齐。

取值见常量 HORIZONTAL_ALIGNS：

取值	中文名
left	左
center	居中
right	右

VerticalAlign

垂直对齐。

取值见常量 VERTICAL_ALIGNS：

取值	中文名
top	上
middle	居中
bottom	下

StrokeStyle

线型。

取值见常量 STROKE_STYLES：

取值	中文名
solid	实线
dashed	虚线
dotted	点线
double	双线

TextOverflow

固定尺寸文本的溢出处理：clip 裁切，shrink 缩小字号以容纳，visible 允许溢出显示。

取值见常量 TEXT_OVERFLOWS：

取值	中文名
clip	裁掉
shrink	缩小字号
visible	照常显示

RichTextSource

富文本字段的内容格式：html 为 HTML 串，按白名单换成文档；document 为富文本文档对象。

取值见常量 RICH_TEXT_SOURCES：

取值	中文名
html	HTML
document	富文本文档

ImageFit

图片在元素框内的适配方式。

取值见常量 IMAGE_FITS：

取值	中文名
contain	完整显示
cover	铺满裁切
fill	拉伸铺满
none	原始大小

LineDirection

直线在元素框内的走向：horizontal 沿垂直中线，vertical 沿水平中线，diagonalDown 左上到右下，diagonalUp 左下到右上。

取值见常量 LINE_DIRECTIONS：

取值	中文名
horizontal	水平
vertical	竖直
diagonalDown	左上到右下
diagonalUp	左下到右上

BarCodeFormat

转导出自 @xihan-ui/headless。取值：code128、ean13、ean8、upca、upce、itf14、code39。

MatrixCodeFormat

转导出自 @xihan-ui/headless。取值：qr、data-matrix、pdf417、aztec。

MatrixCodeLevel

转导出自 @xihan-ui/headless，取值随元素说明。

AggregateFunction

表格汇总函数。

取值见常量 AGGREGATE_FUNCTIONS：

取值	中文名
sum	求和
avg	平均
count	计数
min	最小
max	最大

AggregateScope

表格汇总范围：page 本页数据，cumulative 截至本页的累计数据，all 全部数据。

取值见常量 AGGREGATE_SCOPES：

取值	中文名
page	本页
cumulative	累计到本页
all	全部

TableFooterPlacement

表尾行出现位置：everyPage 表格所跨的每一页，lastPage 仅表格结束的那一页。

取值见常量 TABLE_FOOTER_PLACEMENTS：

取值	中文名
everyPage	每一页
lastPage	只在最后一页

TableRowHeightMode

表体行高模式：fixed 每行固定为设定的行高，minimum 以设定的行高为下限、按单元格内容撑高。

取值见常量 TABLE_ROW_HEIGHT_MODES：

取值	中文名
fixed	固定
minimum	至少

TableCellType

表格列单元格的呈现类型。

取值见常量 TABLE_CELL_TYPES：

取值	中文名
text	文字
image	图片
barCode	条码
matrixCode	二维码

SingleSheetPreference

同一输出页既是首页又是末页时优先采用的变体。

取值见常量 SINGLE_SHEET_PREFERENCES：

取值	中文名
first	首页
last	末页