4.5 KiB
4.5 KiB
Phase 7: WXRead 自定义属性闭环 - Research
Date: 2026-05-22 Phase: 7
Research Question
What do we need to know to plan the WXRead custom pagination-attribute closure well for the native text pipeline?
Current State
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift已经负责章节 HTML 预处理、CSS 分层注入、fragment marker 注入，以及normalizeReadingAttributes的统一属性收口。Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift当前只把 DTCoreText 产出的 attributed string 交给通用后处理，没有显式保留 WXRead 风格的分页语义。Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift目前只定义了rdPageBlockRange、rdPageBlockIndex、rdPageFragmentID、rdPageAttachmentKind四个原生属性键，缺少分页控制语义模型。Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift已经会消费 block/attachment 元数据，并在分页时输出breakReason、blockRange、attachmentKinds、diagnostics，但还不会消费avoidPageBreakInside、pageBreakBefore、pageBreakAfter、pageRelate这类显式语义。Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift的RDEPUBTextPageMetadata已经是页级元数据汇总点，适合继续承载块类型、附件语义、强制分页、分页诊断摘要。Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift会把分页结果提升为 chapter/page 模型，并生成诊断摘要，是把新语义暴露给 Demo、回归、后续 Phase 8 的最佳出口。Doc/WXRead/analysis/EPUB渲染管线详解.md与Doc/WXRead/analysis/DTCoreText自定义修改分析.md明确给出了目标语义集合：wr-vertical-center-style、weread-page-relate、avoidPageBreakInside、pageBreakBefore、pageBreakAfter，以及table / code / list / blockquote这类块分类。ReadViewDemo/Pods/DTCoreText/Core/Source/DTHTMLElement.*与DTHTMLAttributedStringBuilder.*是当前可复用的底层行为边界：现阶段更现实的是在现有 chapter preprocessing 和 attributed-string 后处理层增量接线，而不是直接重写 DTCoreText 私有实现。
What This Means
- Phase 7 的缺口不是“再造一个 renderer”，而是给现有 renderer 增加一套显式、可诊断、可分页消费的语义模型。
- 最稳妥的切入点是
RDEPUBTextRendererSupport，因为它已经同时掌握 HTML、CSS、attributed string、fragment marker 和统一后处理。 - 块分类和分页语义必须先在 attributed string 上变成稳定属性键，后面的 layouter / page metadata / demo 诊断才能复用同一份事实。
- 附件语义不能只保留“是不是图片”，还需要保留像
wr-vertical-center-style这样的消费值，否则 Phase 8 无法继续细化图片/附件规则。 avoidPageBreakInside、pageBreakBefore、pageBreakAfter不能停留在“记录下来”，它们至少要影响分页边界选择或诊断结果，否则闭环是不完整的。
Recommended Planning Shape
- Plan 07-01: 定义语义模型与属性键，把 HTML/CSS 中的分页相关语义稳定映射到 attributed string。
- Plan 07-02: 让分页器和页级元数据真正消费这些语义，尤其是块分类、强制分页、附件垂直居中与 avoid-break 规则。
- Plan 07-03: 把语义闭环暴露到 demo / 诊断 / 回归路径，确保复杂样本上可观察、可比对、可复现。
Technical Risks
- 如果语义提取分散在 renderer、layouter、UI 多处，Phase 8 会继续面对“同一规则多处解释”的漂移问题。
- DTCoreText 默认产物对自定义 CSS 属性并不天然保真，Phase 7 需要在 preprocessing 或 post-processing 层建立明确桥接策略。
avoidPageBreakInside与强制分页一旦直接改写分页边界，最容易引入 page offset 回归，因此必须把兼容契约和诊断一起规划进去。- 块分类如果只靠标签名静态猜测，遇到 EPUB 自带 class/style 变体时可能不稳定；计划里需要明确保守策略和可诊断回退。
Validation Implications
- 现有仓库没有独立测试靶，Phase 7 仍需依赖 simulator build/run 与 demo 日志证据。
- 验证重点必须覆盖三类证据：属性是否进入 attributed string、分页器是否消费、demo 是否能看见块类型/附件语义/分页原因。
- 复杂样本至少要覆盖代码块/表格/列表/引用块以及含图片附件章节，否则 ATTR-02 / ATTR-03 的闭环无法证明。