193 lines
6.5 KiB
Markdown
193 lines
6.5 KiB
Markdown
# @report/layout
|
||
|
||
元素测量、文本换行、动态高度、明细表展开与分页，产出所有 Renderer 共用的 `LayoutDocument`。
|
||
|
||
> 对应设计文档 §4.3、§9、§3.3。
|
||
|
||
## 定位
|
||
|
||
Layout 负责**尺寸计算、文本测量、换行、表格展开、动态高度、分页**；
|
||
Renderer 只负责把 `LayoutDocument` 画成 HTML / SVG / PDF，**绝不重新计算分页**（§3.3）。
|
||
|
||
Layout 通过 `TextMeasurer`、`FontResolver` 接口获得环境能力，**不直接依赖 DOM**（§4.3）。
|
||
因此同一套分页逻辑可以在浏览器、Node 和服务端复用。
|
||
|
||
## 安装与使用
|
||
|
||
```ts
|
||
import { createDocument } from "@report/core"
|
||
import { layoutDocument, createEstimateMeasurer, createPassthroughFontResolver } from "@report/layout"
|
||
|
||
const doc = createDocument({ name: "销售单" })
|
||
|
||
const result = await layoutDocument(
|
||
doc,
|
||
{ data: { ds1: rows }, parameters: { year: 2024 } },
|
||
{
|
||
textMeasurer: createEstimateMeasurer(),
|
||
fontResolver: createPassthroughFontResolver(),
|
||
},
|
||
)
|
||
|
||
console.log(result.pageCount)
|
||
for (const page of result.pages) {
|
||
for (const node of page.nodes) {
|
||
console.log(node.id, node.type, node.frame)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Node 侧使用真实字体度量
|
||
|
||
`@report/layout/fonts` 依赖 `node:fs`，因此单独入口，避免浏览器打包被迫引入 Node 内置模块。
|
||
|
||
```ts
|
||
import { FontLibrary, createFontMeasurer, findSystemFontSources } from "@report/layout/fonts"
|
||
import { layoutDocument } from "@report/layout"
|
||
|
||
const library = new FontLibrary()
|
||
library.loadAll(findSystemFontSources())
|
||
|
||
const measurer = createFontMeasurer({
|
||
library,
|
||
fallbackFamilies: ["SimSun", "SimHei", "Microsoft YaHei"],
|
||
})
|
||
|
||
const result = await layoutDocument(doc, context, {
|
||
textMeasurer: measurer,
|
||
fontResolver: measurer.resolver,
|
||
})
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### LayoutDocument 是唯一的分页真相
|
||
|
||
```ts
|
||
interface LayoutDocument {
|
||
pages: LayoutPage[]
|
||
diagnostics: LayoutDiagnostic[]
|
||
pageCount: number
|
||
}
|
||
|
||
interface LayoutPage {
|
||
width: number // mm
|
||
height: number // mm
|
||
pageNumber: number // 从 1 开始
|
||
nodes: LayoutNode[]
|
||
sections: LayoutPageSection[]
|
||
}
|
||
```
|
||
|
||
所有节点使用**绝对坐标**（mm，原点在页面左上角），Renderer 不需要再做任何层级累加。
|
||
|
||
### 单位约定
|
||
|
||
文档内部统一 mm（§7）。`units.ts` 集中提供换算：
|
||
|
||
| 函数 | 说明 |
|
||
| --- | --- |
|
||
| `mmToPx` / `pxToMm` | 与 Designer 显示层换算（1in = 96px） |
|
||
| `mmToPt` / `ptToMm` | 与 PDF 输出边界换算（1in = 72pt） |
|
||
| `fontSizeToMm` | 字号 pt → 几何 mm，测量时使用 |
|
||
|
||
### 文本换行
|
||
|
||
- 西文按**词**断行，不拆开单词（超长词强制断开并标记 `brokeWords`）。
|
||
- 中文按**字**断行，无需空格分词。
|
||
- 支持**避头点**（`，。）】` 不出现在行首）与**避尾点**（`（【` 不出现在行尾）。
|
||
- 显式换行符保留为硬换行。
|
||
|
||
换行结果完全由注入的 `TextMeasurer` 决定，因此与具体字体环境解耦。
|
||
|
||
### 动态高度
|
||
|
||
`text` 元素内容高于 `frame.height` 时，布局阶段会**自动增高**（§3.3）。
|
||
这是表格 `rowHeightMode: "auto"` 的基础。
|
||
|
||
### 中英混排与字体回退
|
||
|
||
拉丁字体通常不含汉字。度量器按**字符**查找覆盖它的字体：
|
||
|
||
```
|
||
"中" 在 Arial 中 → glyphId 0（.notdef）→ 回退到 SimHei → 1.0em
|
||
"A" 在 Arial 中 → glyphId 36 → 直接用 Arial → 0.667em
|
||
```
|
||
|
||
**关键正确性细节**：字体缺失字符时返回 `.notdef` 字形，而它**本身带有 advance 宽度**。
|
||
若直接返回该宽度，缺字会被静默当成正常字符排版。本实现对此显式返回 `null`，
|
||
由调用方按回退字体或兜底宽度处理，并在 `TextMetrics.fallback` 中标记。
|
||
|
||
### 分页
|
||
|
||
- 页眉 / 页脚每页重复，其高度先从可用高度扣除。
|
||
- 明细表产出「表头块 + 每行一个块」的序列，因此**行与行之间可跨页断开，单行不会被拆散**。
|
||
- `repeatHeaderOnEachPage` 控制表头是否每页重复。
|
||
- 页眉 + 页脚高度达到或超过内容区时返回**明确错误诊断**而不是静默产出重叠页面。
|
||
- 单个内容块高于整页时产生 `layout.page-overflow` 警告并让其独占一页（允许溢出）。
|
||
|
||
### 页脚页码占位符
|
||
|
||
页脚文本中的 `{pageNumber}` 与 `{pageCount}` 会在分页完成后替换为实际值，
|
||
用于「第 X 页 / 共 Y 页」。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/
|
||
├── units.ts 单位换算
|
||
├── measurer.ts TextMeasurer / FontResolver 接口 + 估算度量器
|
||
├── font-parser.ts TTF/OTF/TTC 字节解析（无文件系统依赖）
|
||
├── load-font.ts 字体加载与 FontLibrary（Node）
|
||
├── font-measurer.ts 基于真实字体度量的 TextMeasurer
|
||
├── system-fonts.ts 系统字体探测
|
||
├── text-wrap.ts 分段、换行、避头尾、动态高度
|
||
├── layout-document.ts LayoutDocument 模型
|
||
├── measure.ts 样式解析、绑定求值、元素测量
|
||
├── table.ts 明细表展开为分页块
|
||
├── paginate.ts 分页引擎
|
||
├── engine.ts Layout Engine 主入口
|
||
├── index.ts 主入口（纯逻辑，无 node:fs）
|
||
└── fonts.ts 字体入口（Node）
|
||
```
|
||
|
||
## 字体解析说明
|
||
|
||
`font-parser.ts` 自行解析字体二进制，**不依赖 canvas 等原生模块**：
|
||
|
||
| 表 | 用途 |
|
||
| --- | --- |
|
||
| `head` | unitsPerEm（度量归一化基准） |
|
||
| `hhea` | numberOfHMetrics、ascender、descender、lineGap |
|
||
| `hmtx` | 每个字形的 advanceWidth |
|
||
| `cmap` | 字符 → 字形映射（format 4 与 format 12） |
|
||
| `maxp` | numGlyphs |
|
||
| `name` | 字体族名（用于匹配与诊断） |
|
||
|
||
同时支持 `.ttf` / `.otf` 与 `.ttc` 字体集合（按 `fontIndex` 取字体）。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
pnpm build # tsup 打包
|
||
pnpm test # vitest
|
||
pnpm typecheck # tsc --noEmit
|
||
```
|
||
|
||
## 当前测试覆盖
|
||
|
||
| 测试文件 | 用例数 | 覆盖内容 |
|
||
| --- | --- | --- |
|
||
| `font.test.ts` | 29 | TTF/TTC 解析、真实字宽、中英回退、缺字检测 |
|
||
| `text-wrap.test.ts` | 30 | 分词、按词/按字换行、避头尾、动态高度 |
|
||
| `pagination.test.ts` | 28 | 页面几何、单页/多页、页眉页脚重复、Y 分层 |
|
||
|
||
合计 **87** 个用例。字体相关用例在缺少系统字体的环境中自动跳过。
|
||
|
||
## 尚未实现
|
||
|
||
- 表达式驱动的分组（`group-header` / `group-footer`）与跨页合计。
|
||
- 容器内嵌套表格的多级拆分。
|
||
- 表格列自动宽度（当前按声明宽度 + 等比压缩）。
|
||
- PDF 输出（属 `report-renderer`，阶段 4）。
|