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>
This commit is contained in:
shen
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
86e6922f7b
commit
22bb86959c
@@ -0,0 +1,114 @@
|
||||
# Phase 8: 图片显示修复 - Context
|
||||
|
||||
**Gathered:** 2026-05-23
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
修复 native text 渲染路径（DTCoreText）中三类图片的尺寸适配问题：
|
||||
1. `qrbodyPic` 容器中的独立图片 — 当前无特殊处理，高度可能溢出页面
|
||||
2. 封面图片 (`frontCover`) — 当前用屏幕尺寸基准，需统一到最大尺寸逻辑
|
||||
3. 脚注图片 (`qqreader-footnote`) — 当前三处不一致的尺寸处理
|
||||
|
||||
核心目标：对齐 WXRead 的 `_WRPostProcessElementTree` 逻辑，对所有图片附件统一执行最大尺寸限制。
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## 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 计划
|
||||
|
||||
</decisions>
|
||||
|
||||
<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>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- 用户明确要求"等比缩放，让图片都能显示全"——图片不能被裁剪，必须完整显示
|
||||
- 用户明确要求脚注图片"显示的和文本的高度一样，高度不能超过文本的高度"
|
||||
- WXRead 的实现是参考标准，但不需要 100% 复制——只对齐图片尺寸逻辑
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- 图片缓存机制（属于 08-01 计划）
|
||||
- `wr-vertical-center-style` 垂直居中语义的完整实现（属于 Phase 7 已完成的工作）
|
||||
- 图片点击放大/查看大图功能（新能力，不属于当前范围）
|
||||
- 代码块/表格被粗暴截断（QUAL-02 子需求）— 本次聚焦图片尺寸修复，代码块/表格截断问题留待后续分页质量迭代处理
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 8-图片显示修复*
|
||||
*Context gathered: 2026-05-23*
|
||||
Reference in New Issue
Block a user