来源：https://print.docs.xihanfun.com/reference/runtime

# 预览与打印

<!-- 本页由 docs/scripts/gen-reference.mjs 从源码生成，不要手改；源码变了之后在 docs/ 运行 pnpm gen。 -->

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

## `<xh-print-preview>`

注册 &lt;xh-print-preview&gt;；同一构造器重复注册不报错，没有 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() {#printdocument}

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

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

### printSheets() {#printsheets}

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

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

### definePrintPreview() {#defineprintpreview}

```ts
declare function definePrintPreview(): void
```

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

### renderSheets() {#rendersheets}

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

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

## 类型

### PrintRenderOptions {#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 {#printoptions}

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

继承 `PaginateDocumentOptions`、`PrintSheetsOptions`。

### PrintSheetsOptions {#printsheetsoptions}

printSheets 的选项。

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

### PrintOutcome {#printoutcome}

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

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

### PrintPreviewPrintOptions {#printpreviewprintoptions}

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

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

### PaginationErrorDetail {#paginationerrordetail}

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

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

### PrintPreviewTranslations {#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` | 函数 | 注册 &lt;xh-print-preview&gt;；同一构造器重复注册不报错，没有 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 零件。 |