# 曦寒打印设计器 · 参考

共 7 页。索引见 https://print.docs.xihanfun.com/llms.txt

---

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

# 打印客户端 SDK

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

`@xihan-print/runtime/client` 连接本地打印客户端：静默打印、写原始指令、导出 PDF、查打印机。这个子入口单独打包，不用客户端的页面不会加载它。

## 创建连接

### createPrintClient() {#createprintclient}

```ts
declare function createPrintClient(options?: PrintClientOptions): PrintClient
```

创建本地打印客户端的连接；不会立即连接，第一次调用时才连。

### PrintClientOptions {#printclientoptions}

createPrintClient 的选项。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `ports?` | `readonly number[]` | 按顺序探测的端口，缺省 17620–17623。 |
| `timeoutMs?` | `number` | 请求等响应的期限，缺省 10 秒。 |
| `connectTimeoutMs?` | `number` | 每个端口建连的期限，缺省 3 秒。 |
| `consentTimeoutMs?` | `number` | 客户端弹出授权窗口后等用户决定的期限，缺省 75 秒。 |
| `reconnect?` | `boolean` | 断线后是否自动重连，缺省 true。 |
| `WebSocket?` | `WebSocketConstructor` | WebSocket 构造函数，缺省为全局 WebSocket。 |
| `permissions?` | `PermissionsLike \| null` | 查本机网络权限的入口，缺省为 navigator.permissions；为 null 时不查。 |
| `secureContext?` | `boolean` | 页面是否是安全上下文，缺省为全局 isSecureContext。 |
| `origin?` | `string` | 页面的来源，缺省为全局 location.origin；页面本身在本机回环地址上时，连不上不按本机网络权限判定。 |
| `fetch?` | `typeof fetch` | 打包文档时取资源用的 fetch，缺省为全局 fetch。 |

### PrintClient {#printclient}

本地打印客户端的连接。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `state` | `PrintClientState` | 连接状态。 |
| `welcome` | `ClientWelcome \| undefined` | 最近一次握手的结果；还没连上过时为 undefined。 |

| 方法 | 说明 |
| --- | --- |
| `connect(): Promise<ClientWelcome>` | 连接并握手；已连着时直接返回握手结果。连不上抛 PrintClientError，码为 CLIENT_UNAVAILABLE、LOCAL_NETWORK_DENIED、PROTOCOL_UNSUPPORTED、CONSENT_DENIED、CONSENT_TIMEOUT 等。 |
| `close(): void` | 断开连接，不再重连；未结束的任务以 CONNECTION_LOST 拒绝，客户端里的任务照常执行完。 |
| `printers(): Promise<PrinterInfo[]>` | 列出打印机，不含能力明细。 |
| `printer(name: string): Promise<PrinterInfo>` | 查一台打印机，含能力明细。 |
| `printDocument(schema: PrintDocument, data: unknown, options?: PrintClientDocumentOptions): PrintClientJob` | 按数据排出模板并交给客户端打印。 |
| `printSheets(result: PaginationResult, options?: PrintClientDocumentOptions): PrintClientJob` | 把排好的输出页交给客户端打印。 |
| `printRaw(printer: string, data: Uint8Array \| ArrayBuffer \| string, options?: PrintRawOptions): PrintClientJob` | 把原始指令原样写给打印机；字符串按 UTF-8 编码，要别的编码时先转成字节。 |
| `exportPdf(schema: PrintDocument, data: unknown, options?: PrintClientDocumentOptions): Promise<Blob>` | 按数据排出模板并导出为 PDF。 |
| `exportSheetsPdf(result: PaginationResult, options?: PrintClientDocumentOptions): Promise<Blob>` | 把排好的输出页导出为 PDF。 |
| `job(jobId: string): Promise<JobStatus>` | 查任务状态。 |
| `on<K extends keyof PrintClientEventMap>(type: K, listener: (detail: PrintClientEventMap[K]) => void): () => void` | 订阅事件，返回退订函数。 |

### PrintClientJob {#printclientjob}

一个交给客户端的任务。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `string` | 任务标识，由 SDK 生成。 |
| `status` | `JobStatus \| undefined` | 最近一次的状态；还没交给客户端时为 undefined。 |
| `done` | `Promise<JobStatus>` | completed 时兑现；failed 时以客户端给出的错误码拒绝，cancelled 时以 JOB_CANCELLED 拒绝，发送前出错时以对应错误拒绝。 |

| 方法 | 说明 |
| --- | --- |
| `onStatus(listener: (status: JobStatus) => void): () => void` | 订阅状态变化，返回退订函数。 |
| `cancel(): Promise<boolean>` | 取消任务：排队中的立即取消并返回 true；执行中的尽力取消并返回 false，结果以状态为准。 |

### PrintClientEventMap {#printclienteventmap}

客户端派发的事件。

用 `client.on(type, listener)` 订阅。连接状态 `PrintClientState` 取 `idle`、`connecting`、`open`、`reconnecting`、`closed`。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `state` | `PrintClientState` | 连接状态变化。 |
| `consentpending` | `{ readonly origin: string }` | 来源还没授权，客户端已弹出授权窗口。 |

## 退回浏览器打印

### printWithFallback() {#printwithfallback}

```ts
declare function printWithFallback(client: PrintClient, schema: PrintDocument, data: unknown, options?: PrintWithFallbackOptions): Promise<PrintWithFallbackOutcome>
```

先交给本地打印客户端打印，等到交给打印池；只在连不上客户端（CLIENT_UNAVAILABLE、PROTOCOL_UNSUPPORTED）时退回浏览器的打印对话框。打印机报错、拒绝授权等其它错误照常抛出，免得用户以为已经静默打出来了。

### PrintWithFallbackOptions {#printwithfallbackoptions}

printWithFallback 的选项：客户端打印选项、分页注入项，退回浏览器打印时另用 title。

继承 `PrintClientDocumentOptions`、`Pick<PrintOptions, 'title'>`。

### PrintWithFallbackOutcome {#printwithfallbackoutcome}

printWithFallback 的结果：走了哪条路，与送去打印的页数。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `via` | `'client' \| 'browser'` |  |
| `sheets` | `number` |  |

### shouldFallBack() {#shouldfallback}

```ts
declare function shouldFallBack(error: unknown): boolean
```

这个错误是否表示连不上客户端、应该退回浏览器打印；打印机报错、拒绝授权等一律不退回。

## 错误码

出错时抛出或以 `PrintClientError` 拒绝，`code` 为下表之一，`details` 带补充信息。「SDK」一栏的码在浏览器里产生，其余由客户端给出。

| 错误码 | 出自 | 说明 | 退回浏览器打印 |
| --- | --- | --- | --- |
| `CLIENT_UNAVAILABLE` | SDK | 所有端口都连不上（客户端没装或没运行），details 带端口 ports 与浏览器报的「本机应用」权限状态 permission（查不到时不带） | 是 |
| `LOCAL_NETWORK_DENIED` | SDK | 连接在浏览器里就被拦下：页面不在本机回环地址上、所有端口都在建连期限内失败，且「本机应用」权限被拒或页面不是安全上下文 | 否 |
| `CONNECTION_LOST` | SDK | 等结果时断线，或断线后没能在期限内重连上 | 否 |
| `TOO_MANY_CONNECTIONS` | SDK | 同一来源的连接数超过客户端上限 | 否 |
| `TIMEOUT` | SDK | 请求没有在期限内得到响应 | 否 |
| `JOB_CANCELLED` | SDK | 任务被取消 | 否 |
| `BAD_REQUEST` | 客户端 | 消息格式或字段不合法 | 否 |
| `CONSENT_PENDING` | 客户端 | 授权窗口还开着时又发了业务请求 | 否 |
| `CONSENT_DENIED` | 客户端 | 用户拒绝，或来源在拒绝名单 | 否 |
| `CONSENT_TIMEOUT` | 客户端 | 授权窗口在期限内没人处理 | 否 |
| `SESSION_EXPIRED` | 客户端 | 重连令牌过期或不属于这个来源，已当作新会话 | 否 |
| `PROTOCOL_UNSUPPORTED` | 客户端 | 协议主版本不匹配 | 是 |
| `NO_PRINTERS` | 客户端 | 本机没有任何打印机 | 否 |
| `PRINTER_NOT_FOUND` | 客户端 | 指定的打印机不存在 | 否 |
| `PRINTER_OFFLINE` | 客户端 | 打印机脱机、暂停或出错 | 否 |
| `PAPER_UNSUPPORTED` | 客户端 | 打印机没有任务需要的纸张，且驱动不接受自定义尺寸 | 否 |
| `DOCUMENT_TOO_LARGE` | 客户端 | 超过消息上限或资源总量上限 | 否 |
| `RESOURCE_BLOCKED` | 客户端 | 文档里引用了随任务带来的资源之外的地址 | 否 |
| `RENDER_FAILED` | 客户端 | 渲染引擎载入或等待就绪失败 | 否 |
| `RENDER_TIMEOUT` | 客户端 | 渲染超时 | 否 |
| `SPOOL_FAILED` | 客户端 | 交给打印池失败 | 否 |
| `PDF_FAILED` | 客户端 | 导出 PDF 失败 | 否 |
| `JOB_DUPLICATE` | 客户端 | 任务标识重复 | 否 |
| `JOB_NOT_FOUND` | 客户端 | 查无此任务 | 否 |
| `QUEUE_FULL` | 客户端 | 同一会话排队的任务超过上限 | 否 |
| `CAPABILITY_UNSUPPORTED` | 客户端 | 请求了客户端没有的能力 | 否 |
| `INTERNAL` | 客户端 | 未预期的异常 | 否 |

## 提醒码

HTML 通道的任务照常完成、但有宿主应当知道的情况时，`JobStatus` 的 `warnings` 里带若干条提醒（`ClientWarningPayload`），`code` 为下表之一，`details` 带补充信息。

| 提醒码 | 说明 |
| --- | --- |
| `PAPER_UNCHECKED` | 驱动没有报纸张能力，或读不出驱动会留下哪种纸，没有核对纸张就照常下发了 |
| `PAPER_FITTED` | 按 fitToNearestPaper 把某组改用了最接近的纸张：比纸大的内容按 scale 等比缩小，比纸小的原大居中 |

## 打印选项与结果

### ClientPrintOptions {#clientprintoptions}

交给客户端的打印选项。纸张不在选项里：每组输出页按模板里的纸张尺寸下发；原始指令的纸张由指令自己决定。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `printer?` | `string` | 打印机名称，缺省为默认打印机。 |
| `copies?` | `number` | 份数，1–999。 |
| `collate?` | `boolean` | 多份时逐份打印，缺省 true。 |
| `duplex?` | `'simplex' \| 'long-edge' \| 'short-edge'` |  |
| `color?` | `'color' \| 'grayscale'` |  |
| `pageRanges?` | `string` | 页码范围，如 1-3,5。 |
| `dialog?` | `boolean` | 弹系统打印对话框，缺省静默打印。 |
| `timeoutMs?` | `number` | 交给打印池的期限，毫秒。 |
| `fitToNearestPaper?` | `boolean` | 打印机没有某组的纸张、驱动也不接受这个尺寸时，改用最接近的纸张，比纸大的内容等比缩小到放得下，比纸小的原大居中；缺省 false，这时整个任务以 PAPER_UNSUPPORTED 失败。 |

### PrintClientDocumentOptions {#printclientdocumentoptions}

打印与导出的选项：客户端打印选项、分页注入项与打包文档的选项。

继承 `ClientPrintOptions`、`PrintRenderOptions`、`Pick<ClientDocumentOptions, 'document'>`。

### PrintRawOptions {#printrawoptions}

写原始指令的选项。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `docName?` | `string` | 打印池里显示的文档名，缺省为任务标识。 |

### JobStatus {#jobstatus}

任务的当前状态。

任务状态 `JobState` 取 `queued`、`started`、`completed`、`failed`、`cancelled`。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `jobId` | `string` |  |
| `state` | `JobState` |  |
| `position?` | `number` | 排队时同一台打印机前面还有几个任务。 |
| `sheets?` | `number` | HTML 通道交给打印池的页数。 |
| `bytes?` | `number` | 原始通道写出的字节数，或导出的 PDF 大小。 |
| `error?` | `ClientErrorPayload` |  |
| `warnings?` | `readonly ClientWarningPayload[]` | HTML 通道完成时的提醒，如没能核对纸张、按 fitToNearestPaper 换了纸；没有时缺省。 |

## 打印机与客户端信息

### PrinterInfo {#printerinfo}

一台打印机。

打印机状态 `PrinterState` 取 `ready`、`paused`、`offline`、`error`、`paperOut`、`paperJam`、`busy`、`unknown`。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `string` |  |
| `isDefault` | `boolean` |  |
| `status` | `PrinterState` |  |
| `statusFlags` | `number` | 系统给出的原始状态位。 |
| `location?` | `string` |  |
| `comment?` | `string` |  |
| `driver?` | `string` |  |
| `port?` | `string` |  |
| `isNetwork` | `boolean` |  |
| `capabilities?` | `PrinterCapabilities` |  |

### PrinterCapabilities {#printercapabilities}

打印机能力，只在查单台打印机时给出。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `color` | `boolean` |  |
| `duplex` | `boolean` |  |
| `maxCopies` | `number` |  |
| `papers` | `readonly PaperInfo[]` |  |

### PaperInfo {#paperinfo}

打印机支持的一种纸张。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `number` |  |
| `name` | `string` |  |
| `widthMm` | `number` |  |
| `heightMm` | `number` |  |

### ClientWelcome {#clientwelcome}

握手成功后客户端的回复。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `protocol` | `number` |  |
| `minor` | `number` |  |
| `client` | `ClientInfo` |  |
| `capabilities` | `ClientCapabilities` |  |
| `resumed` | `readonly string[]` | 重连认回会话时仍未结束的任务。 |

### ClientInfo {#clientinfo}

客户端信息。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `version` | `string` |  |
| `os` | `string` |  |
| `arch` | `string` |  |
| `renderer?` | `string` | 渲染引擎版本；没有渲染引擎时缺省。 |

### ClientCapabilities {#clientcapabilities}

客户端能力。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `html` | `boolean` |  |
| `raw` | `boolean` |  |
| `pdf` | `boolean` |  |
| `duplex` | `boolean` |  |
| `printerStatus` | `boolean` |  |

## 交给客户端的文档

### buildClientDocument() {#buildclientdocument}

```ts
declare function buildClientDocument(result: PaginationResult, options?: ClientDocumentOptions): Promise<ClientDocument>
```

把分页结果打包成交给客户端的文档：输出页渲染进一份独立的 HTML（只在预览中显示的元素不画），图片、背景图与模板用到的字体取来随任务带去，地址改写成客户端里的资源地址。

### ClientDocumentOptions {#clientdocumentoptions}

打包文档的选项。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `document?` | `Document` | 发起打印的文档：从它的样式表里找模板用到的字体，相对地址也按它解析；缺省为全局 document。 |
| `fetch?` | `typeof fetch` | 取资源用的 fetch，缺省为全局 fetch。 |
| `extensions?` | `readonly PrintRuntimeExtension[]` | 扩展：扩展元素按它们给的渲染画出，与分页用同一份。 |
| `trace?` | `PrintTrace` | 各环节的回调：报生成 DOM、取资源与合成文档三个环节的起止，见 PrintTrace。 |

### ClientDocument {#clientdocument}

交给客户端的文档：自包含的输出页、资源与按出现顺序的纸张分组。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `html` | `string` |  |
| `resources` | `readonly ClientResource[]` |  |
| `sheets` | `readonly ClientSheetGroup[]` |  |

### ClientResource {#clientresource}

随任务带去的一份资源，data 为 base64。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `string` |  |
| `type` | `string` |  |
| `data` | `string` |  |

### ClientSheetGroup {#clientsheetgroup}

连续的若干张同尺寸输出页。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `widthMm` | `number` |  |
| `heightMm` | `number` |  |
| `count` | `number` |  |

## 常量

| 名称 | 值 | 说明 |
| --- | --- | --- |
| `DEFAULT_PORTS` | `[17620, 17621, 17622, 17623]` | 客户端监听的端口，按顺序探测。 |
| `SUB_PROTOCOL` | `'xihan-print.v1'` | 带主版本的子协议。 |
| `PROTOCOL_VERSION` | `1` | 协议主版本。 |
| `PROTOCOL_MINOR` | `0` | 协议次版本：只加不减。 |

## 全部导出

### client/client

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `createPrintClient` | 函数 | 创建本地打印客户端的连接；不会立即连接，第一次调用时才连。 |
| `PermissionsLike` | 接口 | 查浏览器权限的入口，形同 navigator.permissions。 |
| `PrintClient` | 接口 | 本地打印客户端的连接。 |
| `PrintClientDocumentOptions` | 接口 | 打印与导出的选项：客户端打印选项、分页注入项与打包文档的选项。 |
| `PrintClientEventMap` | 接口 | 客户端派发的事件。 |
| `PrintClientJob` | 接口 | 一个交给客户端的任务。 |
| `PrintClientOptions` | 接口 | createPrintClient 的选项。 |
| `PrintClientState` | 类型 | 连接状态。 |
| `PrintRawOptions` | 接口 | 写原始指令的选项。 |
| `WebSocketConstructor` | 类型 | 能当 WebSocket 用的构造函数，单测可注入假实现。 |

### client/document

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `buildClientDocument` | 函数 | 把分页结果打包成交给客户端的文档：输出页渲染进一份独立的 HTML（只在预览中显示的元素不画），图片、背景图与模板用到的字体取来随任务带去，地址改写成客户端里的资源地址。 |
| `ClientDocumentOptions` | 接口 | 打包文档的选项。 |

### client/errors

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `FALLBACK_CODES` | 常量 | 连不上客户端、可以退回浏览器打印的错误码：客户端没装或没运行，或协议主版本不对。 |
| `PrintClientError` | 类 | 打印客户端相关的错误，`code` 与 `details` 供调用方判断与生成文案。 |
| `shouldFallBack` | 函数 | 这个错误是否表示连不上客户端、应该退回浏览器打印；打印机报错、拒绝授权等一律不退回。 |

### client/fallback

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `printWithFallback` | 函数 | 先交给本地打印客户端打印，等到交给打印池；只在连不上客户端（CLIENT_UNAVAILABLE、PROTOCOL_UNSUPPORTED）时退回浏览器的打印对话框。 |
| `PrintWithFallbackOptions` | 接口 | printWithFallback 的选项：客户端打印选项、分页注入项，退回浏览器打印时另用 title。 |
| `PrintWithFallbackOutcome` | 接口 | printWithFallback 的结果：走了哪条路，与送去打印的页数。 |

### client/protocol

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `ClientCapabilities` | 接口 | 客户端能力。 |
| `ClientDocument` | 接口 | 交给客户端的文档：自包含的输出页、资源与按出现顺序的纸张分组。 |
| `ClientErrorCode` | 类型 | 客户端给出的错误码。 |
| `ClientErrorPayload` | 接口 | 响应与任务事件里的错误。 |
| `ClientInfo` | 接口 | 客户端信息。 |
| `ClientPrintOptions` | 接口 | 交给客户端的打印选项。 |
| `ClientResource` | 接口 | 随任务带去的一份资源，data 为 base64。 |
| `ClientSheetGroup` | 接口 | 连续的若干张同尺寸输出页。 |
| `ClientWarningCode` | 类型 | 客户端在完成的任务里给出的提醒码。 |
| `ClientWarningPayload` | 接口 | 任务照常完成、但宿主应当知道的情况，code 取 ClientWarningCode。 |
| `ClientWelcome` | 接口 | 握手成功后客户端的回复。 |
| `DEFAULT_PORTS` | 常量 | 客户端监听的端口，按顺序探测。 |
| `JobState` | 类型 | 任务状态。 |
| `JobStatus` | 接口 | 任务的当前状态。 |
| `PaperInfo` | 接口 | 打印机支持的一种纸张。 |
| `PrintClientErrorCode` | 类型 | 打印客户端相关的全部错误码。 |
| `PrinterCapabilities` | 接口 | 打印机能力，只在查单台打印机时给出。 |
| `PrinterInfo` | 接口 | 一台打印机。 |
| `PrinterState` | 类型 | 打印机状态。 |
| `PROTOCOL_MINOR` | 常量 | 协议次版本：只加不减。 |
| `PROTOCOL_VERSION` | 常量 | 协议主版本。 |
| `SdkErrorCode` | 类型 | SDK 自己给出的错误码： |
| `SUB_PROTOCOL` | 常量 | 带主版本的子协议。 |

---

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

# 模型层 core

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

`@xihan-print/core` 是纯 TypeScript 的模型层：模板类型、校验、编辑操作、元素登记表与分页算法，不依赖 DOM，浏览器、Node.js 与其它 JavaScript 运行环境里都能用。模板类型的字段见[模板类型](./schema)，元素属性见[元素](./elements)。下表按源码模块列出全部导出。

## 全部导出

### extensions

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `createPrintModel` | 函数 | 合出打印模型：内置扩展 PRINT_CORE_EXTENSION 在前，extensions 按顺序在后。 |
| `PRINT_CORE_EXTENSION` | 常量 | 内置扩展：全部内置元素。 |
| `PRINT_CORE_EXTENSION_ID` | 常量 | 内置扩展的 id。 |
| `PRINT_EXTENSION_SPACES` | 常量 | 打印各层扩展共用的名字空间：元素类型。 |
| `PrintCoreExtension` | 接口 | 打印 core 层的扩展：元素原型、编辑方式与校验规则。 |
| `PrintModel` | 接口 | 一组扩展合出的打印模型：元素登记表与编辑方式。 |
| `PrintRuleContext` | 接口 | 规则拿到的上下文：合并后的元素登记表。 |

### factory

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `collectDocumentIds` | 函数 | 收集文档中已使用的页面与元素标识。 |
| `createDocument` | 函数 | 生成当前 schema 版本的文档。 |
| `CreateDocumentOptions` | 接口 | 文档创建选项。 |
| `createEdges` | 函数 | 生成四边相等或逐边指定的边距。 |
| `createPage` | 函数 | 生成页面模板：页眉单页时优先首页变体，页脚单页时优先末页变体，页码接续上一页面模板。 |
| `createPageBandSet` | 函数 | 生成只含空 default 带区的页眉或页脚。 |
| `CreatePageOptions` | 接口 | 页面模板创建选项。 |
| `createPaper` | 函数 | 按预设名生成纸张。 |

### fields

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `collectDocumentFields` | 函数 | 列出一份模板引用了哪些数据字段，合成去重的字段树，形状同设计器的 fields。 |
| `CollectDocumentFieldsOptions` | 接口 | collectDocumentFields 的选项。 |

### geometry

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `getBandRect` | 函数 | 取页眉或页脚带区在纸张上的矩形。 |
| `getBodyRect` | 函数 | 取给定页眉、页脚带区之间的正文区。 |
| `getContentRect` | 函数 | 取页边距以内的内容区。 |
| `getElementRect` | 函数 | 取元素框。 |
| `getPageBand` | 函数 | 取页眉或页脚中指定键的带区。 |
| `getPaperSize` | 函数 | 取页面按方向换算后的纸张尺寸。 |
| `resolvePageBand` | 函数 | 按输出页位置选出页眉或页脚应使用的带区。 |
| `resolvePageBandKey` | 函数 | 按输出页位置选出页眉或页脚应使用的带区键。 |
| `SheetPosition` | 接口 | 输出页在所属页面模板中的位置。 |

### layout/boxes

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `MIN_SHRINK_FONT_SIZE` | 常量 | 缩小字号以容纳文字时的最小字号，单位 pt。 |
| `SHRINK_FONT_STEP` | 常量 | 缩小字号的步长，单位 pt。 |

### layout/design

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `DESIGN_FILLER_ROWS` | 常量 | 设置了补空行的表格在设计态示意的空行数。 |
| `DESIGN_SAMPLE_ROWS` | 常量 | 表格缺省示意的数据行数。 |
| `DesignLayout` | 接口 | 设计态排版结果：各区的布局盒按元素层级排列，坐标为设计坐标。 |
| `DesignLayoutOptions` | 接口 | 设计态排版的选项：度量器、表达式引擎、格式化器、区域与时区同分页。 |
| `layoutDesign` | 函数 | 按设计坐标排出页面模板的每个元素，页眉页脚取 options.bands 指定的变体。 |

### layout/paginate

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `DEFAULT_MAX_SHEETS` | 常量 | 输出页总数上限的缺省值。 |
| `paginate` | 函数 | 按数据排出模板文档的全部输出页，返回每页每个元素的布局盒。 |

### layout/rich-text

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `RICH_TEXT_BLOCK_GAP` | 常量 | 顶层块与块之间的段距，基准字号的倍数；列表项之间与列表项里的块之间不留段距。 |
| `RICH_TEXT_DIVIDER_WIDTH` | 常量 | 分隔线的线宽，单位 mm。 |
| `RICH_TEXT_HEADING_SCALES` | 常量 | 一到三级标题的字号，基准字号的倍数。 |
| `RICH_TEXT_LIST_INDENT` | 常量 | 每层列表的缩进，基准字号的倍数。 |
| `RICH_TEXT_MARKER_GAP` | 常量 | 项目符号或序号与文字之间的间距，基准字号的倍数。 |
| `RICH_TEXT_SCRIPT_SCALE` | 常量 | 上标与下标的字号，所在文字字号的倍数。 |

### layout/text-measure

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `DEFAULT_FONT_FAMILY` | 常量 | 文字样式没写字体时，量字与渲染共用的字体族。 |

### layout/types

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `BarCodeLayoutBox` | 接口 | 一维条码布局盒。 |
| `EllipseLayoutBox` | 接口 | 椭圆布局盒。 |
| `ExtensionLayoutBox` | 接口 | 扩展元素的布局盒，交给运行时层同一类型的渲染；类型没登记时 data 为 null。 |
| `ImageLayoutBox` | 接口 | 图片布局盒。 |
| `LayoutBand` | 接口 | 输出页选中的页眉或页脚带区。 |
| `LayoutBox` | 类型 |  |
| `LayoutBoxBase` | 接口 | 布局盒共有的字段。 |
| `LayoutFragment` | 接口 | 跨页续排元素的分段位置。 |
| `LayoutSheet` | 接口 | 一张输出页。 |
| `LayoutWatermark` | 类型 | 已替换占位的水印。 |
| `LineLayoutBox` | 接口 | 直线布局盒。 |
| `MatrixCodeLayoutBox` | 接口 | 二维码布局盒。 |
| `PaginateOptions` | 接口 | 分页选项。 |
| `PAGINATION_DIAGNOSTIC_SEVERITIES` | 常量 | 全部分页诊断码及其固定的严重程度：error 为按模板该画的内容没有画出或输出页被截断，warning 为内容画出了但与设计有出入。 |
| `PaginationDiagnostic` | 类型 | 分页诊断：与校验问题同形的 @xihan-ui/designer-kit/schema 的 SchemaIssue，不含文案，严重程度与 target 总是给出。 |
| `PaginationDiagnosticCode` | 类型 | 分页诊断码。 |
| `PaginationDiagnosticTarget` | 接口 | 分页诊断所在的页面（kind 为 page）或元素（kind 为 element）。 |
| `PaginationResult` | 接口 | 分页结果。 |
| `PaginationStep` | 类型 | 分页的一步，按发生的先后交给 PaginateOptions.trace。 |
| `PrintLayoutError` | 类 | 分页无法进行时抛出的错误。 |
| `PrintLayoutErrorCode` | 类型 | 分页无法进行的原因：文档有 error 级校验问题、选项不合法、测量器或格式化器返回了不合法的结果。 |
| `RectLayoutBox` | 接口 | 矩形布局盒。 |
| `RichTextLayoutBox` | 接口 | 富文本布局盒，跨页时每页一段。 |
| `RichTextLine` | 接口 | 富文本排出的一行，长度单位 mm。 |
| `RichTextMarker` | 接口 | 列表项的项目符号或序号。 |
| `RichTextSpan` | 接口 | 富文本一行里同一样式的一截文字：字号与字间距单位 pt。 |
| `TableCellLayout` | 接口 | 表格单元格布局，坐标相对纸张左上角。 |
| `TableLayoutBox` | 接口 | 表格布局盒，跨页时每页一段。 |
| `TableRowLayout` | 接口 | 表格行布局：表头、数据行、补空行或表尾行。 |
| `TextLayoutBox` | 接口 | 文本、长文本与页码的布局盒。 |
| `TextMeasurement` | 接口 | 按文本样式排出的文字，长度单位 mm。 |

### operations/apply

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `applyOperation` | 函数 | 以纯函数方式执行编辑操作：不修改传入的文档，返回新文档与逆操作数组。 |
| `ApplyOperationOptions` | 接口 | 操作选项。 |
| `applyOperations` | 函数 | 按顺序执行一组编辑操作，整体成功或整体失败（@xihan-ui/designer-kit 的 applyInSequence）。 |

### operations/errors

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `PrintOperationError` | 类 | 操作无法执行时抛出的错误，`code` 与 `params` 供调用方判断与生成文案。 |
| `PrintOperationErrorCode` | 类型 | 操作无法执行的原因。 |

### operations/table-plans

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `MIN_TABLE_COLUMN_WIDTH` | 常量 | 调整列宽时每列的最小宽度，单位 mm。 |
| `planInsertFooterRow` | 函数 | 在第 index 个表尾行之前插入一行（index 等于行数时追加）。 |
| `planInsertTableColumn` | 函数 | 在第 index 列之前插入一列（index 等于列数时追加在末尾）；跨过插入位置的表尾单元格多跨一列，其余表尾行在新列处留空。 |
| `planMergeFooterCells` | 函数 | 合并表尾行里 columnIds 覆盖的列范围：与范围相交的单元格（含留空的列）合成一个，合并后的范围扩到它们的并集；保留最左边那个单元格的内容，最左边是留空的列时新建空白单元格。 |
| `planMoveTableColumn` | 函数 | 把一列移到第 index 位（按移动后的顺序数）。 |
| `planRemoveFooterRow` | 函数 | 删除一个表尾行。 |
| `planRemoveTableColumn` | 函数 | 删除一列：只占这一列的表尾单元格删除，跨过它的缩短一列，从它起跨的改由下一列起跨。 |
| `planResizeTableColumn` | 函数 | 把一列调到 width 宽，不小于 MIN_TABLE_COLUMN_WIDTH。 |
| `planSplitFooterCell` | 函数 | 把表尾行里从 columnId 起跨的单元格拆成只占一列，空出来的列留空。 |
| `TableColumnFit` | 类型 | 列宽怎样跟着变：keep 保持表格宽度、各列按比例缩放；resize 改变表格宽度、其余列不动。 |
| `TablePlanRefusal` | 类型 | 计划不能执行的原因：只剩一列、移动会拆开跨列的表尾单元格、所选范围只有一个单元格、单元格本来就不跨列。 |
| `TablePlanResult` | 类型 | 计划结果：成功时给出 updateElement 的属性修改。 |

### operations/types

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `AddBandOperation` | 接口 | 为页眉或页脚添加变体带区。 |
| `AddElementOperation` | 接口 | 向容器添加元素，`index` 缺省时放在最上层。 |
| `AddPageOperation` | 接口 | 添加页面模板，`index` 缺省时放在末尾。 |
| `MoveElementsOperation` | 接口 | 平移一组元素，单位 mm。 |
| `MovePageOperation` | 接口 | 移动页面模板到目标下标。 |
| `OperationResult` | 类型 | 操作结果，即 @xihan-ui/designer-kit 的 OperationResult：新文档，以及按顺序作用于新文档即可还原出传入文档的逆操作。 |
| `PrintOperation` | 类型 | 编辑操作。 |
| `PrintOperationType` | 类型 | 编辑操作的种类。 |
| `PropertyChange` | 接口 | 一处属性修改。 |
| `RemoveBandOperation` | 接口 | 删除页眉或页脚的变体带区及其中的元素。 |
| `RemoveElementOperation` | 接口 | 删除元素。 |
| `RemovePageOperation` | 接口 | 删除页面模板。 |
| `ReorderElementOperation` | 接口 | 调整元素在容器内的层级。 |
| `ReorderTarget` | 类型 | 层级调整目标：最上层、最下层、上移一层、下移一层，或容器内的目标下标。 |
| `ReplaceDocumentOperation` | 接口 | 整份换成另一份文档，如在 JSON 编辑框里改完应用；新文档由调用方先校验（validateDocument），操作只记下换之前的那份作逆操作。 |
| `ResizeElementOperation` | 接口 | 把元素缩放到新的元素框，元素原型可附带专属缩放行为。 |
| `UpdateDocumentOperation` | 接口 | 修改文档属性；不能修改 `schemaVersion` 与 `pages`。 |
| `UpdateElementOperation` | 接口 | 修改元素属性；不能修改 `id` 与 `type`。 |
| `UpdatePageOperation` | 接口 | 修改页面设置：名称、纸张、方向、边距、页码规则、水印、参考线、宿主附加数据，以及页眉页脚的 `singleSheet` 和已有带区的 `height`。 |

### registry/builtins

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `createBuiltinElementPrototypes` | 函数 | 生成全部内置元素原型，每次调用返回互不共享的新对象。 |
| `scaleTableColumns` | 函数 | 按新的总宽度等比缩放列宽，末列吸收舍入误差；原列宽合计不为正时均分。 |

### registry/part-properties

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `pageProperties` | 函数 | 页面设置的属性描述，路径相对页面模板；页眉页脚各变体的高度只在该变体存在时显示。 |
| `tableBodyProperties` | 函数 | 表体的属性描述，路径相对表体。 |
| `tableColumnProperties` | 函数 | 表格列的属性描述，路径相对列；条码码制只在单元格类型为条码时显示。 |
| `tableFooterCellProperties` | 函数 | 表尾单元格的属性描述，路径相对单元格。 |
| `tableFooterRowProperties` | 函数 | 表尾行的属性描述，路径相对表尾行；单元格另按表尾格编辑。 |
| `tableHeaderProperties` | 函数 | 表头的属性描述，路径相对表头；表头隐藏时只显示「是否显示」。 |

### registry/properties

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `behaviorProperties` | 函数 | 名称、锁定与只预览不打印。 |
| `boxProperties` | 函数 | `box` 下的背景、边框与内边距。 |
| `choices` | 函数 | 一组取值写成 select 编辑方式的选项。 |
| `layoutProperties` | 函数 | 坐标、宽高与可选的旋转角度。 |
| `property` | 函数 | 生成一条属性描述，缺省为元素上必须有的属性。 |
| `PropertyOptions` | 接口 | 属性描述的可选项。 |
| `textStyleProperties` | 函数 | `style` 下的文本样式。 |

### registry/registry

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `CreateElementInit` | 接口 | 创建元素的参数。 |
| `createElementRegistry` | 函数 | 创建元素类型登记表，默认登记全部内置元素；类型重复时抛出错误。 |
| `ElementCategoryGroup` | 接口 | 物料面板中的一个分组。 |
| `ElementRegistry` | 接口 | 元素类型登记表。 |

### registry/types

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `AnyElementPrototype` | 类型 | 任一元素的原型：内置元素的，或扩展元素的。 |
| `ELEMENT_CATEGORIES` | 常量 | 内置的物料分组，按面板中的显示顺序；扩展自定的分组排在它们之后。 |
| `ElementCategory` | 类型 | 内置的物料分组：文字、图片、数据、图形、条码。 |
| `ElementDefaults` | 类型 | 元素默认值：不含标识与坐标。 |
| `ElementFieldReference` | 接口 | 元素引用的一个数据字段。 |
| `ElementFieldsContext` | 接口 | 列字段引用时拿到的帮手：把常见的内容来源换成引用，扩展元素不必自己解析模板串与表达式。 |
| `ElementFlowContext` | 接口 | 跨页扩展元素取值时拿到的上下文：在排版上下文之上还能量文字。 |
| `ElementLayoutContext` | 接口 | 扩展元素排版时拿到的上下文。 |
| `ElementPrototype` | 接口 | 元素原型：一种元素的默认值、尺寸约束、可编辑属性与专属行为。 |
| `ElementValidationContext` | 接口 | 元素专属规则的校验上下文。 |
| `ExtensionElementPrototype` | 类型 | 扩展元素的原型：不跨页的给 layout，跨页的给 prepare。 |
| `ExtensionFlowBlock` | 接口 | 跨页扩展元素的一块：块不拆开，height 是它占的高度（mm），data 交给渲染，要是 JSON。 |
| `ExtensionFlowContent` | 接口 | 跨页扩展元素排出的内容：blocks 依次排；repeat 给了时排在每一段的开头（如表头），算进每段的高度。 |
| `FixedExtensionElementPrototype` | 接口 | 不跨页的扩展元素的原型：必须给出 layout。 |
| `FlowExtensionElementPrototype` | 接口 | 跨页的扩展元素的原型：必须给出 prepare；只能放在正文区。 |
| `NumberControl` | 类型 | 数值属性：designer-kit 的 number 编辑方式，单位取打印的单位。 |
| `PAGE_PROPERTY_GROUPS` | 常量 | 页面设置的属性分组取值，按面板中的显示顺序。 |
| `PROPERTY_GROUPS` | 常量 | 元素与表格部位的属性分组取值，按面板中的显示顺序。 |
| `PropertyControl` | 类型 | 属性编辑方式：@xihan-ui/designer-kit/properties 的内建编辑方式（数值的单位取打印的单位），加上打印专属的复合类型；复合类型由设计器提供对应的专用编辑器。 |
| `PropertyControlKind` | 类型 | 属性编辑方式的种类。 |
| `PropertyDescriptor` | 接口 | 可编辑属性描述：@xihan-ui/designer-kit/properties 的 PropertyDescriptor，path 相对元素；分组总是给出，显示条件写在 visibleWhen；required（显示时必须填写）不用，空值由打印自己的规则报告。 |
| `PropertyGroup` | 类型 | 属性面板分组：元素与表格部位用布局、内容、数据、文字、表格、条码、外观、行为，页面设置用页面、纸张、页眉页脚、页码、水印。 |
| `PropertyUnit` | 类型 | 数值属性的单位：mm、pt、角度、倍数或个数。 |
| `SidesControl` | 类型 | 四边距离：designer-kit 的 sides 编辑方式，单位取打印的单位。 |

### schema/common

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `BorderSides` | 接口 | 四边边框，缺省的一边不画线。 |
| `BoxStyle` | 接口 | 元素外框样式。 |
| `Color` | 类型 | 颜色：`#RGB`、`#RGBA`、`#RRGGBB`、`#RRGGBBAA` 或 `transparent`。 |
| `Edges` | 接口 | 四边距离，单位 mm。 |
| `ExpressionFormat` | 接口 | 表达式格式：以受限表达式把值转成显示文本，表达式中以 `value` 引用待格式化的值。 |
| `ExpressionTextContent` | 接口 | 以受限表达式计算的文本，表达式中的变量为数据对象的顶层字段。 |
| `FieldImageSource` | 接口 | 从数据字段读取图片地址。 |
| `FieldTextContent` | 接口 | 绑定单个数据字段。 |
| `ImageSource` | 类型 | 图片来源。 |
| `MapFormat` | 接口 | 值映射格式：按数据值查表显示文本。 |
| `StaticImageSource` | 接口 | 固定地址的图片。 |
| `StaticTextContent` | 接口 | 固定文本。 |
| `Stroke` | 接口 | 描边。 |
| `TemplateTextContent` | 接口 | 含 `{{path}}` 占位的文本模板，占位按数据字段替换。 |
| `TextContent` | 类型 | 文本内容来源。 |
| `TextStyle` | 接口 | 文本样式。 |
| `ValueFormat` | 类型 | 值格式：数字、百分比、日期与人民币大写即 @xihan-ui/expression 的 FormatSpec，交给注入的格式化器；值映射在本包内完成，表达式格式经表达式接入点。 |
| `ValueMapEntry` | 接口 | 值映射的一项：数据值（按字符串比较）与显示文本，与选择类组件的选项同一形状（不带 disabled）。 |

### schema/document

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `PageBand` | 接口 | 页眉或页脚的一个带区。 |
| `PageBandSet` | 接口 | 页眉或页脚：`default` 为常规带区，其余为按输出页命中的变体。 |
| `PageGuides` | 接口 | 参考线：设计时对位用，不参与分页也不打印；坐标相对纸张左上角（按页面方向换算后的纸张），单位 mm。 |
| `PageNumbering` | 接口 | 页码编号规则。 |
| `PaperSpec` | 接口 | 纸张。 |
| `PRINT_SCHEMA_VERSION` | 常量 | 当前模板 schema 版本。 |
| `PrintDocument` | 接口 | 打印模板文档。 |
| `PrintPage` | 接口 | 页面模板：一份页面模板按数据量排出一张或多张输出页。 |
| `PrintSchemaVersion` | 类型 | 模板 schema 版本号类型。 |
| `Watermark` | 接口 | 平铺文字水印。 |

### schema/elements

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `BarCodeElement` | 接口 | 一维条码。 |
| `BarCodeTextStyle` | 接口 | 条码下方文字的样式。 |
| `ElementBase` | 接口 | 全部元素共有的字段。 |
| `EllipseElement` | 接口 | 椭圆，内切于元素框。 |
| `ExtensionElement` | 接口 | 扩展登记的元素：通用字段之外的属性由扩展的原型定义，取值都是 JSON。 |
| `ImageElement` | 接口 | 图片。 |
| `LineElement` | 接口 | 直线，走向由元素框和方向共同决定。 |
| `LongTextElement` | 接口 | 随内容纵向延展并可跨页续排的长文本。 |
| `MatrixCodeElement` | 接口 | 二维码：QR、Data Matrix、PDF417、Aztec。 |
| `PageNumberElement` | 接口 | 页码。 |
| `PRINT_ELEMENT_TYPES` | 常量 | 内置元素类型列表。 |
| `PrintElement` | 类型 | 内置元素。 |
| `PrintElementOf` | 类型 | 按类型取元素接口。 |
| `PrintElementType` | 类型 | 内置元素类型。 |
| `RectElement` | 接口 | 矩形。 |
| `RichTextContent` | 类型 | 富文本的内容来源：模板里写死的文档，或从数据字段读取。 |
| `RichTextElement` | 接口 | 随内容纵向延展并可跨页续排的富文本：段落、标题、列表、分隔线与带样式的文字。 |
| `TableElement` | 接口 | 绑定数组数据、随行数延展并可跨页续排的表格。 |
| `TextElement` | 接口 | 固定尺寸的文本。 |

### schema/options

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `AGGREGATE_FUNCTIONS` | 常量 | 表格汇总函数取值。 |
| `AGGREGATE_SCOPES` | 常量 | 表格汇总范围取值。 |
| `AggregateFunction` | 类型 | 表格汇总函数。 |
| `AggregateScope` | 类型 | 表格汇总范围：page 本页数据，cumulative 截至本页的累计数据，all 全部数据。 |
| `BarCodeFormat` | 类型 | 转导出自 @xihan-ui/headless |
| `HORIZONTAL_ALIGNS` | 常量 | 单元格水平对齐取值。 |
| `HorizontalAlign` | 类型 | 单元格水平对齐。 |
| `IMAGE_FITS` | 常量 | 图片适配方式取值。 |
| `ImageFit` | 类型 | 图片在元素框内的适配方式。 |
| `LINE_DIRECTIONS` | 常量 | 直线方向取值。 |
| `LineDirection` | 类型 | 直线在元素框内的走向：horizontal 沿垂直中线，vertical 沿水平中线，diagonalDown 左上到右下，diagonalUp 左下到右上。 |
| `MatrixCodeFormat` | 类型 | 转导出自 @xihan-ui/headless |
| `MatrixCodeLevel` | 类型 | 转导出自 @xihan-ui/headless |
| `PAGE_BAND_VARIANTS` | 常量 | 页眉页脚的页面变体键。 |
| `PAGE_ORIENTATIONS` | 常量 | 页面方向取值。 |
| `PageBandKey` | 类型 | 页眉页脚的全部带区键，`default` 为未命中任何变体时使用的带区。 |
| `PageBandVariant` | 类型 | 页眉页脚变体：first 首页、last 末页、odd 奇数页、even 偶数页（按页码奇偶）。 |
| `PageOrientation` | 类型 | 页面方向：portrait 纵向，landscape 横向（宽高互换）。 |
| `RICH_TEXT_SOURCES` | 常量 | 富文本字段的内容格式取值。 |
| `RichTextSource` | 类型 | 富文本字段的内容格式：html 为 HTML 串，按白名单换成文档；document 为富文本文档对象。 |
| `SINGLE_SHEET_PREFERENCES` | 常量 | 同一输出页既是首页又是末页时优先采用的变体取值。 |
| `SingleSheetPreference` | 类型 | 同一输出页既是首页又是末页时优先采用的变体。 |
| `STROKE_STYLES` | 常量 | 线型取值。 |
| `StrokeStyle` | 类型 | 线型。 |
| `TABLE_CELL_TYPES` | 常量 | 表格列单元格的呈现类型取值。 |
| `TABLE_FOOTER_PLACEMENTS` | 常量 | 表尾行出现位置取值。 |
| `TABLE_ROW_HEIGHT_MODES` | 常量 | 表体行高模式取值。 |
| `TableCellType` | 类型 | 表格列单元格的呈现类型。 |
| `TableFooterPlacement` | 类型 | 表尾行出现位置：everyPage 表格所跨的每一页，lastPage 仅表格结束的那一页。 |
| `TableRowHeightMode` | 类型 | 表体行高模式：fixed 每行固定为设定的行高，minimum 以设定的行高为下限、按单元格内容撑高。 |
| `TEXT_ALIGNS` | 常量 | 文本水平对齐取值。 |
| `TEXT_OVERFLOWS` | 常量 | 固定尺寸文本的溢出处理取值。 |
| `TextAlign` | 类型 | 文本水平对齐。 |
| `TextOverflow` | 类型 | 固定尺寸文本的溢出处理：clip 裁切，shrink 缩小字号以容纳，visible 允许溢出显示。 |
| `VERTICAL_ALIGNS` | 常量 | 垂直对齐取值。 |
| `VerticalAlign` | 类型 | 垂直对齐。 |

### schema/table

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `AggregateCellContent` | 接口 | 表尾单元格的汇总内容。 |
| `CellStyle` | 接口 | 单元格样式。 |
| `TableBody` | 接口 | 表体。 |
| `TableBorder` | 接口 | 表格网格线。 |
| `TableCellContent` | 类型 | 表体单元格内容来源。 |
| `TableColumn` | 接口 | 表格列。 |
| `TableExpressionCellContent` | 接口 | 表体单元格以受限表达式计算，表达式中的变量为行对象的顶层字段。 |
| `TableFieldCellContent` | 接口 | 表体单元格显示行内字段。 |
| `TableFooterCell` | 接口 | 表尾单元格。 |
| `TableFooterCellContent` | 类型 | 表尾单元格内容：固定文本、根数据字段、根数据模板或汇总值。 |
| `TableFooterRow` | 接口 | 表尾行，可承载固定文字、根数据字段与汇总值。 |
| `TableHeader` | 接口 | 表头。 |
| `TableRowNumberCellContent` | 接口 | 表体单元格显示从 1 开始、跨页连续的行序号。 |
| `TableTemplateCellContent` | 接口 | 表体单元格按行对象替换 `{{path}}` 占位。 |

### traverse

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `ElementContainerRef` | 类型 | 元素容器：页面正文，或页眉、页脚中的某个带区。 |
| `ElementLocation` | 接口 | 元素在文档中的位置。 |
| `ElementRegion` | 类型 | 元素所在区域：正文、页眉或页脚。 |
| `findElement` | 函数 | 按标识查找元素。 |
| `findPage` | 函数 | 按标识查找页面及其下标。 |
| `forEachElement` | 函数 | 按页面、正文、页眉、页脚的顺序遍历全部元素。 |
| `getContainerElements` | 函数 | 取容器的元素数组；页面或带区不存在时返回 undefined。 |
| `getContainerPath` | 函数 | 取容器元素数组相对页面的 JSON 路径。 |
| `listContainers` | 函数 | 列出页面上的全部容器，按正文、页眉、页脚的顺序。 |
| `listPageBandKeys` | 函数 | 列出页眉或页脚中已存在的带区键。 |
| `PAGE_BAND_KEYS` | 常量 | 页眉页脚带区键，按 default、first、last、odd、even 的顺序。 |

### validation/checks

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `isValidColor` | 函数 | 判断颜色是否为 `transparent` 或以 `#` 开头的 3、4、6、8 位十六进制色，判据即 designer-kit 的 color 编辑方式。 |

### validation/issues

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `ExtensionIssueCode` | 类型 | 扩展自己的问题码：扩展 id 的末段加点开头，如 seal.noImage；没有登记严重程度，缺省按 error。 |
| `IssueParams` | 类型 | 问题参数，供各语言文案插值。 |
| `VALIDATION_ISSUE_SEVERITIES` | 常量 | 全部问题码及其固定的严重程度：不带前缀的是 @xihan-ui/designer-kit/schema 的通用问题码，带前缀的是打印专属的问题码。 |
| `ValidationIssue` | 类型 | 校验问题：@xihan-ui/designer-kit/schema 的 SchemaIssue，严重程度总是给出。 |
| `ValidationIssueCode` | 类型 | 问题码。 |
| `ValidationReport` | 接口 | 校验报告。 |

### validation/validate

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `validateDocument` | 函数 | 校验模板文档：先检查 JSON 纯度，再按 schema、属性描述与元素专属规则逐层校验。 |
| `ValidateDocumentOptions` | 接口 | 校验选项。 |

---

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

# 设计器

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

`@xihan-print/designer` 的公开接口。样式在 `@xihan-print/designer/style.css`，还要同时引入 `@xihan-ui/designer-shell/style.css` 与 `@xihan-print/runtime/style.css`。

## `<xh-print-designer>`

注册 &lt;xh-print-designer&gt;；重复调用不报错。

### 属性

| 属性 | attribute | 类型 | 说明 |
| --- | --- | --- | --- |
| `data` | — | `unknown` | 预览分页用的数据。 |
| `sampleData` | — | `unknown` | 示例数据：给出时画布按它显示实际值，不给时字段显示 {path} 占位。 |
| `fields` | — | `readonly DataField[] \| undefined` | 可绑定的字段树：物料面板「字段」组与属性面板的字段选择器读它；导入字段时设计器换掉它并派发 fields-change。 |
| `fieldsReadonly` | `fields-readonly` | `boolean` | 字段由宿主管着、不许在设计器里导入：物料面板头没有导入字段钮，import-fields 命令不可用。attribute 为 fields-readonly。 |
| `expressionEngine` | — | `ExpressionEngine \| undefined` | 受限表达式引擎；缺省为 @xihan-ui/expression 的 createExpressionEngine()。 |
| `formatter` | — | `ValueFormatter \| undefined` | 值格式化器；缺省为 @xihan-ui/expression 的 formatValue。 |
| `measurer` | — | `TextMeasurer \| undefined` | 文字度量器；缺省用所在文档的 Canvas 度量器。 |
| `printClient` | — | `PrintClient \| undefined` | 本地打印客户端：给了时打印先交给它静默打印，连不上客户端才退回浏览器打印；设置里的打印方式选了浏览器时直接用浏览器打印。给了它，设置对话框才有打印方式一项与「本地客户端」一页。 |
| `clientDownloadUrl` | `client-download-url` | `string \| undefined` | 设置对话框「本地客户端」一页里「下载客户端」链接的地址，缺省 PRINT_CLIENT_DOWNLOAD_URL；attribute 为 client-download-url。 |
| `locale` | `locale` | `string \| undefined` | 交给格式化器的区域，只决定小数点与千分位符号；同名 attribute。 |
| `timeZone` | `time-zone` | `string \| undefined` | 交给格式化器的时区：`UTC`、`±HH:mm` 或 IANA 名称；attribute 为 time-zone。 |
| `translations` | — | `Partial<PrintDesignerTranslations> \| undefined` | 元素自己的文案，压在全局配置之上。 |
| `readonly` | `readonly` | `boolean` | 只读：可以选择、浏览与预览，不能修改。attribute 三态：不写或移除为不只读，写 "false" 为不只读，其余写法为只读。 |
| `mode` | `mode` | `PrintDesignerMode` | 设计态或预览态，缺省 design；同名 attribute。 |
| `defaultLayout` | — | `DesignerLayout \| undefined` | 宿主的缺省面板布局：用户没存过布局（settings 里没有 layout.panels）时用它，「恢复默认布局」也回到它；写了的字段整项覆盖内置缺省。面板 id 见 PRINT_DESIGNER_PANELS。 |
| `commandLayout` | — | `DesignerCommandLayout \| undefined` | 工具栏与右键菜单的排列：位置（toolbar、menu:blank、menu:element、menu:table）→ 若干组命令 id，内置与扩展的命令可以混排。写了某个位置就只显示列出的命令；写了没登记的命令 id 时抛 TypeError。 |
| `settings` | — | `DesignerSettings \| undefined` | 设置的值：扁平的键值，键是「分区 id.条目 id」，如 general.theme、print.showGrid；没写的键取条目的缺省值。赋值即生效；用户在设置对话框里或用工具栏上的网格、吸附开关改了以后，设计器换成新的一份并派发 settings-change。 |
| `settingsPolicy` | — | `DesignerSettingsPolicy \| undefined` | 宿主对设置条目的管控：键是条目键或分区 id，hidden 不显示，locked 只读、说明换成「由所在系统管理」。 |
| `settingsStorageKey` | `settings-storage-key` | `string \| undefined` | 设置存在根所在窗口 localStorage 的哪个键下：给了，连上文档时若没赋 settings 就从这里读，用户改了设置就写回去，标了 secret 的条目不存；读写失败派发 settings-storage-error。不给就不读写。同名 attribute settings-storage-key。 |
| `draftKey` | `draft-key` | `string \| undefined` | 自动保存草稿的键：区分同一页、同一种设计器里的不同模板（宿主写模板 id）；不给时按页面地址区分。设置里开着自动保存时，未保存的修改停手约一秒存成这台浏览器里的草稿，保存（markSaved）后删掉；下次装进同一个键的模板、和草稿不一样时问恢复还是丢弃。同名 attribute draft-key。 |
| `autoTour` | `auto-tour` | `boolean \| undefined` | 第一次在设计态显示出来（画布有了尺寸）后自动开始新手引导，缺省开；设置里记过 help.tourDone（走完、跳过或关上过一次）时不再自动开始。写 false 关掉，start-tour 命令、帮助页的「开始引导」与 startTour() 照样能开始。同名 attribute auto-tour，写 "false" 是关。 |

### 存取器

| 属性 | 读写 | 类型 | 说明 |
| --- | --- | --- | --- |
| `xhConfig` | 只读 | `XhConfig` | 设计器这棵子树的配置：设置里选了语言时是这一语言的 UI、designer-shell 与打印语言包，跟随页面时是空对象。设计器自己、里面的元素与它弹出的浮层都按它取 locale 与文案，页面别处不受影响。 |
| `schema` | 可读写 | `PrintDocument` | 打印模板。赋值即装载：清空历史与选择，按实际大小放到视口左上（赋回当前这一份不重新装载）；读取时得到当前模板。 |
| `activePageId` | 可读写 | `string` | 当前页面模板的标识；赋值切换页面模板。 |
| `canUndo` | 只读 | `boolean` | 是否有可以撤销的修改。 |
| `canRedo` | 只读 | `boolean` | 是否有可以重做的修改。 |
| `dirty` | 只读 | `boolean` | 有未保存的修改。 |
| `extensions` | 可读写 | `readonly PrintDesignerExtension[] \| undefined` | 扩展：元素种类、编辑方式、规则、属性编辑器、命令与面板都从这里来，设计器自带的扩展与内置元素自动排在最前。赋值时当场合并查重，冲突抛 DesignerExtensionError、什么都不变；各扩展的 setup 在元素连上文档时调用、断开时清理。同一个扩展对象换了引用当作卸下再装上，宿主要保持引用稳定。 |

### 方法

| 方法 | 说明 |
| --- | --- |
| `execute(operations: readonly PrintOperation[], options?: ExecuteOptions): PrintDocument` | 执行一组操作并记为一步撤销；返回新的模板。 |
| `undo(): boolean` | 撤销一步；没有可撤销的修改时返回 false。 |
| `redo(): boolean` | 重做一步；没有可重做的修改时返回 false。 |
| `markSaved(): void` | 把当前状态记为已保存。 |
| `addElement(type: string, at?: Point, options?: { readonly region?: ElementRegion }): PrintElement` | 新建元素并选中：at 是元素中心的纸张坐标（mm），缺省放在视口中央；位置吸附网格，region 缺省按落点所在区决定。 |
| `select(selection: Partial<PrintSelection>): void` | 替换当前选择；不在当前页面模板正文与当前显示的页眉页脚变体里的元素会被忽略。 |
| `getSelection(): PrintSelection` | 当前选择。 |
| `deleteSelection(): boolean` | 删除选中的元素；只读或没有选中时返回 false。 |
| `copy(): PrintClipboard \| undefined` | 复制选中的元素；没有选中时返回 undefined。 |
| `cut(): PrintClipboard \| undefined` | 复制并删除选中的元素；只读或没有选中时返回 undefined。 |
| `paste(clipboard?: PrintClipboard): PrintSelection` | 粘贴到当前页面模板并选中粘贴出的元素；缺省用最近一次复制的内容，连续粘贴依次错开。只读时不粘贴。 |
| `duplicate(): PrintSelection` | 复制选中的元素并立即粘贴，不改动剪贴板；只读时什么都不做。 |
| `align(mode: AlignMode): void` | 对齐选中的元素；少于两个或只读时什么都不做。 |
| `distribute(axis: DistributeAxis): void` | 等距分布选中的元素；少于三个或只读时什么都不做。 |
| `reorder(target: ReorderTarget): void` | 调整选中元素的层级。 |
| `openSettings(section?: string): void` | 打开设置对话框，给了分区 id 就显示那一页：基础是 general，设计器自己的「画布」是 print。 |
| `openJsonEditor(): void` | 打开编辑整份模板 JSON 的对话框：写出当前模板，边改边按打印的校验报问题；没有错误时「应用」整份换上，记一步撤销。只读时只能看、不能应用。 |
| `startTour(): boolean` | 从头开始新手引导：通用步骤加打印与扩展的步骤，同一页里别的引导开着时先收起它；预览态或没有能走的步骤时返回 false。 |
| `openFieldImport(source?: string): void` | 打开导入字段对话框，给了页 id 就显示那一页：内置的是 sample 与 json-schema，扩展的字段来源用它的 id。 |
| `validate(): ValidationIssue[]` | 按当前登记表与表达式引擎校验模板。 |
| `getViewport(): Viewport` | 视口：屏幕坐标 = 纸张坐标（mm）× zoom × 96 / 25.4 + (x, y)；zoom 为 1 时是实际尺寸。 |
| `setViewport(viewport: Viewport): void` | 设置视口；此后尺寸变化不再自动适配。 |
| `zoomToFit(): void` | 让整张纸连同左侧的页眉页脚标签落在视口中央，让开浮在画布一侧的翻页条（让出的宽度与四周留白取较大的那个），不放大到实际尺寸以上；此后尺寸变化时重新适配，直到设置视口或在画布上操作。 |
| `zoomIn(): void` | 以视口中心放大一档。 |
| `zoomOut(): void` | 以视口中心缩小一档。 |
| `zoomToActual(): void` | 实际尺寸，纸张居中。 |
| `scrollToElement(id: string): void` | 切到元素所在的页面模板与带区变体，并把元素居中。 |
| `revealElement(id: string): void` | 切到元素所在的页面模板与带区变体；元素没整个落在视口内时把它居中。 |
| `clientToWorld(clientX: number, clientY: number): Point` | 浏览器视口坐标换成纸张坐标（mm）。 |
| `print(options?: PrintPreviewPrintOptions): Promise<PrintOutcome>` | 按当前模板与 data 打印，等同 &lt;xh-print-preview&gt; 的 print。 |

### 事件

事件都是冒泡的 `CustomEvent`。

| 事件 | detail | 说明 |
| --- | --- | --- |
| `schema-change` | `{ schema: PrintDocument, operations: readonly PrintOperation[], kind: PrintSchemaChangeKind }` | 模板变了：schema 为变化后的模板，operations 为实际应用的操作；一次拖动、一次属性编辑等事务提交时合成一次，宿主装载新模板时 kind 为 load、operations 为空。 |
| `selection-change` | `PrintSelection` | 选择变了，detail 为当前选择。 |
| `dirty-change` | `{ dirty: boolean }` | 是否有未保存的修改变了。 |
| `issues-change` | `{ issues: readonly ValidationIssue[] }` | 模板改动或登记表、表达式引擎换了之后重新校验，detail 为全部校验问题。 |
| `viewport-change` | `{ viewport: Viewport }` | 视口变了，取值同 getViewport()。 |
| `save` | `Record<string, never>` | 执行了保存命令 save：选了菜单栏的「文件 → 保存」，或设计态下焦点在设计器里（输入框与面板之外）时按了 Ctrl / ⌘ + S；设计器不保存，宿主保存后调用 markSaved()。 |
| `element-dblclick` | `{ id: string }` | 双击元素；双击表格时同时进入表格编辑态。 |
| `element-contextmenu` | `{ id: string, x: number, y: number }` | 在元素上打开右键菜单，未选中的元素先被选中；可取消，取消后不弹设计器自带的菜单。 |
| `blank-contextmenu` | `{ x: number, y: number }` | 在画布空白处打开右键菜单；可取消，取消后不弹设计器自带的菜单。 |
| `table-contextmenu` | `{ id: string, part: PrintTablePart, x: number, y: number }` | 在表格编辑态里打开右键菜单，右键处的表格部位先被选中；可取消，取消后不弹设计器自带的菜单。 |
| `import-error` | `{ importer: string, source: DesignerImportSource, error: unknown }` | 导入器没能导入粘贴或拖放进来的内容：它抛了错，或给出的元素没有通过校验；importer 是导入器的 id。 |
| `page-change` | `{ pageId: string }` | 当前页面模板变了。 |
| `mode-change` | `{ mode: PrintDesignerMode }` | 在设计态与预览态之间切换了。 |
| `settings-change` | `{ key: string, value: JsonValue \| undefined, settings: DesignerSettings }` | 改了一条设置（设置对话框里，或工具栏上的网格、吸附开关）：设计器已换成新的 settings 并生效；value 为 undefined 表示删掉这个键、回到缺省值。宿主存起来，下次赋回 settings。 |
| `settings-storage-error` | `VisualEnvironmentStorageError` | 读写 settingsStorageKey 指的本机存储失败（内容不是对象、无痕窗口、配额满）；设置留在内存里。 |
| `fields-change` | `{ fields: readonly DataField[] }` | 在导入字段对话框里导入了字段：设计器已换成新的 fields。宿主存起来，下次赋回 fields。 |
| `sample-data-change` | `{ sampleData: JsonValue }` | 导入字段时勾了「同时作为示例数据」：设计器已换成新的 sampleData。宿主存起来，下次赋回 sampleData。 |

## 类型

### PrintDesignerMode {#printdesignermode}

设计态或预览态。取值：`design`、`preview`。

### PrintSchemaChangeKind {#printschemachangekind}

schema-change 的种类：执行操作、撤销、重做，或宿主装载了新模板。取值：`execute`、`undo`、`redo`、`load`。

### PrintSelection {#printselection}

选择：都在当前页面模板的正文与当前显示的页眉页脚变体里；tablePart 只在表格编辑态下出现。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `elements` | `readonly string[]` |  |
| `tablePart?` | `PrintTablePart` |  |

### PrintTablePart {#printtablepart}

表格编辑态下选中的部位。

`| { readonly kind: 'column', readonly elementId: string, readonly columnId: string } | { readonly kind: 'header' | 'body', readonly elementId: string } | { readonly kind: 'footerRow', readonly elementId: string, readonly rowId: string } | { readonly kind: 'footerCell', readonly elementId: string, readonly rowId: string, readonly columnId: string }`

### PrintClipboard {#printclipboard}

剪贴板内容：被复制的元素与它们所在的区域。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `elements` | `readonly PrintElement[]` |  |
| `region` | `ElementRegion` |  |

### PrintDesignerTranslations {#printdesignertranslations}

设计器的文案。

文案键是 `xh-print-designer`，中文在 `@xihan-print/runtime/locale` 的 `printZhCN` 里。

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `label` | `string` | 设计器的可访问名。 |
| `canvas` | `string` | 画布区域的可访问名。 |
| `grid` | `string` | 显示网格的开关。 |
| `snap` | `string` | 吸附其它元素与参考线的开关。 |
| `print` | `string` |  |
| `pages` | `string` | 画布右侧翻页条的可访问名。 |
| `minimap` | `string` | 画布左下角小地图的名字：面板菜单与设置的「布局」页里用。 |
| `menuInsert` | `string` | 菜单栏上「插入」菜单的名字：各种元素与页眉页脚的变体。 |
| `menuPage` | `string` | 菜单栏上「页面」菜单的名字：纸张、方向与页面模板。 |
| `previousPage` | `string` |  |
| `nextPage` | `string` |  |
| `addPage` | `string` |  |
| `duplicatePage` | `string` |  |
| `removePage` | `string` |  |
| `movePageUp` | `string` |  |
| `movePageDown` | `string` |  |
| `regions` | `Readonly<Record<ElementRegion, string>>` | 页眉、正文、页脚的名称。 |
| `bandVariants` | `Readonly<Record<PageBandKey, string>>` | 页眉页脚变体的名称。 |
| `addBandVariant` | `string` |  |
| `removeBandVariant` | `string` |  |
| `elements` | `Readonly<Record<PrintElementType, string>>` | 元素种类的名称。 |
| `categories` | `Readonly<Record<ElementCategory, string>>` | 物料分组的名称。 |
| `tableParts` | `Readonly<Record<PrintTablePartKind, string>>` | 表格部位的名称。 |
| `editTable` | `string` |  |
| `exitTableEdit` | `string` |  |
| `insertColumnLeft` | `string` |  |
| `insertColumnRight` | `string` |  |
| `removeColumn` | `string` |  |
| `moveColumnLeft` | `string` |  |
| `moveColumnRight` | `string` |  |
| `insertFooterRowAbove` | `string` |  |
| `insertFooterRowBelow` | `string` |  |
| `removeFooterRow` | `string` |  |
| `mergeCellRight` | `string` |  |
| `splitCell` | `string` |  |
| `history` | `PrintHistoryTranslations` | 撤销历史里一步的说明。 |
| `palette` | `string` | 物料面板的标题。 |
| `fieldGroup` | `string` | 物料面板里按 fields 列出的字段那一组的名称。 |
| `properties` | `string` | 属性面板的标题。 |
| `issues` | `string` | 问题列表的标题。 |
| `paletteHelp` | `string` | 物料面板头里的帮助。 |
| `propertiesHelp` | `string` | 属性面板头里的帮助。 |
| `issuesHelp` | `string` | 问题列表面板头里的帮助。 |
| `settingsPrint` | `string` | 设置对话框里设计器自己那一页（打印方式与画布偏好）的名称。 |
| `settingsShowGrid` | `string` |  |
| `settingsShowGridHint` | `string` |  |
| `settingsGridSize` | `string` |  |
| `settingsGridSizeHint` | `string` |  |
| `settingsSnap` | `string` |  |
| `settingsSnapHint` | `string` |  |
| `settingsShowMargins` | `string` |  |
| `settingsShowMarginsHint` | `string` |  |
| `settingsRulers` | `string` | 设置「打印」分区：标尺开关。 |
| `settingsRulersHint` | `string` |  |
| `tourSteps` | `Readonly<Record<PrintTourStepKey, PrintTourStepTranslations>>` | 新手引导里打印自己的几步：页眉页脚、页面模板、字段物料与打印。 |
| `helpNotes` | `readonly string[]` | 设置对话框「帮助」页的几段操作说明。 |
| `shortcutNudge` | `string` | 快捷键表「通用」里方向键那一行：移动选中的元素，没有选中时平移画布。 |
| `shortcutCancel` | `string` | 快捷键表「通用」里 Esc 那一行：取消拖动、退出表格编辑或取消选择。 |
| `settingsVia` | `string` | 「打印」页里打印方式一项：经本地打印客户端，还是浏览器的打印对话框。 |
| `settingsViaHint` | `string` |  |
| `settingsViaOptions` | `Readonly<Record<'client' \| 'browser', string>>` |  |
| `settingsClient` | `string` | 设置对话框里「本地客户端」那一页的名称。 |
| `settingsClientStatus` | `string` | 「本地客户端」页里连接状态一项。 |
| `settingsClientStatusHint` | `string` |  |
| `settingsClientStates` | `Readonly<Record<'connected' \| 'disconnected' \| 'missing', string>>` | 连接状态的三种说法：已连接；未连接；最近一次测试连接没找到客户端时是未安装。 |
| `settingsClientTest` | `string` |  |
| `settingsClientDownload` | `string` |  |
| `statusZoom` | `string` | 状态栏右段缩放一项的标签。 |
| `statusClient` | `string` | 状态栏右段打印客户端一项的标签。 |
| `statusClientStates` | `Readonly<Record<PrintClientState, string>>` | 打印客户端连接状态的说法。 |
| `selectionToolbar` | `string` | 选中元素后浮在选中框上方的选中工具条的名字。 |
| `alignTextLeft` | `string` |  |
| `alignTextCenter` | `string` |  |
| `alignTextRight` | `string` |  |
| `propertyGroups` | `Readonly<Record<PropertyGroup, string>>` | 属性分组的名称。 |
| `propertyNames` | `Readonly<Record<string, string>>` | 属性名：键为 formatJsonPath(path)；「对象种类:路径」覆盖同一路径在该种类上的名字，对象种类是 page、元素种类或 table-column 等表格部位。复合属性拆开后的分项用「复合种类/分项」作键，如 stroke/width、edges/top。 |
| `propertyOptions` | `Readonly<Record<string, string>>` | select 选项名：键为选项值；「路径=选项值」覆盖该属性上的名字。 |
| `units` | `Readonly<Record<PropertyUnit, string>>` | 数值属性的单位。 |
| `pageSettings` | `string` | 属性面板在没有选中时编辑页面设置，标题下的一行。 |
| `pageNumberInsert` | `string` | 页码格式编辑器里插入变量的菜单按钮。 |
| `pageNumberTokens` | `Readonly<{ page: string, pages: string }>` | 页码格式里能插入的两个变量：当前页码与总页数。 |
| `valueFormatKind` | `string` | 值格式编辑器里种类下拉的名字。 |
| `valueFormatKinds` | `Readonly<{ none: string, format: string, map: string, expression: string }>` | 值格式的种类：不设格式、常用格式（数字、百分比、日期、人民币大写、数字字形）、值映射、表达式。 |
| `valueMapColumns` | `Readonly<{ value: string, label: string }>` | 值映射表的两列：数据值与显示文本。 |
| `valueMapFallback` | `string` | 值映射里没有命中任何一项时显示的文本。 |

| 方法 | 说明 |
| --- | --- |
| `pagePosition(position: number, count: number, name: string): string` | 翻页条上页码按钮的名字：含按钮上写的「第几个 / 共几个」，再加页面名称（没有名称时是 pageTitle），position 从 1 开始。按钮上看得见的字要包含在名字里。 |
| `pageTitle(position: number): string` | 没有名称的页面模板的标题，position 从 1 开始。 |
| `resizeBand(region: 'header' \| 'footer'): string` | 拖动调整页眉或页脚高度的把手的可访问名。 |
| `elementLabel(type: string, name: string): string` | 画布上一个元素的可访问名：种类名加元素名称或标识。 |
| `resizeColumn(title: string): string` | 拖动调整列宽的把手的可访问名。 |
| `newColumnTitle(position: number): string` | 新插入的列的标题，position 从 1 开始。 |
| `statusElements(count: number): string` | 状态栏左段没有选中时的值：当前页面模板上可见的元素个数。 |
| `statusGeometry(x: string, y: string, width: string, height: string): string` | 状态栏左段选中一个元素时的值：入参是格式化后的位置与尺寸（mm）。 |
| `fontSizeMenu(size: string): string` | 格式工具条上字号菜单的名字：含按钮上写的字号，选中的几处字号不一时是 —。 |
| `issue(issue: SchemaIssue): string` | 校验问题与分页诊断的说明，按问题码与参数生成。 |
| `propertyPart(parent: string, part: string): string` | 复合属性拆开后分项的名字，如「页边距 · 上」。 |
| `selectedCount(count: number): string` | 属性面板在选中多个元素时标题下的一行。 |
| `pageNumberSample(text: string): string` | 页码格式的示例，入参是按第 1 页、共 3 页填好的文字。 |
| `valueMapCell(index: number, column: string): string` | 值映射表里一格的名字，index 从 1 起，column 是列名。 |

## 编辑模型

设计器内部的编辑模型也一并导出，不显示界面、只想按操作改模板时可以直接用。创建打印编辑模型。

```ts
declare function createPrintEditor(options: PrintEditorOptions): PrintEditor
```

### PrintEditorOptions {#printeditoroptions}

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `document` | `PrintDocument` |  |
| `extensions?` | `readonly PrintCoreExtension[]` | 扩展：元素种类、编辑方式与规则，内置扩展自动排在最前。 |
| `historyLimit?` | `number` | 撤销步数上限，缺省 100。 |
| `mergeWithin?` | `number` | 同一合并键相隔多少毫秒内并入上一步，缺省 1000。 |

| 方法 | 说明 |
| --- | --- |
| `now(): number` |  |
| `describe(operations: readonly PrintOperation[], before: PrintDocument): HistoryLabel \| undefined` | 没给说明的一步，按正向操作与应用前的文档生成说明。 |

### PrintEditor {#printeditor}

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `document` | `PrintDocument` |  |
| `elements` | `ElementRegistry` | 当前扩展合出的元素登记表。 |
| `history` | `History<PrintDocument, PrintOperation>` |  |
| `selection` | `PrintSelection` |  |
| `activePageId` | `string` |  |
| `page` | `PrintPage` | 当前页面模板。 |
| `bands` | `PrintBandView` |  |

| 方法 | 说明 |
| --- | --- |
| `setExtensions(extensions: readonly PrintCoreExtension[]): void` | 换一组扩展：之后的编辑操作与校验都按它；冲突时抛 DesignerExtensionError、什么都不变。 |
| `load(document: PrintDocument): void` | 装载新文档：清空历史与选择，当前页面回到第一张；文档变化的 cause 为 reset。 |
| `execute(operations: readonly PrintOperation[], options?: ExecuteOptions): PrintDocument` | 执行一组操作并记为一步撤销；返回新文档。 |
| `undo(): boolean` |  |
| `redo(): boolean` |  |
| `seal(): void` | 封口：此后带同一合并键的修改另起一步。 |
| `setActivePage(pageId: string): void` | 切换当前页面模板并清空选择；页面不存在时抛错。 |
| `setBandVariant(region: 'header' \| 'footer', key: PageBandKey): void` | 切换页眉或页脚当前显示的变体；变体不存在时用 default。选择里不再显示的元素随之取消选择。 |
| `select(selection: Partial<PrintSelection>, mode?: PrintSelectMode): void` |  |
| `selectAll(): void` |  |
| `clearSelection(): void` |  |
| `visibleElements(): { readonly element: PrintElement, readonly region: ElementRegion }[]` | 当前页面模板里可见的元素（正文与当前显示的页眉页脚变体），按页眉、正文、页脚的层级顺序。 |
| `addElement(type: string, init: PrintAddElementInit, options?: ExecuteOptions): PrintElement` | 按元素类型新建元素并选中它；类型未登记时抛错。 |
| `deleteSelection(options?: ExecuteOptions): boolean` | 删除选中的元素；没有选中时返回 false。 |
| `moveElements(ids: readonly string[], dx: number, dy: number, options?: ExecuteOptions): void` | 平移一组元素，单位 mm；位移为零或元素为空时什么都不做。 |
| `reorder(target: ReorderTarget, options?: ExecuteOptions): void` | 调整选中元素的层级；多个元素按选中先后依次调整。 |
| `align(mode: AlignMode, options?: ExecuteOptions): void` | 对齐选中的元素；少于两个时什么都不做。 |
| `distribute(axis: DistributeAxis, options?: ExecuteOptions): void` | 等距分布选中的元素；少于三个时什么都不做。 |
| `copy(): PrintClipboard \| undefined` | 复制选中的元素；没有选中时返回 undefined。 |
| `cut(options?: ExecuteOptions): PrintClipboard \| undefined` | 复制并删除选中的元素。 |
| `paste(clipboard?: PrintClipboard, options?: ExecuteOptions & { readonly offset?: number }): PrintSelection` | 粘贴到当前页面模板并选中粘贴出的元素；缺省用最近一次 copy 的内容，每次粘贴比上一次多偏移 offset（mm）。 |
| `duplicate(options?: ExecuteOptions & { readonly offset?: number }): PrintSelection` | 复制选中内容并立即粘贴，不改动剪贴板。 |
| `addPage(index?: number, options?: ExecuteOptions): PrintPage` | 在 index 处（缺省末尾）新增一张页面模板并切到它。 |
| `duplicatePage(pageId: string, options?: ExecuteOptions): PrintPage` | 复制页面模板：页面与其中的元素换新 id，放在原页之后并切到它；页面不存在时抛错。 |
| `removePage(pageId: string, options?: ExecuteOptions): boolean` | 删除页面模板；只剩一张时不删并返回 false。 |
| `movePage(pageId: string, index: number, options?: ExecuteOptions): void` |  |
| `addBand(region: 'header' \| 'footer', variant: PageBandVariant, options?: ExecuteOptions): void` | 为当前页面模板的页眉或页脚新增变体（高度取 default 的高度）并切到它；已存在时只切换。 |
| `removeBand(region: 'header' \| 'footer', variant: PageBandVariant, options?: ExecuteOptions): void` | 删除当前页面模板页眉或页脚的变体及其中的元素。 |
| `setBandHeight(region: 'header' \| 'footer', key: PageBandKey, height: number, options?: ExecuteOptions): void` | 设置当前页面模板某个带区的高度，单位 mm。 |
| `applyTablePlan(tableId: string, plan: TablePlanResult, options?: ExecuteOptions): boolean` | 按 core 的表格计划修改表格；计划被拒时不改文档并返回 false。 |
| `validate(): ValidationIssue[]` |  |
| `subscribe(listener: (change: PrintEditorChange) => void): () => void` |  |

## 全部导出

### editor

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `createPrintEditor` | 函数 | 创建打印编辑模型。 |
| `elementRect` | 函数 | 元素外框：带旋转角的元素按旋转后的形状参与对齐与分布。 |
| `PrintAddElementInit` | 接口 | 新建元素的参数：位置为左上角，单位 mm；region 缺省为正文，页眉页脚放进当前显示的变体。 |
| `PrintBandView` | 接口 | 当前页面模板显示的页眉与页脚变体。 |
| `PrintClipboard` | 接口 | 剪贴板内容：被复制的元素与它们所在的区域。 |
| `PrintEditor` | 接口 |  |
| `PrintEditorChange` | 类型 | 编辑模型的变化：文档变化带上历史变化的种类与实际应用的操作；视图变化指当前页面、带区变体或选择变了。 |
| `PrintEditorOptions` | 接口 |  |
| `PrintSelection` | 接口 | 选择：都在当前页面模板的正文与当前显示的页眉页脚变体里；tablePart 只在表格编辑态下出现。 |
| `PrintSelectMode` | 类型 | 选择方式：替换、追加或切换。 |
| `PrintTablePart` | 类型 | 表格编辑态下选中的部位。 |

### extensions

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `createPrintDesignerModel` | 函数 | 合出设计器用的模型；任何一处重名（含设置分区与设计器自己的 print、内建的 general 重名，引导步骤 id 重名或用了 shell. 前缀，物料来源 id 重名，菜单栏的菜单 id 重名，扩展的命令占了 panel:&lt;区名&gt; 或 insert:&lt;元素类型&gt;）都抛 DesignerExtensionError，物料项给了别处登记的元素类型时抛 TypeError。 |
| `PRINT_DESIGNER_EXTENSION_ID` | 常量 | 设计器自带的扩展的 id：内置命令，以及表格列与表尾行的条目、页码格式、四边边框与值格式的编辑器。 |
| `PRINT_DESIGNER_HELP_URL` | 常量 | 内置命令 help 打开的帮助页：打印文档站的设计器一页。 |
| `PRINT_DESIGNER_PANELS` | 常量 | 设计器的面板 id：宿主写 defaultLayout、settingsPolicy（layout.panels.&lt;面板 id&gt;）时用。 |
| `PRINT_MENUBAR_MENUS` | 常量 | 打印自己在菜单栏上的两张菜单的 id：插入、页面；宿主写 commandLayout 的 menubar:&lt;菜单 id&gt; 时用。 |
| `PRINT_PAGE_STRIP_LAYOUT` | 常量 | 画布右侧翻页条上的命令，排列固定：上一页、页码、下一页，新增、复制、删除页面。 |
| `PRINT_TOOLBAR_LAYOUT` | 常量 | 工具栏的缺省排列；commandLayout 没写 toolbar 时用它，再把 placement 含 toolbar 的扩展命令追加成一组。 |
| `PrintDesignerCommand` | 类型 | 设计器的命令：工具栏按钮、右键菜单项与快捷键共用。 |
| `PrintDesignerContext` | 接口 | 扩展装上时拿到的上下文。 |
| `PrintDesignerExtension` | 接口 | 打印设计器层的扩展：运行时层的全部字段（元素种类、渲染、编辑方式与规则），加上属性编辑器、命令、面板、设置分区、导入器、物料项、物料来源、菜单栏的菜单与 setup。 |
| `PrintDesignerImporter` | 类型 | 导入器：把粘贴或拖放进来的外部内容换成一组元素；返回 undefined 即不放任何元素。 |
| `PrintDesignerModel` | 接口 | 一组设计器扩展合出的东西：交给 core 函数与预览的列表、运行时的模型、属性编辑器表、命令表、导入器、物料项与物料来源。 |
| `PrintImportFragment` | 接口 | 导入的结果：一组元素，整体挪到落点（粘贴时为视口中央）后按粘贴的规则放进当前页面模板。 |
| `printInsertCommandId` | 函数 | 插入一种元素的命令 id：insert:&lt;元素类型&gt;。 |
| `printMenubarLayout` | 函数 | 菜单栏的缺省排列：在 designer-shell 四张菜单的缺省排列上，文件菜单的设置之前多出导入字段、打印两组，视图菜单的拖动之后多出网格与吸附一组；插入菜单按物料分组（elements 的 groupByCategory）各成一组列出插入元素的命令，最后一组是页眉、页脚的变体；页面菜单是纸张、方向与页面设置，上一页、下一页，新增、复制、删除页面，上移、下移页面。 |
| `printMenuLayout` | 函数 | 右键菜单的缺省排列；选中的是一张表格时，元素菜单最前面加「编辑表格」。 |
| `PrintMenuSubject` | 类型 | 右键菜单落在哪类对象上：画布空白处、元素，或表格编辑态里的表格部位。 |
| `PrintPaletteDrop` | 接口 | 物料来源的条目拖到画布上放下的落点：纸张坐标（mm，以纸张左上角为原点），以及这一点落在页眉、正文还是页脚。 |
| `PrintPaletteEntry` | 接口 | 物料面板里的一项：扩展元素的名称与图标。 |
| `printSelectionLayout` | 函数 | 选中工具条（命令落点 selection:&lt;主体&gt;）的缺省排列：文字类元素多出字号、粗体、斜体、下划线、删除线与左中右对齐；多选多出对齐与分布；都有层级、创建副本、复制与删除。 |
| `PrintSelectionSubject` | 类型 | 选中工具条落在哪类选中上：都是文字类元素（文本、长文本、富文本、页码）、单个别的元素，或几个元素里有别的种类。 |

### print-designer

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `definePrintDesigner` | 函数 | 注册 &lt;xh-print-designer&gt;；重复调用不报错。 |
| `PRINT_DESIGNER_TAG` | 常量 | 设计器的标签名。 |
| `PrintDesignerEventMap` | 接口 | 设计器派发的事件；x / y 为浏览器视口坐标。 |
| `PrintDesignerMode` | 类型 | 设计态或预览态。 |
| `PrintSchemaChangeKind` | 类型 | schema-change 的种类：执行操作、撤销、重做，或宿主装载了新模板。 |
| `XhPrintDesigner` | 类 |  |

### settings

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `PRINT_CLIENT_DOWNLOAD_URL` | 常量 | 「下载客户端」链接的缺省地址：打印文档站的客户端一页。 |
| `PRINT_CLIENT_SETTINGS_SECTION` | 常量 | 设计器「本地客户端」分区的 id，扩展同样不能再用；只在宿主给了 printClient 时出现。 |
| `PRINT_CLIENT_STATUS_CONTROL` | 常量 | 「本地客户端」分区里连接状态那一条的编辑方式种类：设计器自己铺状态、「测试连接」钮与下载链接，这一条不存值。 |
| `PRINT_SETTING_KEYS` | 常量 | 「打印」分区各条目的键，即 settings 里的键（分区 id.条目 id）。 |
| `PRINT_SETTINGS_SECTION` | 常量 | 设计器「打印」分区的 id，扩展不能再用。 |
| `printClientSettingsSection` | 函数 | 「本地客户端」分区：一条连接状态，按 PRINT_CLIENT_STATUS_CONTROL 铺。 |
| `PrintClientSettingsSectionOptions` | 接口 | printClientSettingsSection 的选项。 |
| `PrintClientStatusControl` | 接口 | 连接状态那一条的编辑方式：带着「下载客户端」链接的地址。 |
| `printSettingsSection` | 函数 | 「打印」分区：打印方式缺省经本地客户端；网格间距缺省 1 mm，吸附对齐、边距线与标尺缺省打开，网格缺省不显示。 |
| `PrintSettingsSectionOptions` | 接口 | printSettingsSection 的选项。 |
| `PrintVia` | 类型 | 打印方式：经本地打印客户端，或浏览器的打印对话框。 |

### version

| 名称 | 种类 | 说明 |
| --- | --- | --- |
| `PRINT_VERSION` | 常量 | @xihan-print/designer 的版本号。 |

---

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

# 元素

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

内置元素按物料面板的分组列出。属性路径相对元素，嵌套属性用点连接；「名称」是属性面板里的中文名，「新建时」是在设计器里新建元素时的取值，过长的值以 … 代替，详见各元素的类型。

每个元素还有共有字段 `id`、`type`、`name`、`x`、`y`、`width`、`height`、`locked`、`previewOnly`、`meta`，见 [ElementBase](./schema#elementbase)。坐标相对纸张左上角，长度单位为 mm，字号与字间距单位为 pt。

## 文字

### 文本 `text` {#text}

固定尺寸，可放在页眉、正文与页脚 · 最小 1 × 1 mm · 新建时 60 × 8 mm · 类型 [TextElement](./schema#textelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `60` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `8` |
| `rotation` | 旋转 | 数值（度），≥ -360，≤ 360 | 是 | `0` |
| `content` | 内容 | [文本内容](./schema#textcontent) | 是 | `{"kind":"static","text":""}` |
| `style.fontFamily` | 字体 | 文本 | 可省 | — |
| `style.fontSize` | 字号 | 数值（pt），> 0，≤ 500 | 是 | `10.5` |
| `style.bold` | 粗体 | 布尔 | 是 | `false` |
| `style.italic` | 斜体 | 布尔 | 是 | `false` |
| `style.underline` | 下划线 | 布尔 | 是 | `false` |
| `style.lineThrough` | 删除线 | 布尔 | 是 | `false` |
| `style.color` | 文字颜色 | [颜色](./schema#color) | 是 | `"#000000"` |
| `style.align` | 水平对齐 | `left` 左、`center` 居中、`right` 右、`justify` 两端对齐 | 是 | `"left"` |
| `style.verticalAlign` | 垂直对齐 | `top` 上、`middle` 居中、`bottom` 下 | 是 | `"middle"` |
| `style.lineHeight` | 行高 | 数值（倍），> 0，≤ 10 | 是 | `1.2` |
| `style.letterSpacing` | 字间距 | 数值（pt），≥ -10，≤ 100 | 是 | `0` |
| `wrap` | 自动换行 | 布尔 | 是 | `false` |
| `overflow` | 放不下时 | `clip` 裁掉、`shrink` 缩小字号、`visible` 照常显示 | 是 | `"clip"` |
| `box.background` | 背景 | [颜色](./schema#color) | 可省 | — |
| `box.border` | 边框 | [四边边框](./schema#bordersides) | 可省 | — |
| `box.padding` | 内边距 | [四边距离](./schema#edges)，每边是数值（mm），≥ 0 | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

### 长文本 `longText` {#longtext}

随内容纵向延展、可跨页续排，只能放在正文区 · 最小 5 × 3 mm · 新建时 120 × 20 mm · 类型 [LongTextElement](./schema#longtextelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `120` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `20` |
| `content` | 内容 | [文本内容](./schema#textcontent) | 是 | `{"kind":"static","text":""}` |
| `style.fontFamily` | 字体 | 文本 | 可省 | — |
| `style.fontSize` | 字号 | 数值（pt），> 0，≤ 500 | 是 | `10.5` |
| `style.bold` | 粗体 | 布尔 | 是 | `false` |
| `style.italic` | 斜体 | 布尔 | 是 | `false` |
| `style.underline` | 下划线 | 布尔 | 是 | `false` |
| `style.lineThrough` | 删除线 | 布尔 | 是 | `false` |
| `style.color` | 文字颜色 | [颜色](./schema#color) | 是 | `"#000000"` |
| `style.align` | 水平对齐 | `left` 左、`center` 居中、`right` 右、`justify` 两端对齐 | 是 | `"left"` |
| `style.verticalAlign` | 垂直对齐 | `top` 上、`middle` 居中、`bottom` 下 | 是 | `"top"` |
| `style.lineHeight` | 行高 | 数值（倍），> 0，≤ 10 | 是 | `1.5` |
| `style.letterSpacing` | 字间距 | 数值（pt），≥ -10，≤ 100 | 是 | `0` |
| `box.background` | 背景 | [颜色](./schema#color) | 可省 | — |
| `box.border` | 边框 | [四边边框](./schema#bordersides) | 可省 | — |
| `box.padding` | 内边距 | [四边距离](./schema#edges)，每边是数值（mm），≥ 0 | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

### 富文本 `richText` {#richtext}

随内容纵向延展、可跨页续排，只能放在正文区 · 最小 5 × 3 mm · 新建时 120 × 20 mm · 类型 [RichTextElement](./schema#richtextelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `120` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `20` |
| `content` | 内容 | [富文本内容](./schema#richtextcontent) | 是 | … |
| `style.fontFamily` | 字体 | 文本 | 可省 | — |
| `style.fontSize` | 字号 | 数值（pt），> 0，≤ 500 | 是 | `10.5` |
| `style.bold` | 粗体 | 布尔 | 是 | `false` |
| `style.italic` | 斜体 | 布尔 | 是 | `false` |
| `style.underline` | 下划线 | 布尔 | 是 | `false` |
| `style.lineThrough` | 删除线 | 布尔 | 是 | `false` |
| `style.color` | 文字颜色 | [颜色](./schema#color) | 是 | `"#000000"` |
| `style.align` | 水平对齐 | `left` 左、`center` 居中、`right` 右、`justify` 两端对齐 | 是 | `"left"` |
| `style.verticalAlign` | 垂直对齐 | `top` 上、`middle` 居中、`bottom` 下 | 是 | `"top"` |
| `style.lineHeight` | 行高 | 数值（倍），> 0，≤ 10 | 是 | `1.5` |
| `style.letterSpacing` | 字间距 | 数值（pt），≥ -10，≤ 100 | 是 | `0` |
| `box.background` | 背景 | [颜色](./schema#color) | 可省 | — |
| `box.border` | 边框 | [四边边框](./schema#bordersides) | 可省 | — |
| `box.padding` | 内边距 | [四边距离](./schema#edges)，每边是数值（mm），≥ 0 | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

### 页码 `pageNumber` {#pagenumber}

固定尺寸，可放在页眉、正文与页脚 · 最小 1 × 1 mm · 新建时 30 × 6 mm · 类型 [PageNumberElement](./schema#pagenumberelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `30` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `6` |
| `format` | 格式 | 页码模板，可用 `{{$page}}` 与 `{{$pages}}` | 是 | `"{{$page}}/{{$pages}}"` |
| `numeral` | 数字写法 | `roman-upper` 罗马数字（I、II）、`roman-lower` 罗马数字（i、ii）、`cn-lower` 中文小写（一、二）、`cn-upper` 中文大写（壹、贰） | 可省 | — |
| `style.fontFamily` | 字体 | 文本 | 可省 | — |
| `style.fontSize` | 字号 | 数值（pt），> 0，≤ 500 | 是 | `9` |
| `style.bold` | 粗体 | 布尔 | 是 | `false` |
| `style.italic` | 斜体 | 布尔 | 是 | `false` |
| `style.underline` | 下划线 | 布尔 | 是 | `false` |
| `style.lineThrough` | 删除线 | 布尔 | 是 | `false` |
| `style.color` | 文字颜色 | [颜色](./schema#color) | 是 | `"#000000"` |
| `style.align` | 水平对齐 | `left` 左、`center` 居中、`right` 右、`justify` 两端对齐 | 是 | `"center"` |
| `style.verticalAlign` | 垂直对齐 | `top` 上、`middle` 居中、`bottom` 下 | 是 | `"middle"` |
| `style.lineHeight` | 行高 | 数值（倍），> 0，≤ 10 | 是 | `1.2` |
| `style.letterSpacing` | 字间距 | 数值（pt），≥ -10，≤ 100 | 是 | `0` |
| `box.background` | 背景 | [颜色](./schema#color) | 可省 | — |
| `box.border` | 边框 | [四边边框](./schema#bordersides) | 可省 | — |
| `box.padding` | 内边距 | [四边距离](./schema#edges)，每边是数值（mm），≥ 0 | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

## 图片

### 图片 `image` {#image}

固定尺寸，可放在页眉、正文与页脚 · 最小 1 × 1 mm · 新建时 40 × 30 mm · 类型 [ImageElement](./schema#imageelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `40` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `30` |
| `rotation` | 旋转 | 数值（度），≥ -360，≤ 360 | 是 | `0` |
| `source` | 图片来源 | [图片来源](./schema#imagesource) | 是 | `{"kind":"static","url":""}` |
| `fit` | 填充方式 | `contain` 完整显示、`cover` 铺满裁切、`fill` 拉伸铺满、`none` 原始大小 | 是 | `"contain"` |
| `box.background` | 背景 | [颜色](./schema#color) | 可省 | — |
| `box.border` | 边框 | [四边边框](./schema#bordersides) | 可省 | — |
| `box.padding` | 内边距 | [四边距离](./schema#edges)，每边是数值（mm），≥ 0 | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

## 数据

### 表格 `table` {#table}

随内容纵向延展、可跨页续排，只能放在正文区 · 最小 10 × 5 mm · 新建时 180 × 22 mm · 类型 [TableElement](./schema#tableelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `180` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `22` |
| `dataField` | 数据字段 | 指向数组的字段路径 | 是 | `""` |
| `columns` | 列 | [列](#table-column)的数组 | 是 | … |
| `header.visible` | 显示表头 | 布尔 | 是 | `true` |
| `header.repeat` | 每页重复表头 | 布尔；「显示表头」打开时显示 | 是 | `true` |
| `header.height` | 表头行高 | 数值（mm），> 0；「显示表头」打开时显示 | 是 | `8` |
| `header.style` | 表头样式 | [单元格样式](./schema#cellstyle)；「显示表头」打开时显示 | 是 | … |
| `body.rowHeight` | 行高 | 数值（mm），> 0 | 是 | `7` |
| `body.rowHeightMode` | 行高方式 | `fixed` 固定、`minimum` 至少 | 是 | `"fixed"` |
| `body.style` | 表体样式 | [单元格样式](./schema#cellstyle) | 是 | … |
| `footerRows` | 表尾行 | [表尾行](#table-footer-row)的数组 | 是 | `[]` |
| `maxRowsPerPage` | 每页最多行数 | 整数（个），≥ 1 | 可省 | — |
| `fillEmptyRows` | 用空行补齐 | 布尔 | 是 | `false` |
| `border.stroke` | 边框线 | [描边](./schema#stroke) | 是 | `{"width":0.2,"style":"solid","color":"#000000"}` |
| `border.outer` | 外框 | 布尔 | 是 | `true` |
| `border.horizontal` | 横线 | 布尔 | 是 | `true` |
| `border.vertical` | 竖线 | 布尔 | 是 | `true` |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

## 图形

### 直线 `line` {#line}

固定尺寸，可放在页眉、正文与页脚 · 最小 0 × 0 mm · 新建时 80 × 0 mm · 类型 [LineElement](./schema#lineelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `80` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `0` |
| `direction` | 方向 | `horizontal` 水平、`vertical` 竖直、`diagonalDown` 左上到右下、`diagonalUp` 左下到右上 | 是 | `"horizontal"` |
| `stroke` | 边线 | [描边](./schema#stroke) | 是 | `{"width":0.3,"style":"solid","color":"#000000"}` |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

### 矩形 `rect` {#rect}

固定尺寸，可放在页眉、正文与页脚 · 最小 1 × 1 mm · 新建时 40 × 20 mm · 类型 [RectElement](./schema#rectelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `40` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `20` |
| `rotation` | 旋转 | 数值（度），≥ -360，≤ 360 | 是 | `0` |
| `stroke` | 边线 | [描边](./schema#stroke) | 可省 | `{"width":0.3,"style":"solid","color":"#000000"}` |
| `fill` | 填充 | [颜色](./schema#color) | 可省 | — |
| `radius` | 圆角 | 数值（mm），≥ 0 | 是 | `0` |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

### 椭圆 `ellipse` {#ellipse}

固定尺寸，可放在页眉、正文与页脚 · 最小 1 × 1 mm · 新建时 30 × 20 mm · 类型 [EllipseElement](./schema#ellipseelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `30` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `20` |
| `rotation` | 旋转 | 数值（度），≥ -360，≤ 360 | 是 | `0` |
| `stroke` | 边线 | [描边](./schema#stroke) | 可省 | `{"width":0.3,"style":"solid","color":"#000000"}` |
| `fill` | 填充 | [颜色](./schema#color) | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

## 条码

### 条码 `barCode` {#barcode}

固定尺寸，可放在页眉、正文与页脚 · 最小 5 × 3 mm · 新建时 50 × 15 mm · 类型 [BarCodeElement](./schema#barcodeelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `50` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `15` |
| `rotation` | 旋转 | 数值（度），≥ -360，≤ 360 | 是 | `0` |
| `format` | 码制 | `code128`、`ean13`、`ean8`、`upca`、`upce`、`itf14`、`code39` | 是 | `"code128"` |
| `content` | 内容 | [文本内容](./schema#textcontent) | 是 | `{"kind":"static","text":"1234567890"}` |
| `showText` | 显示文字 | 布尔 | 是 | `true` |
| `textStyle.fontFamily` | 文字字体 | 文本；「显示文字」打开时显示 | 可省 | — |
| `textStyle.fontSize` | 文字字号 | 数值（pt），> 0，≤ 100；「显示文字」打开时显示 | 是 | `9` |
| `color` | 颜色 | [颜色](./schema#color) | 是 | `"#000000"` |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

### 二维码 `matrixCode` {#matrixcode}

固定尺寸，可放在页眉、正文与页脚 · 最小 5 × 5 mm · 新建时 25 × 25 mm · 类型 [MatrixCodeElement](./schema#matrixcodeelement)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `x` | X | 数值（mm） | 是 | — |
| `y` | Y | 数值（mm） | 是 | — |
| `width` | 宽 | 数值（mm），≥ 0 | 是 | `25` |
| `height` | 高 | 数值（mm），≥ 0 | 是 | `25` |
| `rotation` | 旋转 | 数值（度），≥ -360，≤ 360 | 是 | `0` |
| `content` | 内容 | [文本内容](./schema#textcontent) | 是 | `{"kind":"static","text":"1234567890"}` |
| `format` | 码制 | `qr`、`data-matrix`、`pdf417`、`aztec` | 是 | `"qr"` |
| `level` | 纠错级别 | 纠错级别，见 [MatrixCodeElement](./schema#matrixcodeelement) | 可省 | `"M"` |
| `quietZone` | 静区 | 整数（个），≥ 0，≤ 20 | 是 | `1` |
| `color` | 颜色 | [颜色](./schema#color) | 是 | `"#000000"` |
| `background` | 背景 | [颜色](./schema#color) | 可省 | — |
| `name` | 名称 | 文本 | 可省 | — |
| `locked` | 锁定 | 布尔 | 可省 | — |
| `previewOnly` | 只在预览中显示 | 布尔 | 可省 | — |

## 页面设置 {#page}

没有选中元素时，属性面板编辑当前页面模板。属性路径相对页面模板，见 [PrintPage](./schema#printpage)。

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `name` | 名称 | 文本 | 可省 | — |
| `paper` | 纸张 | [纸张](./schema#paperspec) | 是 | — |
| `orientation` | 方向 | `portrait` 纵向、`landscape` 横向 | 是 | — |
| `margins` | 页边距 | [四边距离](./schema#edges)，每边是数值（mm），≥ 0 | 是 | — |
| `header.default.height` | 页眉高度 | 数值（mm），≥ 0 | 是 | — |
| `header.first.height` | 首页页眉高度 | 数值（mm），≥ 0；设置了 `header.first` 时显示 | 可省 | — |
| `header.last.height` | 末页页眉高度 | 数值（mm），≥ 0；设置了 `header.last` 时显示 | 可省 | — |
| `header.odd.height` | 奇数页页眉高度 | 数值（mm），≥ 0；设置了 `header.odd` 时显示 | 可省 | — |
| `header.even.height` | 偶数页页眉高度 | 数值（mm），≥ 0；设置了 `header.even` 时显示 | 可省 | — |
| `header.singleSheet` | 只有一页时的页眉 | `first` 首页、`last` 末页 | 是 | — |
| `footer.default.height` | 页脚高度 | 数值（mm），≥ 0 | 是 | — |
| `footer.first.height` | 首页页脚高度 | 数值（mm），≥ 0；设置了 `footer.first` 时显示 | 可省 | — |
| `footer.last.height` | 末页页脚高度 | 数值（mm），≥ 0；设置了 `footer.last` 时显示 | 可省 | — |
| `footer.odd.height` | 奇数页页脚高度 | 数值（mm），≥ 0；设置了 `footer.odd` 时显示 | 可省 | — |
| `footer.even.height` | 偶数页页脚高度 | 数值（mm），≥ 0；设置了 `footer.even` 时显示 | 可省 | — |
| `footer.singleSheet` | 只有一页时的页脚 | `first` 首页、`last` 末页 | 是 | — |
| `numbering.continuous` | 接续上一页面模板的页码 | 布尔 | 是 | — |
| `numbering.start` | 起始页码 | 整数（个），≥ 0 | 是 | — |
| `watermark` | 水印 | [水印](./schema#watermark) | 可省 | — |

纸张预设：

| 预设名 | 宽 × 高（mm，纵向） |
| --- | --- |
| `A3` | 297 × 420 |
| `A4` | 210 × 297 |
| `A5` | 148 × 210 |
| `A6` | 105 × 148 |
| `B4` | 250 × 353 |
| `B5` | 176 × 250 |
| `Letter` | 215.9 × 279.4 |
| `Legal` | 215.9 × 355.6 |

## 表格部位 {#table-parts}

双击表格进入表格编辑态后，可以分别选中列、表头、表体、表尾行与表尾单元格编辑。属性路径相对该部位。

### 列 {#table-column}

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `title` | 标题 | 文本 | 是 | `""` |
| `content` | 内容 | [单元格内容](./schema#tablecellcontent) | 是 | `{"kind":"field","field":""}` |
| `cellType` | 单元格类型 | `text` 文字、`image` 图片、`barCode` 条码、`matrixCode` 二维码 | 是 | `"text"` |
| `barCodeFormat` | 条码码制 | `code128`、`ean13`、`ean8`、`upca`、`upce`、`itf14`、`code39`；「单元格类型」为 `barCode` 时显示 | 可省 | — |
| `width` | 列宽 | 数值（mm），> 0 | 是 | `60` |
| `align` | 对齐 | `left` 左、`center` 居中、`right` 右 | 是 | `"left"` |

### 表头 {#table-header}

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `visible` | 显示 | 布尔 | 是 | `true` |
| `repeat` | 每页重复 | 布尔；「显示」打开时显示 | 是 | `true` |
| `height` | 行高 | 数值（mm），> 0；「显示」打开时显示 | 是 | `8` |
| `style` | 样式 | [单元格样式](./schema#cellstyle)；「显示」打开时显示 | 是 | … |

### 表体 {#table-body}

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `rowHeight` | 行高 | 数值（mm），> 0 | 是 | `7` |
| `rowHeightMode` | 行高方式 | `fixed` 固定、`minimum` 至少 | 是 | `"fixed"` |
| `style` | 样式 | [单元格样式](./schema#cellstyle) | 是 | … |

### 表尾行 {#table-footer-row}

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `placement` | 出现在 | `everyPage` 每一页、`lastPage` 只在最后一页 | 是 | — |
| `height` | 行高 | 数值（mm），> 0 | 是 | — |
| `style` | 样式 | [单元格样式](./schema#cellstyle) | 是 | — |

### 表尾单元格 {#table-footer-cell}

| 属性 | 名称 | 取值 | 必有 | 新建时 |
| --- | --- | --- | --- | --- |
| `content` | 内容 | [表尾单元格内容](./schema#tablefootercellcontent) | 是 | — |
| `colSpan` | 跨列数 | 整数（个），≥ 1 | 是 | — |
| `align` | 对齐 | `left` 左、`center` 居中、`right` 右 | 可省 | — |

---

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

# 问题码与诊断

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

校验问题由 `validateDocument` 与设计器的问题列表给出，分页诊断随分页结果一起给出。问题都不带文案，只有问题码、严重程度、路径与参数；下表的说明来自中文语言包 `printZhCN`，其中的 {名} 是参数，实际文案只含问题给出的参数。

## 校验问题

有错误级问题的模板不能分页：`paginate` 抛出 `PrintLayoutError`（码为 `document.invalid`），预览元素派发 `pagination-error`。警告不影响分页。

| 问题码 | 严重程度 | 说明 | 参数 |
| --- | --- | --- | --- |
| `required` | 错误 | 缺少必填项 | — |
| `invalid-type` | 错误 | 类型不对 | — |
| `invalid-value` | 错误 | 取值无效 | — |
| `out-of-range` | 错误 | 应不小于 {min}、大于 {exclusiveMin}、不大于 {max} | `min`、`exclusiveMin`、`max` |
| `not-integer` | 错误 | 应为整数 | — |
| `invalid-option` | 错误 | 不是可选的值 | — |
| `invalid-color` | 错误 | 不是有效的颜色 | — |
| `empty` | 错误 | 不能为空 | — |
| `unknown-key` | 警告 | 未知的属性 {key} | `key` |
| `unknown-control` | 错误 | 未知的编辑方式 | — |
| `duplicate-key` | 错误 | 键 {key} 重复 | `key` |
| `duplicate-id` | 错误 | 标识 {id} 重复 | `id` |
| `duplicate-value` | 错误 | 选项的值重复 | — |
| `json.circular` | 错误 | 数据有循环引用 | — |
| `schema.unsupportedVersion` | 错误 | 不支持模板版本 {version}（应为 {supported}） | `version`、`supported` |
| `field.empty` | 警告 | 没有绑定字段 | — |
| `field.invalidPath` | 错误 | 字段路径 {field} 写法不对 | `field` |
| `template.unclosedPlaceholder` | 错误 | 模板里有没闭合的 &#123;&#123; | — |
| `template.emptyPlaceholder` | 错误 | 模板里有空的 &#123;&#123;}} | — |
| `template.invalidPath` | 错误 | 模板里的字段路径写法不对 | — |
| `expression.invalid` | 错误 | 表达式有误 | — |
| `format.duplicateMapValue` | 警告 | 值映射里 {value} 重复 | `value` |
| `format.invalidOption` | 错误 | 格式选项无效 | — |
| `format.conflict` | 错误 | 格式选项相互冲突 | — |
| `document.noPages` | 错误 | 模板里没有页面 | — |
| `page.presetMismatch` | 警告 | 纸张尺寸与 {preset} 不符 | `preset` |
| `page.noContentArea` | 错误 | 页边距占满了纸张 | — |
| `page.bandsOverflow` | 错误 | 页眉页脚比版心还高 | — |
| `watermark.emptyText` | 警告 | 水印文字为空 | — |
| `element.unknownType` | 错误 | 未知的元素种类 {type} | `type` |
| `element.tooSmall` | 错误 | 小于最小尺寸 … × … mm | `minWidth`、`minHeight` |
| `element.outsidePaper` | 警告 | 超出纸张 | — |
| `element.outsideBand` | 警告 | 超出{region}区 | `region` |
| `element.flowInBand` | 错误 | 跨页元素只能放在正文区 | — |
| `element.flowOutsideBody` | 警告 | 跨页元素超出正文区 | — |
| `line.zeroLength` | 错误 | 直线长度为 0 | — |
| `shape.invisible` | 警告 | 图形既没有边线也没有填充 | — |
| `image.emptySource` | 警告 | 图片地址为空 | — |
| `image.unsafeSource` | 错误 | 图片地址不允许使用 | — |
| `table.noColumns` | 警告 | 表格没有列 | — |
| `table.duplicateColumnId` | 错误 | 列标识 {id} 重复 | `id` |
| `table.duplicateRowId` | 错误 | 表尾行标识 {id} 重复 | `id` |
| `table.columnWidthMismatch` | 警告 | 列宽合计 … mm，与表格宽度 … mm 不一致 | `columnsWidth`、`width` |
| `table.unknownColumn` | 错误 | 表尾单元格指向不存在的列 {columnId} | `columnId` |
| `table.cellSpanOverflow` | 错误 | 跨 {colSpan} 列，右侧只剩 {available} 列 | `colSpan`、`available` |
| `table.cellOverlap` | 错误 | 表尾单元格与其它单元格重叠 | — |
| `table.aggregateFieldMissing` | 错误 | 汇总 {fn} 缺少字段 | `fn` |
| `table.rowExceedsBody` | 警告 | 表头加一行需要 … mm，正文区只有 … mm | `required`、`available` |
| `barCode.invalidValue` | 错误 | 内容无法按 {format} 编码 | `format` |
| `matrixCode.invalidValue` | 错误 | 内容无法按 {format} 编码 | `format` |
| `matrixCode.invalidLevel` | 错误 | 纠错级别 {level} 不适用于 {format} | `level`、`format` |
| `matrixCode.levelIgnored` | 警告 | {format} 没有纠错级别，设置的级别不起作用 | `format` |
| `matrixCode.notSquare` | 警告 | 二维码宽高不等 | — |
| `pageNumber.noToken` | 警告 | 页码格式里没有 &#123;&#123;$page}} 或 &#123;&#123;$pages}} | — |
| `pageNumber.unknownToken` | 警告 | 页码格式里有未知的变量 {token} | `token` |
| `richText.invalidDocument` | 错误 | 富文本写法不对 | `code` |
| `richText.empty` | 警告 | 富文本没有内容 | — |

## 分页诊断

分页诊断不打断分页：错误表示按模板该画的内容没有画出或输出页被截断，警告表示内容画出了但与设计有出入。同一位置的同一问题只报告一次。

| 问题码 | 严重程度 | 说明 | 参数 |
| --- | --- | --- | --- |
| `data.notArray` | 警告 | 字段 {field} 不是数组 | `field` |
| `data.notScalar` | 警告 | 字段 {field} 不是单个值 | `field` |
| `format.unavailable` | 警告 | 没有提供格式化器 | — |
| `format.failed` | 警告 | 格式化失败 | — |
| `expression.unavailable` | 警告 | 没有提供表达式引擎 | — |
| `expression.failed` | 错误 | 表达式求值失败 | — |
| `image.unsafeSource` | 错误 | 图片地址不允许使用 | — |
| `barCode.invalidValue` | 错误 | 内容无法按 {format} 编码 | `format` |
| `matrixCode.invalidValue` | 错误 | 内容无法按 {format} 编码 | `format` |
| `text.overflow` | 警告 | 文字缩到 {fontSize} pt 仍超出元素框 | `fontSize` |
| `richText.droppedContent` | 警告 | 字段 {field} 的 HTML 里去掉了 {names} | `field`、`names` |
| `richText.invalidData` | 错误 | 字段 {field} 不是合规的富文本文档 | `field` |
| `table.rowOverflow` | 警告 | 第 … 行在一页里放不下 | `dataIndex` |
| `element.overflow` | 警告 | 内容超出元素框 | — |
| `layout.sheetLimit` | 错误 | 输出页数超过上限 {limit} | `limit` |

## 分页与打印失败

分页无法进行的原因：文档有 error 级校验问题、选项不合法、测量器或格式化器返回了不合法的结果。

`PrintLayoutError` 的码：`document.invalid`、`option.invalid`、`measurer.invalidResult`、`formatter.invalidResult`。

运行时无法完成分页或打印的原因：拿不到文字度量器、没有给模板。

`PrintRuntimeError` 的码：`measurer.unavailable`、`schema.missing`。

---

来源：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 零件。 |

---

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

# 模板类型

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

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

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

## 文档与页面

### PrintSchemaVersion {#printschemaversion}

模板 schema 版本号类型。

类型：<code>typeof PRINT_SCHEMA_VERSION</code>

### PaperSpec {#paperspec}

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

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

### PageBand {#pageband}

页眉或页脚的一个带区。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `height` | <code>number</code> | 是 | 带区高度，单位 mm。 |
| `elements` | <code><a href="#printelement">PrintElement</a>[]</code> | 是 | 带区内的元素，坐标相对纸张左上角。 |

### PageBandSet {#pagebandset}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `default` | <code><a href="#pageband">PageBand</a></code> | 是 |  |
| `first` | <code><a href="#pageband">PageBand</a></code> | 可省 |  |
| `last` | <code><a href="#pageband">PageBand</a></code> | 可省 |  |
| `odd` | <code><a href="#pageband">PageBand</a></code> | 可省 |  |
| `even` | <code><a href="#pageband">PageBand</a></code> | 可省 |  |
| `singleSheet` | <code><a href="#singlesheetpreference">SingleSheetPreference</a></code> | 是 | 输出页既是首页又是末页且两种变体都存在时采用哪一个。 |

### PageNumbering {#pagenumbering}

页码编号规则。

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

### Watermark {#watermark}

平铺文字水印。

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

### PageGuides {#pageguides}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `x` | <code>number[]</code> | 是 | 竖线的横坐标。 |
| `y` | <code>number[]</code> | 是 | 横线的纵坐标。 |

### PrintPage {#printpage}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | <code>string</code> | 是 | 页面标识，在整份文档内唯一。 |
| `name` | <code>string</code> | 可省 |  |
| `paper` | <code><a href="#paperspec">PaperSpec</a></code> | 是 |  |
| `orientation` | <code><a href="#pageorientation">PageOrientation</a></code> | 是 |  |
| `margins` | <code><a href="#edges">Edges</a></code> | 是 | 页边距，单位 mm。 |
| `header` | <code><a href="#pagebandset">PageBandSet</a></code> | 是 |  |
| `footer` | <code><a href="#pagebandset">PageBandSet</a></code> | 是 |  |
| `elements` | <code><a href="#printelement">PrintElement</a>[]</code> | 是 | 正文元素，坐标相对纸张左上角。 |
| `numbering` | <code><a href="#pagenumbering">PageNumbering</a></code> | 是 |  |
| `watermark` | <code><a href="#watermark">Watermark</a></code> | 可省 |  |
| `guides` | <code><a href="#pageguides">PageGuides</a></code> | 可省 |  |
| `meta` | <code>JsonObject</code> | 可省 |  |
| `extensions` | <code>JsonObject</code> | 可省 | 扩展自己的数据，键是扩展 id。 |

### PrintDocument {#printdocument}

打印模板文档。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schemaVersion` | <code><a href="#printschemaversion">PrintSchemaVersion</a></code> | 是 |  |
| `name` | <code>string</code> | 可省 |  |
| `pages` | <code><a href="#printpage">PrintPage</a>[]</code> | 是 |  |
| `meta` | <code>JsonObject</code> | 可省 |  |
| `extensions` | <code>JsonObject</code> | 可省 | 扩展自己的数据，键是扩展 id。 |

## 元素

### ElementBase {#elementbase}

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

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

### TextElement {#textelement}

固定尺寸的文本。

继承 <code><a href="#elementbase">ElementBase</a>&lt;'text'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | <code><a href="#textcontent">TextContent</a></code> | 是 |  |
| `style` | <code><a href="#textstyle">TextStyle</a></code> | 是 |  |
| `wrap` | <code>boolean</code> | 是 | 是否自动换行。 |
| `overflow` | <code><a href="#textoverflow">TextOverflow</a></code> | 是 |  |
| `rotation` | <code>number</code> | 是 | 绕中心顺时针旋转的角度。 |
| `box` | <code><a href="#boxstyle">BoxStyle</a></code> | 可省 |  |

### LongTextElement {#longtextelement}

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

继承 <code><a href="#elementbase">ElementBase</a>&lt;'longText'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | <code><a href="#textcontent">TextContent</a></code> | 是 |  |
| `style` | <code><a href="#textstyle">TextStyle</a></code> | 是 |  |
| `box` | <code><a href="#boxstyle">BoxStyle</a></code> | 可省 |  |

### RichTextContent {#richtextcontent}

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

类型：<code>&#124; { kind: 'static', document: RichTextDocument } &#124; { kind: 'field', field: string, source: <a href="#richtextsource">RichTextSource</a> }</code>

### RichTextElement {#richtextelement}

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

继承 <code><a href="#elementbase">ElementBase</a>&lt;'richText'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | <code><a href="#richtextcontent">RichTextContent</a></code> | 是 |  |
| `style` | <code><a href="#textstyle">TextStyle</a></code> | 是 | 基准样式：块与行内的样式在它之上覆写。 |
| `box` | <code><a href="#boxstyle">BoxStyle</a></code> | 可省 |  |

### TableElement {#tableelement}

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

继承 <code><a href="#elementbase">ElementBase</a>&lt;'table'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dataField` | <code>string</code> | 是 | 数组数据的字段路径。 |
| `columns` | <code><a href="#tablecolumn">TableColumn</a>[]</code> | 是 |  |
| `header` | <code><a href="#tableheader">TableHeader</a></code> | 是 |  |
| `body` | <code><a href="#tablebody">TableBody</a></code> | 是 |  |
| `footerRows` | <code><a href="#tablefooterrow">TableFooterRow</a>[]</code> | 是 |  |
| `maxRowsPerPage` | <code>number</code> | 可省 | 每页最多显示的数据行数，缺省按可用高度排满。 |
| `fillEmptyRows` | <code>boolean</code> | 是 | 数据行不足时是否用空行补齐到每页最大行数或可用高度。 |
| `border` | <code><a href="#tableborder">TableBorder</a></code> | 是 |  |

### ImageElement {#imageelement}

图片。

继承 <code><a href="#elementbase">ElementBase</a>&lt;'image'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source` | <code><a href="#imagesource">ImageSource</a></code> | 是 |  |
| `fit` | <code><a href="#imagefit">ImageFit</a></code> | 是 |  |
| `rotation` | <code>number</code> | 是 |  |
| `box` | <code><a href="#boxstyle">BoxStyle</a></code> | 可省 |  |

### LineElement {#lineelement}

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

继承 <code><a href="#elementbase">ElementBase</a>&lt;'line'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `direction` | <code><a href="#linedirection">LineDirection</a></code> | 是 |  |
| `stroke` | <code><a href="#stroke">Stroke</a></code> | 是 |  |

### RectElement {#rectelement}

矩形。

继承 <code><a href="#elementbase">ElementBase</a>&lt;'rect'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stroke` | <code><a href="#stroke">Stroke</a></code> | 可省 | 边线，缺省不画边。 |
| `fill` | <code><a href="#color">Color</a></code> | 可省 | 填充色，缺省不填充。 |
| `radius` | <code>number</code> | 是 | 圆角半径，单位 mm。 |
| `rotation` | <code>number</code> | 是 |  |

### EllipseElement {#ellipseelement}

椭圆，内切于元素框。

继承 <code><a href="#elementbase">ElementBase</a>&lt;'ellipse'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stroke` | <code><a href="#stroke">Stroke</a></code> | 可省 |  |
| `fill` | <code><a href="#color">Color</a></code> | 可省 |  |
| `rotation` | <code>number</code> | 是 |  |

### BarCodeTextStyle {#barcodetextstyle}

条码下方文字的样式。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fontFamily` | <code>string</code> | 可省 |  |
| `fontSize` | <code>number</code> | 是 | 字号，单位 pt。 |

### BarCodeElement {#barcodeelement}

一维条码。

继承 <code><a href="#elementbase">ElementBase</a>&lt;'barCode'&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `format` | <code>BarCodeFormat</code> | 是 | 码制，取值见 @xihan-ui/headless 的 BAR_CODE_FORMATS。 |
| `content` | <code><a href="#textcontent">TextContent</a></code> | 是 |  |
| `showText` | <code>boolean</code> | 是 | 是否在条码下方显示编码文字。 |
| `textStyle` | <code><a href="#barcodetextstyle">BarCodeTextStyle</a></code> | 是 |  |
| `color` | <code><a href="#color">Color</a></code> | 是 |  |
| `rotation` | <code>number</code> | 是 |  |

### MatrixCodeElement {#matrixcodeelement}

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

继承 <code><a href="#elementbase">ElementBase</a>&lt;'matrixCode'&gt;</code> 的字段。

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

### PageNumberElement {#pagenumberelement}

页码。

继承 <code><a href="#elementbase">ElementBase</a>&lt;'pageNumber'&gt;</code> 的字段。

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

### ExtensionElement {#extensionelement}

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

继承 <code><a href="#elementbase">ElementBase</a>&lt;string&gt;</code> 的字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `` | <code>JsonValue &#124; undefined</code> | 是 |  |

### PrintElement {#printelement}

内置元素。

取其一：<code><a href="#textelement">TextElement</a></code>、<code><a href="#longtextelement">LongTextElement</a></code>、<code><a href="#richtextelement">RichTextElement</a></code>、<code><a href="#tableelement">TableElement</a></code>、<code><a href="#imageelement">ImageElement</a></code>、<code><a href="#lineelement">LineElement</a></code>、<code><a href="#rectelement">RectElement</a></code>、<code><a href="#ellipseelement">EllipseElement</a></code>、<code><a href="#barcodeelement">BarCodeElement</a></code>、<code><a href="#matrixcodeelement">MatrixCodeElement</a></code>、<code><a href="#pagenumberelement">PageNumberElement</a></code>。

### PrintElementType {#printelementtype}

内置元素类型。

类型：<code><a href="#printelement">PrintElement</a>['type']</code>

### PrintElementOf {#printelementof}

按类型取元素接口。

类型：<code>Extract&lt;<a href="#printelement">PrintElement</a>, { type: TType }&gt;</code>

## 表格

### CellStyle {#cellstyle}

单元格样式。

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

### TableFieldCellContent {#tablefieldcellcontent}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'field'</code> | 是 |  |
| `field` | <code>string</code> | 是 | 行对象内的字段路径。 |
| `format` | <code><a href="#valueformat">ValueFormat</a></code> | 可省 |  |
| `emptyText` | <code>string</code> | 可省 |  |

### TableTemplateCellContent {#tabletemplatecellcontent}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'template'</code> | 是 |  |
| `template` | <code>string</code> | 是 |  |

### TableRowNumberCellContent {#tablerownumbercellcontent}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'rowNumber'</code> | 是 |  |

### TableExpressionCellContent {#tableexpressioncellcontent}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'expression'</code> | 是 |  |
| `expression` | <code>string</code> | 是 | 受限表达式源码。 |
| `format` | <code><a href="#valueformat">ValueFormat</a></code> | 可省 | 计算结果的格式。 |

### TableCellContent {#tablecellcontent}

表体单元格内容来源。

取其一：<code><a href="#tablefieldcellcontent">TableFieldCellContent</a></code>、<code><a href="#tabletemplatecellcontent">TableTemplateCellContent</a></code>、<code><a href="#tablerownumbercellcontent">TableRowNumberCellContent</a></code>、<code><a href="#tableexpressioncellcontent">TableExpressionCellContent</a></code>。

### TableColumn {#tablecolumn}

表格列。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | <code>string</code> | 是 | 列标识，在所属表格内唯一。 |
| `title` | <code>string</code> | 是 | 表头文本。 |
| `width` | <code>number</code> | 是 | 列宽，单位 mm。 |
| `align` | <code><a href="#horizontalalign">HorizontalAlign</a></code> | 是 |  |
| `content` | <code><a href="#tablecellcontent">TableCellContent</a></code> | 是 |  |
| `cellType` | <code><a href="#tablecelltype">TableCellType</a></code> | 是 |  |
| `barCodeFormat` | <code>BarCodeFormat</code> | 可省 | 条码码制，`cellType` 为 barCode 时必填；matrixCode 单元格按 QR 编码。 |

### TableHeader {#tableheader}

表头。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `visible` | <code>boolean</code> | 是 |  |
| `repeat` | <code>boolean</code> | 是 | 表格跨页时是否在每一页重复表头。 |
| `height` | <code>number</code> | 是 | 表头行高，单位 mm。 |
| `style` | <code><a href="#cellstyle">CellStyle</a></code> | 是 |  |

### TableBody {#tablebody}

表体。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `rowHeight` | <code>number</code> | 是 | 行高，单位 mm；`rowHeightMode` 为 minimum 时作为最小行高。 |
| `rowHeightMode` | <code><a href="#tablerowheightmode">TableRowHeightMode</a></code> | 是 |  |
| `style` | <code><a href="#cellstyle">CellStyle</a></code> | 是 |  |

### AggregateCellContent {#aggregatecellcontent}

表尾单元格的汇总内容。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'aggregate'</code> | 是 |  |
| `fn` | <code><a href="#aggregatefunction">AggregateFunction</a></code> | 是 |  |
| `field` | <code>string</code> | 可省 | 参与汇总的行内字段路径；`fn` 为 count 时可省略，表示统计行数。 |
| `scope` | <code><a href="#aggregatescope">AggregateScope</a></code> | 是 |  |
| `format` | <code><a href="#valueformat">ValueFormat</a></code> | 可省 |  |

### TableFooterCellContent {#tablefootercellcontent}

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

取其一：<code><a href="#textcontent">TextContent</a></code>、<code><a href="#aggregatecellcontent">AggregateCellContent</a></code>。

### TableFooterCell {#tablefootercell}

表尾单元格。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `columnId` | <code>string</code> | 是 | 起始列的标识。 |
| `colSpan` | <code>number</code> | 是 | 向右跨越的列数，至少为 1。 |
| `content` | <code><a href="#tablefootercellcontent">TableFooterCellContent</a></code> | 是 |  |
| `align` | <code><a href="#horizontalalign">HorizontalAlign</a></code> | 可省 | 水平对齐，缺省跟随行样式再跟随起始列。 |

### TableFooterRow {#tablefooterrow}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | <code>string</code> | 是 | 行标识，在所属表格内唯一。 |
| `placement` | <code><a href="#tablefooterplacement">TableFooterPlacement</a></code> | 是 |  |
| `height` | <code>number</code> | 是 | 行高，单位 mm。 |
| `style` | <code><a href="#cellstyle">CellStyle</a></code> | 是 |  |
| `cells` | <code><a href="#tablefootercell">TableFooterCell</a>[]</code> | 是 |  |

### TableBorder {#tableborder}

表格网格线。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stroke` | <code><a href="#stroke">Stroke</a></code> | 是 |  |
| `outer` | <code>boolean</code> | 是 | 是否画外框。 |
| `horizontal` | <code>boolean</code> | 是 | 是否画行之间的横线。 |
| `vertical` | <code>boolean</code> | 是 | 是否画列之间的竖线。 |

## 通用类型

### Color {#color}

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

类型：<code>string</code>

### Edges {#edges}

四边距离，单位 mm。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `top` | <code>number</code> | 是 |  |
| `right` | <code>number</code> | 是 |  |
| `bottom` | <code>number</code> | 是 |  |
| `left` | <code>number</code> | 是 |  |

### Stroke {#stroke}

描边。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `width` | <code>number</code> | 是 | 线宽，单位 mm。 |
| `style` | <code><a href="#strokestyle">StrokeStyle</a></code> | 是 |  |
| `color` | <code><a href="#color">Color</a></code> | 是 |  |

### BorderSides {#bordersides}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `top` | <code><a href="#stroke">Stroke</a></code> | 可省 |  |
| `right` | <code><a href="#stroke">Stroke</a></code> | 可省 |  |
| `bottom` | <code><a href="#stroke">Stroke</a></code> | 可省 |  |
| `left` | <code><a href="#stroke">Stroke</a></code> | 可省 |  |

### BoxStyle {#boxstyle}

元素外框样式。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `background` | <code><a href="#color">Color</a></code> | 可省 | 背景色，缺省为透明。 |
| `border` | <code><a href="#bordersides">BorderSides</a></code> | 可省 |  |
| `padding` | <code><a href="#edges">Edges</a></code> | 可省 | 内边距，单位 mm。 |

### TextStyle {#textstyle}

文本样式。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fontFamily` | <code>string</code> | 可省 | 字体族，缺省使用运行时默认字体。 |
| `fontSize` | <code>number</code> | 是 | 字号，单位 pt。 |
| `bold` | <code>boolean</code> | 是 |  |
| `italic` | <code>boolean</code> | 是 |  |
| `underline` | <code>boolean</code> | 是 |  |
| `lineThrough` | <code>boolean</code> | 是 |  |
| `color` | <code><a href="#color">Color</a></code> | 是 |  |
| `align` | <code><a href="#textalign">TextAlign</a></code> | 是 |  |
| `verticalAlign` | <code><a href="#verticalalign">VerticalAlign</a></code> | 是 |  |
| `lineHeight` | <code>number</code> | 是 | 行高，字号的倍数。 |
| `letterSpacing` | <code>number</code> | 是 | 字间距，单位 pt。 |

### ValueMapEntry {#valuemapentry}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `value` | <code>string</code> | 是 |  |
| `label` | <code>string</code> | 可省 |  |

### MapFormat {#mapformat}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'map'</code> | 是 |  |
| `entries` | <code><a href="#valuemapentry">ValueMapEntry</a>[]</code> | 是 |  |
| `fallback` | <code>string</code> | 可省 | 未命中任何映射时显示的文本，缺省显示原值。 |

### ExpressionFormat {#expressionformat}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'expression'</code> | 是 |  |
| `expression` | <code>string</code> | 是 | 受限表达式源码。 |

### ValueFormat {#valueformat}

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

取其一：<code>FormatSpec</code>、<code><a href="#mapformat">MapFormat</a></code>、<code><a href="#expressionformat">ExpressionFormat</a></code>。

### StaticTextContent {#statictextcontent}

固定文本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'static'</code> | 是 |  |
| `text` | <code>string</code> | 是 |  |

### FieldTextContent {#fieldtextcontent}

绑定单个数据字段。

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

### TemplateTextContent {#templatetextcontent}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'template'</code> | 是 |  |
| `template` | <code>string</code> | 是 |  |

### ExpressionTextContent {#expressiontextcontent}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'expression'</code> | 是 |  |
| `expression` | <code>string</code> | 是 | 受限表达式源码。 |
| `format` | <code><a href="#valueformat">ValueFormat</a></code> | 可省 | 计算结果的格式。 |

### TextContent {#textcontent}

文本内容来源。

取其一：<code><a href="#statictextcontent">StaticTextContent</a></code>、<code><a href="#fieldtextcontent">FieldTextContent</a></code>、<code><a href="#templatetextcontent">TemplateTextContent</a></code>、<code><a href="#expressiontextcontent">ExpressionTextContent</a></code>。

### StaticImageSource {#staticimagesource}

固定地址的图片。

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

### FieldImageSource {#fieldimagesource}

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | <code>'field'</code> | 是 |  |
| `field` | <code>string</code> | 是 |  |

### ImageSource {#imagesource}

图片来源。

取其一：<code><a href="#staticimagesource">StaticImageSource</a></code>、<code><a href="#fieldimagesource">FieldImageSource</a></code>。

## 取值

### PageOrientation {#pageorientation}

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

取值见常量 `PAGE_ORIENTATIONS`：

| 取值 | 中文名 |
| --- | --- |
| `portrait` | 纵向 |
| `landscape` | 横向 |

### PageBandVariant {#pagebandvariant}

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

取值见常量 `PAGE_BAND_VARIANTS`：

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

### PageBandKey {#pagebandkey}

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

类型：<code>'default' &#124; <a href="#pagebandvariant">PageBandVariant</a></code>

### TextAlign {#textalign}

文本水平对齐。

取值见常量 `TEXT_ALIGNS`：

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

### HorizontalAlign {#horizontalalign}

单元格水平对齐。

取值见常量 `HORIZONTAL_ALIGNS`：

| 取值 | 中文名 |
| --- | --- |
| `left` | 左 |
| `center` | 居中 |
| `right` | 右 |

### VerticalAlign {#verticalalign}

垂直对齐。

取值见常量 `VERTICAL_ALIGNS`：

| 取值 | 中文名 |
| --- | --- |
| `top` | 上 |
| `middle` | 居中 |
| `bottom` | 下 |

### StrokeStyle {#strokestyle}

线型。

取值见常量 `STROKE_STYLES`：

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

### TextOverflow {#textoverflow}

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

取值见常量 `TEXT_OVERFLOWS`：

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

### RichTextSource {#richtextsource}

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

取值见常量 `RICH_TEXT_SOURCES`：

| 取值 | 中文名 |
| --- | --- |
| `html` | HTML |
| `document` | 富文本文档 |

### ImageFit {#imagefit}

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

取值见常量 `IMAGE_FITS`：

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

### LineDirection {#linedirection}

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

取值见常量 `LINE_DIRECTIONS`：

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

### BarCodeFormat {#barcodeformat}

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

### MatrixCodeFormat {#matrixcodeformat}

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

### MatrixCodeLevel {#matrixcodelevel}

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

### AggregateFunction {#aggregatefunction}

表格汇总函数。

取值见常量 `AGGREGATE_FUNCTIONS`：

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

### AggregateScope {#aggregatescope}

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

取值见常量 `AGGREGATE_SCOPES`：

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

### TableFooterPlacement {#tablefooterplacement}

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

取值见常量 `TABLE_FOOTER_PLACEMENTS`：

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

### TableRowHeightMode {#tablerowheightmode}

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

取值见常量 `TABLE_ROW_HEIGHT_MODES`：

| 取值 | 中文名 |
| --- | --- |
| `fixed` | 固定 |
| `minimum` | 至少 |

### TableCellType {#tablecelltype}

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

取值见常量 `TABLE_CELL_TYPES`：

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

### SingleSheetPreference {#singlesheetpreference}

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

取值见常量 `SINGLE_SHEET_PREFERENCES`：

| 取值 | 中文名 |
| --- | --- |
| `first` | 首页 |
| `last` | 末页 |