583 lines
14 KiB
Markdown
583 lines
14 KiB
Markdown
# EPUB 渲染管线详解
|
||
|
||
读书 (WeRead) 的 EPUB 渲染管线将原始 XHTML 文件转换为可分页、可交互的阅读视图。本文档完整描述从 EPUB 文件到屏幕像素的每一步。
|
||
|
||
---
|
||
|
||
## 1. 管线总览
|
||
|
||
```
|
||
EPUB 文件 (.epub)
|
||
|
|
||
v
|
||
[WREpubParser] 解析 EPUB 结构
|
||
|
|
||
v
|
||
[WREpubTypesetter] XHTML → NSAttributedString
|
||
| (CSS 级联 + HTML 解析 + 后处理)
|
||
v
|
||
[WRCoreTextLayouter] NSAttributedString → 分页布局
|
||
| (CTTypesetter + 分页算法)
|
||
v
|
||
[WRCoreTextLayoutFrame] 单页布局帧
|
||
| (CTFrame + 行提取 + 避免断页)
|
||
v
|
||
[WRPageView] 渲染到屏幕
|
||
| (CGContext 绘制 + 图片 + 装饰)
|
||
v
|
||
屏幕像素
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 阶段一: EPUB 解析 (WREpubParser)
|
||
|
||
### 2.1 输入
|
||
|
||
EPUB 文件路径 + WRBook 模型对象
|
||
|
||
### 2.2 解析步骤
|
||
|
||
```
|
||
1. parseContainerXML
|
||
- 读取 META-INF/container.xml
|
||
- 提取 OPF 文件路径 (rootfile full-path)
|
||
|
||
2. parseOPFAtRelativePath
|
||
- 解析 content.opf
|
||
- 提取 manifest (id → href 映射)
|
||
- 提取 spine (阅读顺序 idref 列表)
|
||
- 提取 metadata (书名、标识符等)
|
||
|
||
3. parseNCX
|
||
- 解析 toc.ncx (目录)
|
||
- 提取 navPoint 树 (id, label, src, playOrder)
|
||
|
||
4. _buildChapterList
|
||
- 将 spine idref 映射到 manifest href
|
||
- 生成 chapters 数组 [{id, href, mediaType, fullPath}]
|
||
|
||
5. _buildResourceMap
|
||
- 构建资源路径映射 (href → 绝对路径)
|
||
- 同时索引文件名用于快速查找
|
||
```
|
||
|
||
### 2.3 输出
|
||
|
||
- chapters 数组（有序章节列表）
|
||
- resourceMap 字典（资源路径映射）
|
||
- WRBook 元数据更新
|
||
|
||
---
|
||
|
||
## 3. 阶段二: CSS 级联 (WREpubTypesetter)
|
||
|
||
### 3.1 CSS 加载顺序
|
||
|
||
```
|
||
Layer 1: default.css (App Bundle)
|
||
↓ 覆盖
|
||
Layer 2: replace.css (App Bundle)
|
||
↓ 覆盖
|
||
Layer 3: dark.css (App Bundle, 仅暗色模式)
|
||
↓ 覆盖
|
||
Layer 4: EPUB 嵌入 CSS (书籍自带)
|
||
↓ 覆盖
|
||
Layer 5: 用户设置 CSS (运行时生成)
|
||
```
|
||
|
||
### 3.2 各层内容
|
||
|
||
**Layer 1 - default.css**:
|
||
```css
|
||
body { font-family: "PingFang SC", sans-serif; margin: 0; padding: 10px 15px; }
|
||
p { margin-top: 0.5em; margin-bottom: 0.5em; }
|
||
h1 { font-size: 1.8em; font-weight: bold; }
|
||
h2 { font-size: 1.5em; font-weight: bold; }
|
||
h3 { font-size: 1.3em; font-weight: bold; }
|
||
ul, ol { padding-left: 1.5em; }
|
||
blockquote { margin-left: 1em; font-style: italic; }
|
||
```
|
||
|
||
**Layer 2 - replace.css**:
|
||
```css
|
||
h1, h2, h3 { font-family: "Source Han Serif CN", serif; }
|
||
pre, code { font-family: "Menlo", monospace; }
|
||
img.bodyPic { wr-vertical-center-style: 2; max-width: 100%; }
|
||
.conQuot { /* 引用块样式 */ }
|
||
```
|
||
|
||
**Layer 3 - dark.css**:
|
||
```css
|
||
body { background-color: #1a1a1a; color: #cccccc; }
|
||
a { color: #6eaad7; }
|
||
img { filter: brightness(0.85); }
|
||
```
|
||
|
||
**Layer 5 - 用户设置 CSS** (动态生成):
|
||
```css
|
||
body { font-size: 18px; line-height: 1.8; font-family: "PingFang SC", sans-serif; }
|
||
body { background-color: #f5f0e8; } /* 护眼模式 */
|
||
p { text-indent: 2em; } /* 首行缩进 */
|
||
```
|
||
|
||
### 3.3 级联合并
|
||
|
||
使用 DTCSSStylesheet.mergeStylesheet: 方法按顺序合并，后加载的覆盖先前的同名规则。
|
||
|
||
---
|
||
|
||
## 4. 阶段三: HTML 解析 (DTHTMLAttributedStringBuilder)
|
||
|
||
### 4.1 SAX 解析流程
|
||
|
||
```
|
||
XHTML 数据
|
||
|
|
||
v
|
||
DTHTMLParser (SAX)
|
||
|
|
||
├── didStartElement: → 创建 DTHTMLElement 节点
|
||
| 应用 CSS 样式
|
||
| 处理自定义属性
|
||
|
|
||
├── foundCharacters: → 累积文本到当前元素
|
||
|
|
||
├── foundCDATA: → 处理 CDATA 内容
|
||
|
|
||
└── didEndElement: → 弹出元素栈
|
||
调用 interpretAttributes
|
||
插入分页标记
|
||
```
|
||
|
||
### 4.2 元素处理
|
||
|
||
每个 HTML 标签被转换为 DTHTMLElement 节点：
|
||
|
||
```
|
||
DTHTMLElement
|
||
├── tagName: "p" / "div" / "img" / ...
|
||
├── classNames: ["bodyPic", "conQuot"]
|
||
├── fontDescriptor: 字体描述符
|
||
├── paragraphStyle: 段落样式
|
||
├── textColor / backgroundColor
|
||
├── children: [DTHTMLElement]
|
||
├── textAttachment (图片)
|
||
├── linkURL (链接)
|
||
├── [WeRead 扩展]
|
||
│ ├── verticalCenterStyle
|
||
│ ├── pageRelate
|
||
│ ├── shouldAvoidPageBreakInside
|
||
│ ├── pageBreakAfter / pageBreakBefore
|
||
│ ├── pageBackgroundColor
|
||
│ └── pageBackgroundImage
|
||
```
|
||
|
||
### 4.3 样式应用顺序
|
||
|
||
```
|
||
1. CSS 样式表规则 (class, id, tag 选择器)
|
||
2. 内联 style="" 属性
|
||
3. WeRead 自定义 CSS 属性
|
||
4. 元素默认样式 (基于标签名)
|
||
```
|
||
|
||
### 4.4 后处理 (_WRPostProcessElementTree)
|
||
|
||
在元素树转为 NSAttributedString 之前，执行 WeRead 特有的后处理：
|
||
|
||
**图片处理**:
|
||
- 设置最大显示尺寸 (1080x1920)
|
||
- 超限图片按比例缩放
|
||
- 添加 .bodyPic CSS 类
|
||
- 设置 wr-vertical-center-style: 2
|
||
|
||
**链接处理**:
|
||
- 添加下划线样式
|
||
- 存储链接 URL 到自定义属性
|
||
|
||
**自定义属性处理**:
|
||
- wr-vertical-center-style → DTHTMLVerticalCenterAttribute
|
||
- weread-page-relate → DTPageRelateAttribute
|
||
|
||
---
|
||
|
||
## 5. 阶段四: NSAttributedString 生成
|
||
|
||
### 5.1 递归转换
|
||
|
||
```
|
||
DTHTMLElement.attributedString
|
||
|
|
||
├── 处理 void 元素 (br → "\n", img → attachment, hr → "\n")
|
||
|
|
||
├── 插入 pageBreakBefore 标记 (如果需要)
|
||
|
|
||
├── 转换文本内容
|
||
| ├── 应用 CTFont (从 fontDescriptor)
|
||
| ├── 应用前景色 (kCTForegroundColorAttributeName)
|
||
| ├── 应用背景色 (DTBackgroundColor)
|
||
| └── 应用链接 (DTLink)
|
||
|
|
||
├── 递归处理子元素
|
||
|
|
||
├── 应用段落样式 (kCTParagraphStyleAttributeName)
|
||
|
|
||
├── 插入 pageBreakAfter 标记 (如果需要)
|
||
|
|
||
└── 应用 WeRead 页面属性
|
||
├── DTHTMLVerticalCenterAttribute
|
||
├── DTPageRelateAttribute
|
||
├── DTPageBreakInsideAvoidAttribute
|
||
├── DTPageBackgroundColorAttribute
|
||
└── DTPageBackgroundImageAttribute
|
||
```
|
||
|
||
### 5.2 输出
|
||
|
||
一个 NSAttributedString，包含：
|
||
- 标准 CoreText 属性 (字体、颜色、段落样式)
|
||
- DTCoreText 标准属性 (链接、附件、列表)
|
||
- WeRead 自定义属性 (分页、居中、背景)
|
||
|
||
---
|
||
|
||
## 6. 阶段五: 分页布局 (WRCoreTextLayouter)
|
||
|
||
### 6.1 Typesetter 创建
|
||
|
||
```
|
||
NSAttributedString
|
||
|
|
||
v
|
||
CTTypesetterCreateWithAttributedString
|
||
|
|
||
v
|
||
CTTypesetter (内部缓存字形分析结果)
|
||
```
|
||
|
||
### 6.2 分页算法
|
||
|
||
```
|
||
输入: NSAttributedString + pageSize
|
||
|
||
1. 计算可用宽度 = pageSize.width - edgeInsets.left - edgeInsets.right
|
||
|
||
2. 初始化 currentIndex = 0
|
||
|
||
3. 循环:
|
||
a. lineBreakIndex = CTTypesetterSuggestLineBreak(typesetter, currentIndex, usableWidth)
|
||
b. 如果 lineBreakIndex <= 0, 退出循环
|
||
c. 创建 WRCoreTextLayoutFrame(range: currentIndex..<currentIndex+lineBreakIndex)
|
||
d. currentIndex += lineBreakIndex
|
||
|
||
4. 返回 [WRCoreTextLayoutFrame] 数组 (每帧 = 一页)
|
||
```
|
||
|
||
### 6.3 页面范围查询
|
||
|
||
`rangeForPageAtIndex:pageSize:` 通过模拟分页快速定位指定页的文本范围，无需创建布局帧对象。
|
||
|
||
### 6.4 行高建议
|
||
|
||
`suggestedLineFragHeights` 逐行创建临时 CTLine 测量高度，用于精确分页计算和避免孤行/寡行。
|
||
|
||
---
|
||
|
||
## 7. 阶段六: 单页布局 (WRCoreTextLayoutFrame)
|
||
|
||
### 7.1 CTFrame 创建
|
||
|
||
```
|
||
CTTypesetter + range + CGPath(rect)
|
||
|
|
||
v
|
||
CTTypesetterCreateFrame
|
||
|
|
||
v
|
||
CTFrame (包含 CTLines 和 CTRuns)
|
||
```
|
||
|
||
### 7.2 行提取
|
||
|
||
```
|
||
CTFrameGetLines → CTLine 数组
|
||
CTFrameGetLineOrigins → 行原点数组
|
||
|
||
对每个 CTLine:
|
||
CTLineGetStringRange → 字符范围
|
||
CTLineGetTypographicBounds → ascent/descent/leading
|
||
创建 WRCoreTextLayoutLine 对象
|
||
|
||
判断每行是否为段落末尾行 (检查下一个字符是否为 '\n')
|
||
```
|
||
|
||
### 7.3 avoidPageBreakInside 实现
|
||
|
||
```
|
||
1. 从最后一行向前遍历
|
||
2. 检查行的 attributedString 属性:
|
||
- WRAvoidPageBreakInside == YES?
|
||
- WRBlockType ∈ {table, code, list, blockquote}?
|
||
3. 如果是受保护元素的一部分，标记需要移除
|
||
4. 最多移除 3 行 (kMaxLinesToRemove)
|
||
5. 调用 rebuildFrameWithoutLastLines: 更新帧
|
||
6. 返回 YES 表示有行被移除
|
||
```
|
||
|
||
### 7.4 渲染高度计算
|
||
|
||
```
|
||
getRenderHeight:
|
||
lastLine = lines.lastObject
|
||
lastLineBottom = lastLine.origin.y - lastLine.descent
|
||
renderedHeight = frameHeight - lastLineBottom + insets.top + insets.bottom
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 阶段七: 绘制到屏幕 (WRCoreTextLayoutFrame)
|
||
|
||
### 8.1 绘制流程
|
||
|
||
```
|
||
drawInContext:image:size:inRect:position:
|
||
|
||
1. CGContextSaveGState
|
||
|
||
2. 坐标系翻转 (CoreText 底左原点 → UIKit 顶左原点)
|
||
CGContextTranslateCTM(0, height)
|
||
CGContextScaleCTM(1, -1)
|
||
|
||
3. 应用位置偏移 (多列/多页布局)
|
||
|
||
4. 应用内容内边距
|
||
|
||
5. 绘制封面图片 (如果有)
|
||
|
||
6. CTFrameDraw(ctFrame, context) — 绘制文本
|
||
|
||
7. drawAttachmentsInContext: — 绘制图片附件
|
||
|
||
8. drawDecorativeElementsInContext: — 绘制装饰元素
|
||
├── 删除线
|
||
├── 下划线
|
||
└── 高亮背景
|
||
|
||
9. CGContextRestoreGState
|
||
```
|
||
|
||
### 8.2 图片绘制
|
||
|
||
```
|
||
遍历 attachments 数组:
|
||
对每个 attachment:
|
||
获取 image, position, size
|
||
CGContextDrawImage(context, imageRect, image.CGImage)
|
||
```
|
||
|
||
### 8.3 装饰元素绘制
|
||
|
||
**删除线**:
|
||
```
|
||
遍历 strikethroughRanges:
|
||
对每个 range:
|
||
找到相交的行
|
||
计算 startX, endX (CTLineGetOffsetForStringIndex)
|
||
y = line.origin.y + ascent * 0.3
|
||
CGContextStrokePath
|
||
```
|
||
|
||
**下划线**:
|
||
```
|
||
遍历 underlineRanges:
|
||
对每个 range:
|
||
找到相交的行
|
||
y = line.origin.y - descent
|
||
CGContextStrokePath (蓝色)
|
||
```
|
||
|
||
**高亮**:
|
||
```
|
||
遍历 highlightRanges:
|
||
对每个 range:
|
||
找到相交的行
|
||
计算高亮矩形 (descent 到 ascent)
|
||
CGContextFillRect (半透明黄色)
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 交互层
|
||
|
||
### 9.1 文本选择
|
||
|
||
```
|
||
characterIndexAtPoint:
|
||
遍历所有行
|
||
检查点是否在行的垂直范围内
|
||
使用 CTLineGetStringIndexForPosition 定位字符
|
||
|
||
selectTextInRange:
|
||
遍历所有行
|
||
找到与 range 相交的行
|
||
添加到 selectedLineIndices
|
||
通过 RACSubject 发送选择通知
|
||
```
|
||
|
||
### 9.2 搜索高亮
|
||
|
||
```
|
||
highlightSearchResults:
|
||
使用 NSString rangeOfString: 搜索
|
||
收集所有匹配范围
|
||
创建 highlightRanges (黄色半透明)
|
||
返回匹配数量
|
||
```
|
||
|
||
### 9.3 Hit Testing
|
||
|
||
```
|
||
stringIndexAtPoint:
|
||
遍历行 → 找到目标行
|
||
CTLineGetStringIndexForPosition → 字符索引
|
||
|
||
rectForCharacterAtIndex:
|
||
遍历行 → 找到包含索引的行
|
||
CTLineGetOffsetForStringIndex → x 坐标
|
||
返回 CGRect
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 附加功能
|
||
|
||
### 10.1 繁简转换
|
||
|
||
```
|
||
如果 book.language ∈ {zh-Hant, zh-TW, zh-HK}:
|
||
CFStringTransform(Hans → Latin → Hant)
|
||
```
|
||
|
||
### 10.2 免费试读截断
|
||
|
||
```
|
||
如果 isFreeTrial && result.length > trialCharacterLimit:
|
||
从限制位置向前搜索段落边界 (\n 或 U+2029)
|
||
截取子串
|
||
追加 "\n\n...\n\n" 指示器
|
||
```
|
||
|
||
### 10.3 附件注入
|
||
|
||
```
|
||
如果 insertArticleToolAttachment:
|
||
追加 NSTextAttachment {type: "articleTool"}
|
||
|
||
如果 insertBookChapterToolAttachment:
|
||
追加 NSTextAttachment {type: "bookChapterTool"}
|
||
|
||
如果 insertRecommendView:
|
||
追加 NSTextAttachment {type: "recommendView"}
|
||
```
|
||
|
||
### 10.4 页面背景生成
|
||
|
||
```
|
||
pageBackgroundImageAtRange:themeBgColor:
|
||
检查是否为章节开头页
|
||
创建 UIGraphicsImageContext
|
||
填充主题背景色
|
||
如果是章节开头: 绘制装饰边框
|
||
否则: 绘制边距参考线
|
||
缓存结果
|
||
```
|
||
|
||
### 10.5 图片缩放
|
||
|
||
```
|
||
resizedImageForImagePath:rect:position:sizePattern:darkMode:themeBgColor:
|
||
根据 sizePattern 计算目标尺寸:
|
||
"full" → 全宽
|
||
"half" → 半宽
|
||
"third" → 1/3 宽
|
||
"quarter" → 1/4 宽
|
||
如果 darkMode: 混合背景色
|
||
高质量插值缩放
|
||
缓存结果
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 性能优化
|
||
|
||
### 11.1 缓存策略
|
||
|
||
- **布局帧缓存**: NSCache, 最多 20 个 (DTCoreTextLayouter)
|
||
- **图片缓存**: NSCache, 最多 50 个 (WRCoreTextLayouter)
|
||
- **页面背景缓存**: NSCache, 按 range + 颜色键 (WRCoreTextLayouter)
|
||
- **内容高度缓存**: 布局帧级别 (DTCoreTextLayoutFrame)
|
||
|
||
### 11.2 懒加载
|
||
|
||
- CTTypesetter 按需创建 (createTypesetter)
|
||
- CTFramesetter 按需创建 (createFramesetter)
|
||
- 行数据按需提取 (extractLines)
|
||
- 字形数据按需提取 (extractGlyphs)
|
||
|
||
### 11.3 线程安全
|
||
|
||
所有核心类使用 NSLock 保护：
|
||
- DTCoreTextLayouter._lock
|
||
- DTCoreTextLayoutFrame._lock
|
||
- DTCoreTextLayoutLine._lock
|
||
- DTCoreTextGlyphRun._lock
|
||
- WRCoreTextLayouter._layoutLock
|
||
- WRCoreTextLayoutFrame._frameLock
|
||
|
||
### 11.4 增量更新
|
||
|
||
- attributedString 变化时标记 typesetterDirty
|
||
- 仅在下次访问时重建 typesetter
|
||
- 布局帧缓存自动失效
|
||
|
||
---
|
||
|
||
## 12. 数据流总结
|
||
|
||
```
|
||
EPUB 文件
|
||
│
|
||
├─ container.xml → OPF 路径
|
||
├─ content.opf → manifest + spine + metadata
|
||
├─ toc.ncx → 目录树
|
||
└─ *.xhtml → 章节内容
|
||
│
|
||
▼
|
||
XHTML 字符串
|
||
│ (繁简转换)
|
||
▼
|
||
CSS 级联合并
|
||
│ (5 层合并)
|
||
▼
|
||
DTHTMLAttributedStringBuilder
|
||
│ (SAX 解析 + DOM 构建 + 样式应用)
|
||
▼
|
||
DTHTMLElement 树
|
||
│ (后处理: 图片/链接/自定义属性)
|
||
▼
|
||
NSAttributedString
|
||
│ (包含标准 + 自定义属性)
|
||
▼
|
||
CTTypesetter
|
||
│ (字形分析 + 行断点计算)
|
||
▼
|
||
WRCoreTextLayoutFrame[]
|
||
│ (每帧 = 一页, 含 avoidPageBreakInside)
|
||
▼
|
||
CGContext 绘制
|
||
│ (文本 + 图片 + 装饰)
|
||
▼
|
||
屏幕像素
|
||
```
|