预览与打印

@xihan-print/runtime 的公开接口：预览元素、直接打印的函数与相关类型。样式在 @xihan-print/runtime/style.css。

<xh-print-preview>

注册 <xh-print-preview>；同一构造器重复注册不报错，没有 customElements 的环境跳过。

属性

属性	attribute	类型	说明
schema	—	PrintDocument | undefined	打印模板。
data	—	unknown	绑定的数据。
expressionEngine	—	ExpressionEngine | undefined	受限表达式引擎；缺省为 @xihan-ui/expression 的 createExpressionEngine()。
formatter	—	ValueFormatter | undefined	值格式化器；缺省为 @xihan-ui/expression 的 formatValue。
measurer	—	TextMeasurer | undefined	文字度量器；缺省用所在文档的 Canvas 度量器，字体加载完成后自动重排。
translations	—	Partial<PrintPreviewTranslations> | undefined	元素自己的文案，压在全局配置之上。
locale	locale	string | undefined	交给格式化器的区域。
timeZone	time-zone	string | undefined	交给格式化器的时区。
zoom	zoom	number | undefined	显示缩放倍数，缺省 1；写在宿主的 --xh-print-zoom 上，由 style.css 作用到输出页，只影响预览、不影响打印。
printClient	—	PrintClient | undefined	本地打印客户端（@xihan-print/runtime/client 的 createPrintClient）：给了时 print() 先交给它静默打印，连不上客户端才退回浏览器打印。
trace	—	PrintTrace | undefined	分页与打印各环节的回调，给调试日志用：重新分页时报分页的每一步与分页、生成 DOM 两个环节，print() 另报后面的环节。换它不重新分页。

存取器

属性	读写	类型	说明
extensions	可读写	readonly PrintRuntimeExtension[] | undefined	扩展：元素种类、渲染、编辑方式与规则，内置扩展自动排在最前。赋值时当场合并查重，冲突抛 DesignerExtensionError、什么都不变；同一个数组只合并一次，宿主要保持引用稳定。
result	只读	PaginationResult | undefined	最近一次分页的结果；还没分页或分页失败时为 undefined。

方法

方法	说明
paginate(): PaginationResult | undefined	立即按当前属性重新分页并渲染，返回分页结果；没有模板或分页失败时返回 undefined，失败另派发 pagination-error。
print(options?: PrintPreviewPrintOptions): Promise<PrintOutcome>	打印当前模板：按当前属性重新分页后送去打印，只在预览中显示的元素不打印。没有模板或分页失败时抛错。给了 printClient 时先交给本地打印客户端，等到交给打印池；只在连不上客户端时退回浏览器打印，其它错误照常抛出。

事件

事件都是冒泡的 CustomEvent。

事件	detail	说明
paginated	{ readonly sheets: number, readonly diagnostics: readonly PaginationDiagnostic[] }	分页并渲染完成。
pagination-error	PaginationErrorDetail	分页失败，已清空预览。

函数

printDocument()

declare function printDocument(schema: PrintDocument, data: unknown, options?: PrintOptions): Promise<PrintOutcome>

按数据排出模板并直接打印，不需要页面上有预览元素；分页同 paginateDocument。文档不合法或拿不到度量器时抛错，不打开打印对话框。

printSheets()

declare function printSheets(result: PaginationResult, options?: PrintSheetsOptions): Promise<void>

把排好的输出页送去打印：在隐藏 iframe 里渲染（只在预览中显示的元素不画），纸张尺寸不同的输出页分到各自的具名 @page，带上源文档的字体，等样式表、图片与字体就绪后调起打印对话框，对话框关闭后移除 iframe。

definePrintPreview()

declare function definePrintPreview(): void

注册 <xh-print-preview>；同一构造器重复注册不报错，没有 customElements 的环境跳过。

renderSheets()

declare function renderSheets(result: PaginationResult, container: Element, options?: RenderSheetsOptions): HTMLDivElement[]

把分页结果渲染进 container：先清空 container，再按顺序放入每张输出页，返回这些输出页元素。输出页按纸张尺寸定宽高，元素按毫米绝对定位；只用标准 HTML 与 SVG，任何文档里都能渲染，不依赖自定义元素注册。

类型

PrintRenderOptions

分页用到的注入项：预览元素的属性与 printDocument 的选项共用这一组。

属性	类型	说明
measurer?	TextMeasurer	文字度量器；缺省用所在文档的 Canvas 度量器（@xihan-ui/viz 的 createCanvasMeasurer），拿不到 2D 上下文时报 measurer.unavailable。
expressionEngine?	ExpressionEngine	受限表达式引擎；缺省为 @xihan-ui/expression 的 createExpressionEngine()。
formatter?	ValueFormatter	值格式化器；缺省为 @xihan-ui/expression 的 formatValue。
locale?	string	交给格式化器的区域。
timeZone?	string	交给格式化器的时区：UTC、±HH:mm 或 IANA 名称。
maxSheets?	number	输出页总数上限，缺省同 @xihan-print/core 的 paginate。
extensions?	readonly PrintRuntimeExtension[]	扩展：元素种类、渲染、编辑方式与规则，内置扩展自动排在最前。
trace?	PrintTrace	分页与打印各环节的回调，给调试日志用，见 PrintTrace。

PrintOptions

printDocument 的选项：分页注入项加上打印选项。

继承 PaginateDocumentOptions、PrintSheetsOptions。

PrintSheetsOptions

printSheets 的选项。

属性	类型	说明
document?	Document	发起打印的文档，缺省为全局 document；隐藏 iframe 挂在它的 body 上。
title?	string	打印文档的标题，即打印对话框与另存 PDF 时的缺省文件名；缺省沿用发起打印的文档标题。
extensions?	readonly PrintRuntimeExtension[]	扩展：扩展元素按它们给的渲染画出，与分页用同一份。
trace?	PrintTrace	打印各环节的回调：报生成 DOM、等资源与送打印三个环节的起止，见 PrintTrace。

PrintOutcome

一次打印的结果：送去打印的输出页数与分页诊断。

属性	类型	说明
sheets	number
diagnostics	readonly PaginationDiagnostic[]
via?	'client' | 'browser'	送去打印的途径：client 为本地打印客户端，browser 为浏览器的打印对话框。

PrintPreviewPrintOptions

print() 的选项：浏览器打印时的标题，以及交给本地打印客户端的打印选项。

继承 Pick<PrintSheetsOptions, 'title'>、ClientPrintOptions。

PaginationErrorDetail

分页失败的原因：core 的 PrintLayoutError 或运行时的 PrintRuntimeError。

属性	类型	说明
code	PrintLayoutErrorCode | PrintRuntimeErrorCode
params	IssueParams
issues	readonly ValidationIssue[]	文档不合法时的校验问题。

PrintPreviewTranslations

预览元素的文案。

属性	类型	说明
label	string	预览区域的可访问名。

方法	说明
sheetLabel(position: number, count: number): string	一张输出页的可访问名；position 从 1 开始，count 为输出页总数。

全部导出

designer-locale

名称	种类	说明
DEFAULT_PRINT_DESIGNER_TRANSLATIONS	常量	设计器的内建英文文案，与 printEnUS 里设计器的那份相同。

extensions

名称	种类	说明
createPrintRuntimeModel	函数	合出运行时用的打印模型；同一元素类型在两个扩展里都给了渲染时抛 DesignerExtensionError。
PrintElementRenderContext	接口	渲染扩展元素时拿到的上下文。
PrintElementRenderer	类型	扩展元素的渲染：按布局盒建出画在元素框里的节点，元素框的位置、尺寸与只预览标记由运行时摆好。
PrintRuntimeExtension	接口	打印运行时层的扩展：core 层的全部字段，加上扩展元素的渲染。
PrintRuntimeModel	接口	运行时用的打印模型：core 的模型加上各元素类型的渲染。

merge

名称	种类	说明
MergedPaginationDiagnostic	类型	合并结果里的一条诊断：原样带着，另记它来自第几份结果。
MergedPaginationPart	接口	一份结果在合并结果里占的输出页。
MergedPaginationResult	接口	合并后的分页结果。
mergePaginationResults	函数	按顺序把几份分页结果接成一份。

options

名称	种类	说明
PrintPhase	类型	打印的环节：paginate 分页，render 把输出页画成 DOM，resources 等图片与字体就绪（交给本地客户端时是把它们取来随任务带去），document 把输出页、资源与样式合成交给本地客户端的一份文档，print 交给浏览器的打印对话框。
PrintRenderOptions	接口	分页用到的注入项：预览元素的属性与 printDocument 的选项共用这一组。
PrintRuntimeError	类	运行时无法完成分页或打印时抛出的错误，code 与 params 供调用方判断与生成文案。
PrintRuntimeErrorCode	类型	运行时无法完成分页或打印的原因：拿不到文字度量器、没有给模板。
PrintTrace	接口	分页与打印各环节的回调，给调试日志用；不给就不报，结果照旧。

print

名称	种类	说明
paginateDocument	函数	按数据排出模板，返回分页结果，不打印；缺省注入项与 printDocument 相同：度量器用 options.document（缺省全局 document）里的 Canvas 度量器，表达式引擎与格式化器同预览元素。
PaginateDocumentOptions	接口	paginateDocument 的选项：分页注入项，外加缺省度量器所在的文档。
printDocument	函数	按数据排出模板并直接打印，不需要页面上有预览元素；分页同 paginateDocument。
PrintOptions	接口	printDocument 的选项：分页注入项加上打印选项。
PrintOutcome	接口	一次打印的结果：送去打印的输出页数与分页诊断。
printSheets	函数	把排好的输出页送去打印：在隐藏 iframe 里渲染（只在预览中显示的元素不画），纸张尺寸不同的输出页分到各自的具名 @page，带上源文档的字体，等样式表、图片与字体就绪后调起打印对话框，对话框关闭后移除 iframe。
PrintSheetsOptions	接口	printSheets 的选项。

print-preview

名称	种类	说明
definePrintPreview	函数	注册 <xh-print-preview>；同一构造器重复注册不报错，没有 customElements 的环境跳过。
PaginationErrorDetail	接口	分页失败的原因：core 的 PrintLayoutError 或运行时的 PrintRuntimeError。
PRINT_PREVIEW_TAG	常量	预览元素的标签名。
PrintPreviewEventMap	接口	预览元素派发的事件。
PrintPreviewPrintOptions	接口	print() 的选项：浏览器打印时的标题，以及交给本地打印客户端的打印选项。
XhPrintPreview	类

render/boxes

名称	种类	说明
renderBox	函数	按布局盒的种类渲染一个元素；扩展元素按 renderers 里同一类型的渲染。

render/sheets

名称	种类	说明
renderSheets	函数	把分页结果渲染进 container：先清空 container，再按顺序放入每张输出页，返回这些输出页元素。
RenderSheetsOptions	接口	renderSheets 的选项。
sheetPageName	函数	纸张尺寸对应的 CSS 具名页面，尺寸相同的输出页共用一个名字。

render/watermark

名称	种类	说明
renderWatermark	函数	按模板的水印生成覆盖整张输出页的一层；没有可印的文字时返回 undefined。

translations

名称	种类	说明
PrintDesignerTranslations	接口	设计器的文案。
PrintHistoryTranslations	接口	撤销历史里一步的说明：单个元素写「种类 名称」（见 elementLabel），几个元素写个数。
PrintPreviewTranslations	接口	预览元素的文案。
PrintTablePartKind	类型	表格编辑态里可以选中的部位。
PrintTourStepKey	类型	新手引导里打印自己那几步的键。
PrintTourStepTranslations	接口	新手引导一步的标题与说明。

@xihan-print/runtime/locale 的导出

locale

名称	种类	说明
printDeDE	常量	打印的德语文案：预览、设计器与 designer-shell 零件。
printEnUS	常量	打印的英文文案：预览、设计器与 designer-shell 零件。
printEsES	常量	打印的西班牙语文案：预览、设计器与 designer-shell 零件。
printFrFR	常量	打印的法语文案：预览、设计器与 designer-shell 零件。
printJaJP	常量	打印的日语文案：预览、设计器与 designer-shell 零件。
printKoKR	常量	打印的韩语文案：预览、设计器与 designer-shell 零件。
printPtBR	常量	打印的巴西葡萄牙语文案：预览、设计器与 designer-shell 零件。
printRuRU	常量	打印的俄语文案：预览、设计器与 designer-shell 零件。
printZhCN	常量	打印的简体中文文案：预览、设计器与 designer-shell 零件。
printZhTW	常量	打印的繁体中文文案：预览、设计器与 designer-shell 零件。