shen 22bb86959c docs(08): create phase plans for image display fix and pagination cache

3 plans covering QUAL-01 through QUAL-04:
- 08-01: pagination cache key + wiring into rendering pipeline
- 08-02: unified 1080x1920 max-size for all images, footnote width-only fix
- 08-03: pagination timing instrumentation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-23 18:43:41 +08:00

6.0 KiB

Raw Blame History

Phase 8: 图片显示修复 - Context

Gathered: 2026-05-23 Status: Ready for planning

## Phase Boundary

修复 native text 渲染路径（DTCoreText）中三类图片的尺寸适配问题：

qrbodyPic 容器中的独立图片 — 当前无特殊处理，高度可能溢出页面
封面图片 (frontCover) — 当前用屏幕尺寸基准，需统一到最大尺寸逻辑
脚注图片 (qqreader-footnote) — 当前三处不一致的尺寸处理

核心目标：对齐 WXRead 的 _WRPostProcessElementTree 逻辑，对所有图片附件统一执行最大尺寸限制。

## Implementation Decisions

图片最大尺寸

D-01: 对所有图片附件统一执行最大尺寸限制 CGSizeMake(1080, 1920)
D-02: 超过最大宽度时等比缩放（与 WXRead _WRPostProcessElementTree 一致）
D-03: 实现位置：prepareHTMLElementForReaderRendering 中，在现有 footnote/cover 特殊处理之前，添加统一的最大尺寸限制逻辑

封面图片

D-04: 保持屏幕尺寸基准（UIScreen.main.bounds.insetBy(dx: 20, dy: 28)），但受统一最大尺寸 1080x1920 约束
D-05: 保持 configureCoverIfNeeded 的 UIImageView 专用路径不变
D-06: 封面图片仍通过 prepareHTMLElementForReaderRendering 中的 cover 分支处理，但需确保不超过统一最大尺寸

脚注图片

D-07: 对齐 WXRead：只设 width:1em，不设高度，让渲染器按原始宽高比自动计算
D-08: 移除 prepareHTMLElementForReaderRendering 中脚注的高度计算逻辑（pointSize * 0.54）
D-09: 移除 normalizeInlineAttachments 中的高度覆盖逻辑（pointSize * 0.14）
D-10: 保留 normalizeAttachmentHTMLMarkers 中的 CSS width:1em，移除 height:1em

qrbodyPic 图片

D-11: 不单独添加特殊处理逻辑，统一最大尺寸限制会隐式修复高度溢出问题
D-12: 保持现有 CSS 规则不变（max-width:100%; height:auto; display:block; margin:auto）

Claude's Discretion

具体实现细节（如是否需要自动添加 bodyPic 类、是否需要 wr-vertical-center-style 语义标记）由 planner 和 executor 决定
图片缓存策略不在本次讨论范围，属于 Phase 8 的 08-01 计划

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

WXRead 参考实现

Doc/WXRead/decompiled/WREpubTypesetter.m §672-701 — _WRPostProcessElementTree()：统一图片最大尺寸逻辑（1080x1920）、自动添加 bodyPic 类、设置 wr-vertical-center-style
Doc/WXRead/decompiled/WRCoreTextLayoutFrame.m §615-635 — drawCoverImage:inContext:rect:：封面图片等比缩放适配 frame
Doc/WXRead/decompiled/WRCoreTextLayouter.m §639-667 — targetSizeForPattern:rect:imageSize:：sizePattern 缩放逻辑
Doc/WXRead/resources/css/replace.css §91-103 — .bodyPic、.qrbodyPic、.qqreader-footnote 的 CSS 规则

ReadViewSDK 当前实现

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift §220-262 — prepareHTMLElementForReaderRendering：当前图片处理逻辑
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift §302-343 — replaceCSS()：当前图片 CSS 规则
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift §345-404 — normalizeAttachmentHTMLMarkers：HTML 预处理
Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift §217-282 — configureCoverIfNeeded 和 normalizeInlineAttachments
Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift §90-112 — dtOptions：DTMaxImageSize 配置

Demo 样本

ReadViewDemo/ReadViewDemo/book/宝山辽墓材料与释读_副本/OEBPS/Styles/stylesheets.css — 实际 EPUB 书籍的图片 CSS
ReadViewDemo/ReadViewDemo/book/宝山辽墓材料与释读_副本/OEBPS/Text/cover.xhtml — 封面 HTML 结构
ReadViewDemo/ReadViewDemo/book/宝山辽墓材料与释读_副本/OEBPS/Text/Chapter_5.xhtml — qrbodyPic 图片 HTML 结构

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

prepareHTMLElementForReaderRendering：已有 footnote 和 cover 的分类处理框架，可在此基础上添加统一最大尺寸逻辑
normalizeAttachmentHTMLMarkers：已有 HTML 正则替换基础设施，可复用于 qrbodyPic 的 HTML 预处理
replaceCSS()：已有图片 CSS 规则，可直接修改

Established Patterns

图片分类检测：通过 CSS class（qqreader-footnote、rd-front-cover-image）和文件名（note.png、cover.jpg）识别图片类型
DTTextAttachment API：originalSize（原始尺寸）、displaySize（显示尺寸）、verticalAlignment（垂直对齐）
HTML 正则替换：mergeHTMLAttributes + replaceMatches 模式用于 HTML 预处理

Integration Points

RDEPUBDTCoreTextRenderer.swift → willFlushCallback → prepareHTMLElementForReaderRendering：DTCoreText 渲染时的图片处理入口
RDEPUBTextContentView.swift → configureCoverIfNeeded：封面图片显示入口
RDEPUBTextContentView.swift → normalizeInlineAttachments：显示时的脚注图片处理入口

</code_context>

## Specific Ideas

用户明确要求"等比缩放，让图片都能显示全"——图片不能被裁剪，必须完整显示
用户明确要求脚注图片"显示的和文本的高度一样，高度不能超过文本的高度"
WXRead 的实现是参考标准，但不需要 100% 复制——只对齐图片尺寸逻辑

## Deferred Ideas

图片缓存机制（属于 08-01 计划）
wr-vertical-center-style 垂直居中语义的完整实现（属于 Phase 7 已完成的工作）
图片点击放大/查看大图功能（新能力，不属于当前范围）
代码块/表格被粗暴截断（QUAL-02 子需求）— 本次聚焦图片尺寸修复，代码块/表格截断问题留待后续分页质量迭代处理

Phase: 8-图片显示修复 Context gathered: 2026-05-23

6.0 KiB Raw Blame History Unescape Escape