如有医疗设备等不能断电的情况，请在 10 月 22 日前联系物业登记。
', } ``` - 打印时按白名单把 HTML 换成文档：认识的标签与 `style` 属性换成块与样式，`script`、`img`、`iframe` 这类连同内容去掉，表格这类去掉标签、留下文字。规则见 [XiHan.UI 的解析 HTML](https://ui.docs.xihanfun.com/runtime/rich-text#解析-html)。 - 连同内容去掉或降级了标签时，给出警告诊断 `richText.droppedContent`，`params.field` 是字段路径，`params.names` 是去掉的标签名；`style` 属性与链接地址的取舍不报。上面的数据带了一段 `script`，所以会有这条警告。 - HTML 里的 `` 也是行内字段，按同一份数据取值。 ### 字段里的文档 字段值是富文本文档对象时用 `source: 'document'`。值先按模板里同样的规则检查，不合规时整段不画，给出错误级诊断 `richText.invalidData`：`params.field` 是字段路径，`params.code` 是问题码，`params.path` 是出问题的位置（如 `blocks[0].type`）。字段值是 JSON 串时也不合规，先在宿主这边解析成对象。 字段为空（`null`、`undefined` 或空串）时没有内容，不报诊断。 ## 基准样式 元素的 `style` 是基准样式：字体、字号、颜色、行高倍数、字间距、对齐与垂直对齐。块的 `align` 与文字的 `marks` 在它之上覆写，没写的取基准样式。 ## 排版规则 - 按元素内宽（扣掉左右内边距）逐块排。段落与标题的折行与普通文本是同一套规则：中日韩文字逐字可断，拉丁文按词断，一个单词跨两种样式时不拆开。 - 行高是这一行里最大的字号乘以行高倍数。上标与下标的字号缩到 0.7 倍，行高仍按原字号算。 - 一、二、三级标题的字号是基准字号的 1.6、1.35、1.15 倍，并且加粗；文字上写 `bold: false` 可以取消加粗。 - 顶层的块与块之间空半个基准字号；列表项之间、列表项里的块之间不空。 - 列表每层缩进两个基准字号。无序列表三层依次用 `•`、`◦`、`▪`，有序列表从 `start` 编号（缺省 1）；符号或序号的右边离文字半个基准字号。 - 分隔线单独占一行基准行高，用基准颜色画 0.2 mm 的横线。 - 两端对齐的块里，最后一行与换行之前的那一行不拉伸。 - 链接写成带地址的链接，外观只取这截文字自己的样式。 这些倍数都是 `@xihan-print/core` 导出的常量，见[模型层 core](../reference/core#layout-rich-text)。 ## 跨页 跨页与长文本相同：按整行切到后续输出页，段落可以从中间切开；每段都带上下内边距，续排那一段的第一行不留段距；只有一段时高度不小于设计高度。富文本下面的元素随它下推，规则见[运行时](./runtime#正文元素的位置)。 不做孤行与寡行控制：标题可能单独留在一页的最后一行。 ## 在设计器里 - 属性面板的「内容」先选来源；选「字段」时再选绑定的字段与内容格式（HTML 或富文本文档）。 - 写死的文档在属性面板上不能编辑，用代码写进模板（如上面的例子），或从存量模板迁移过来。 - 画布按设计态排版显示；不给示例数据时，字段显示为 `{路径}` 占位。 ## 校验 | 问题码 | 级别 | 说明 | | --- | --- | --- | | `richText.invalidDocument` | 错误 | 文档结构不对，`params.code` 是 XiHan.UI 的[检查](https://ui.docs.xihanfun.com/runtime/rich-text#检查)给出的问题码 | | `field.invalidPath` | 错误 | 行内字段的路径写法不对 | | `format.*`、`invalid-option` 等 | 错误 | 行内字段的值格式不对，与文本内容的值格式同一套规则 | | `richText.empty` | 警告 | 写死的文档没有任何文字、行内字段、分隔线或列表项 | | `element.flowInBand` | 错误 | 放进了页眉或页脚 | ## 从存量 HTML 元素迁移 存量模板里的 HTML 元素，有的在模板里存一段 HTML，有的存一个返回 HTML 的函数。迁移到富文本由宿主完成：解析器是 `@xihan-ui/core/rich-text` 的 `parseRichTextHtml`，不依赖 DOM，Node.js 里也能跑，可以写成一次性的迁移脚本或放在服务端。 | 旧写法 | 迁移成 | | --- | --- | | 写死的 HTML | 解析成 `{ kind: 'static', document }` | | 绑定字段，字段值是 HTML | `{ kind: 'field', field, source: 'html' }`，打印时再解析 | | 函数只返回一个字符串字面量 | 静态取出这段字面量（不执行函数），再按写死的 HTML 处理 | | 函数里有拼接、条件、取数等逻辑 | 不能自动迁移，记进报告人工改写成富文本加行内字段、带表达式的文本或其它元素 | | HTML 里的表格、图片 | 解析时去掉并记进丢弃清单；表格改用表格元素，图片另起图片元素 | 迁移时不执行模板里的任何代码。 ### 迁移报告 每个元素迁移后留一条记录，汇总起来就是迁移报告。报告的形状由宿主自定，打印的包里没有发布这些类型与函数；下面的 `migrateHtmlContent`、`RichTextMigrationEntry` 与 `needsReview` 只是一种写法，可以照着改成自己的： ```ts import type { RichTextContent } from '@xihan-print/core' import type { RichTextDrop } from '@xihan-ui/core/rich-text' import { parseRichTextHtml } from '@xihan-ui/core/rich-text' /** 旧元素里与迁移有关的三种写法。 */ export type LegacyHtmlContent = | { kind: 'html', html: string } // 写死的 HTML，或从只返回一个字符串字面量的函数里静态取出的 HTML | { kind: 'field', field: string } // 绑定字段，字段值是 HTML | { kind: 'code', source: string } // 其余的函数源码 /** 迁移报告里的一条：一个元素一条。 */ export interface RichTextMigrationEntry { /** 原元素的标识。 */ elementId: string /** static：已换成写死的文档；field：改成绑定字段，打印时再解析；manual：要人工改写。 */ outcome: 'static' | 'field' | 'manual' /** 解析时丢掉的东西，即 parseRichTextHtml 的 dropped；绑定字段与人工改写的为空。 */ dropped: readonly RichTextDrop[] /** 人工改写时参考的原始内容。 */ source?: string } export function migrateHtmlContent(elementId: string, legacy: LegacyHtmlContent): { content?: RichTextContent, entry: RichTextMigrationEntry } { switch (legacy.kind) { case 'html': { const { document, dropped } = parseRichTextHtml(legacy.html) return { content: { kind: 'static', document }, entry: { elementId, outcome: 'static', dropped } } } case 'field': return { content: { kind: 'field', field: legacy.field, source: 'html' }, entry: { elementId, outcome: 'field', dropped: [] } } case 'code': return { entry: { elementId, outcome: 'manual', dropped: [], source: legacy.source } } } } /** 要人工复核的条目：要人工改写的，以及丢了标签或连同内容去掉了东西（表格、图片、脚本等）的。 */ export function needsReview(entry: RichTextMigrationEntry): boolean { return entry.outcome === 'manual' || entry.dropped.some(drop => drop.kind === 'element' || drop.kind === 'content') } ``` - `outcome` 是迁移结果：`static` 已换成写死的文档，`field` 改成绑定字段，`manual` 要人工改写，`source` 留着原来的内容供参考。 - `dropped` 直接取 `parseRichTextHtml` 的丢弃清单，每项是 `{ kind, name, count }`：`element` 去掉或降级了标签、文字保留，`content` 连同内容去掉，`style` 是不认识或取值不合法的 `style` 属性，`link` 是没通过判定的链接地址。同类同名合成一条并计数，详见 [XiHan.UI 的丢弃清单](https://ui.docs.xihanfun.com/runtime/rich-text#丢弃清单)。 - `dropped` 里有 `element` 或 `content` 的要人工复核，表格与图片要另外补上；只有 `style` 与 `link` 的通常可以忽略。 - 绑定字段的元素在迁移时还不知道数据里的 HTML 会丢什么，打印时由 `richText.droppedContent` 诊断报出。