ReadViewSDK/Doc/WXRead/decompiled-doc.md

WXRead/decompiled 逆向代码说明

概述

此目录包含从读书 (WeRead) iOS 客户端二进制逆向还原的头文件和实现代码。共 44 个文件（22 对 .h/.m），分为三大模块：

1. 阅读器核心 — 阅读控制器、页面渲染、排版引擎、EPUB 解析
2. 标注系统 — 划线、高亮、书签、想法、Pencil 手写笔记
3. DTCoreText 定制 — 基于开源 DTCoreText 库的读书私有定制

---

架构总览

WRReaderViewController (阅读器主控制器)
├── WRPageViewController (翻页控制器, 支持 curl/slide/fade/none)
│   └── WRPageView (页面渲染视图, CoreText 直接绘制)
│       └── WRCoreTextLayoutFrame (单页排版帧)
│           └── WRCoreTextLayoutLine (单行排版)
├── WREpubParser (EPUB 文件解析)
├── WREpubTypesetter (XHTML → NSAttributedString 排版)
│   └── DTHTMLAttributedStringBuilder (HTML DOM → 属性字符串)
│       └── DTHTMLElement (DOM 节点)
├── WRChapterData (章节数据模型)
├── WRChapterPageCount (分页计算器)
├── WRCoreTextLayouter (CoreText 排版器)
└── WRBookmark / WRPageHighlight / WRPageMark / WRPageUnderline (标注模型)

---

阅读器核心模块

WRReaderViewController

阅读器的主入口控制器，431 个方法，管理阅读状态的完整生命周期。

核心职责：

• 管理 WRReadingProgress（阅读进度：章节索引、页码、字符偏移、滚动位置、阅读百分比）
• 章节导航：gotoChapterIdx:position:positionOfFile:、jumpReadingToNextChapter、jumpReadingToPreChapter
• 页面渲染：renderPageView:progressData:source: — 获取/计算章节数据、分页、创建/更新 WRPageView
• 排版重排：recomposeCurrentPageViewWithSource: — 字号/行距/主题变更后触发
• 进度持久化：_saveReadingProgressAndIsAsync:
• 支持涂鸦模式 (doodle mode) 和自动阅读 (auto-read)
• 通过 WRReaderViewControllerDelegate 回调通知外部进度变化和退出

WRPageViewController

自定义的翻页控制器，支持四种翻页动画：

枚举值	样式	说明
WRPageFlippingStyleCurl	纸张翻页	基于 UIPageViewController 的 curl 效果
WRPageFlippingStyleSlide	水平滑动	UIScrollView 驱动的滑动翻页
WRPageFlippingStyleFade	淡入淡出	交叉渐变
WRPageFlippingStyleNone	无动画	瞬间切换

关键特性：

• 内部封装 UIPageViewController，提供 WRPageViewControllerDelegate / WRPageViewControllerDataSource 协议
• 包含 3 个故障修补方法，处理 Apple UIPageViewController 的已知崩溃：
  • detectNavigationDirectionCrashWithPageViewController: — 检测导航方向崩溃
  • patchNavigationDirectionFault — 修复导航方向状态不一致
  • patchNoViewControllerManagingPageViewFault — 修复子 VC 丢失
  • patchUIPageCurlFault — 修复快速翻页时的动画故障

WRPageView

单页渲染视图，继承 UIView，通过 CoreText 的 drawRect: 直接绘制文本，不使用 UILabel 或 UITextView。

核心绘制：

• drawInContext:withData:size:inRect:position: — 将文本和行内图片直接绘制到 CGContext
• 通过 CTLineGetStringIndexForPosition 进行 CoreText 级别的坐标点击测试

UI 覆盖层：

• 章节标题头 (headerLabel)、背景图片 (backgroundImageView)
• 加载指示器 (activityIndicator)、加载进度条 (loadingProgressView)
• 状态提示 (statusLabel)、重试按钮 (retryButton)
• 分享按钮、书签按钮、字号调节按钮
• 好友想法按钮 (friendReviewsButton)

文本选区：

• stringIndexForPoint: / lineRangeForStringIndex: — CoreText 坐标与字符索引转换
• isSelecting / selectedRange — 选区状态
• clearSelection — 清除选区

---

EPUB 解析与排版

WREpubParser

EPUB 文件解析器，处理完整的 EPUB 结构：

解析流程： container.xml → content.opf → spine → 章节文件

主要 API：

• initWithFilePath:book: — 初始化
• parse: — 执行解析，返回 YES/NO
• parseContainerXML: — 解析 container.xml 获取 OPF 路径
• parseOPFAtRelativePath:error: — 解析 content.opf，填充章节列表和资源映射
• parseNCX: — 解析 toc.ncx 目录树
• contentForChapterAtIndex:error: — 读取单章 XHTML 内容
• absolutePathForResource: — 将相对资源路径解析为绝对路径

错误码：

错误码	含义
-1000	文件未找到
-1001	container.xml 解析失败
-1002	OPF 解析失败
-1003	NCX 解析失败
-1004	spine 为空
-1005	章节加载失败
-1006	解密失败

WREpubTypesetter

EPUB 排版器，XHTML → NSAttributedString 的转换核心。全部为类方法，无需实例化。

主入口方法：

+ (NSAttributedString *)attributeStringWithFilePath:priority:
    insertArticleToolAttachment:insertBookChapterToolAttachment:
    insertRecommendView:book:chapter:pageFlippingStyle:
    renderErrorReason:isStyleFileNotFound:options:

处理流程：

1. 加载并级联合并 CSS（用户设置 > EPUB 内嵌 > 默认样式）
2. 将 XHTML + 合并后的 CSS 喂入 DTHTMLAttributedStringBuilder
3. 遍历生成的元素树，修补图片、链接、自定义属性
4. 应用用户排版偏好（字体、行距、主题）
5. 可选截断用于免费试读预览

自定义 CSS 属性：

• WREpubTypesetterVerticalCenterStyleAttribute — 行内元素垂直居中（wr-vertical-center-style）
• WREpubTypesetterPageRelateAttribute — 跨页关联标记（weread-page-relate）

翻译渲染错误上报：

• tryReportTranslationError: — 双语（原文 + 翻译）渲染异常时上报分析

WREpubPositionConverter

文件位置与字符位置的双向转换器。用于书签同步和阅读进度追踪。

核心概念： 将 (fileIndex, row, column) 三元组映射为全局字符偏移量。

主要 API：

• initWithFilePaths:attributedStrings:offset:isContainIntroFlyleaf: — 初始化
• initIndices — 构建内部索引表（调用前不能执行转换）
• indicesInFile:forRowColumnPairs:stringIndices: — 行/列 → 字符索引
• stringRangeFromFileRange: — 文件内范围 → 全局字符串范围
• totalCharacterCount — 全书总字符数
• fileIndexForCharacterPosition: — 全局位置 → 文件索引
• localOffsetInFileAtIndex:forGlobalPosition: — 全局位置 → 文件内偏移

---

分页与布局

WRChapterPageCount

章节分页计算器。管理每页的 NSRange。

关键属性：

• pageRanges — 每页的字符范围数组 (NSValue-wrapped NSRange)
• totalPages — 总页数

关键方法：

• currentCacheKeyWithBookId: — 生成缓存键（编码书 ID + 当前排版设置，设置变更则失效）
• rangeValueWithPageInfo: — 从服务端分页数据提取范围
• rangeForPageAtIndex: / pageIndexForCharacterIndex: — 页码 ↔ 字符位置
• recalculatePageRangesForAttributedString:drawingSize:margins: — 重算分页

WRCoreTextLayouter

读书封装的 CoreText 排版器，创建 CTTypesetter / CTFramesetter 并产出 WRCoreTextLayoutFrame 页面对象。

初始化：

• initWithAttributedString: / initWithAttributedString:config:
• WRCoreTextLayoutConfig 配置：frame 宽高、内边距、栏数、栏间距、孤行/寡行控制、连字符

排版 API：

• createTypesetter / createFramesetter / invalidateTypesetter
• layoutFrameWithRange:frame: — 单帧排版
• layoutFramesForPageSize: — 全文分页排版
• numberOfPagesForPageSize: / rangeForPageAtIndex:pageSize: — 分页查询
• pageBackgroundImageAtRange:themeBgColor: — 页面背景图
• resizedImageForImagePath: — 图片缩放适配

WRCoreTextLayoutFrame

单页排版帧，封装 CTFrame，管理 WRCoreTextLayoutLine 行数组。

核心功能：

• 文本绘制：drawInContext:image:size:inRect:position:（含 CTFrameDraw + 图片附件 + 装饰元素）
• 分栏支持：numberOfColumns / columnGap
• 跨页避让：avoidPageBreakInsideByRemovingLastLinesIfNeeded — CSS avoid-page-break-inside 实现
• 点击测试：characterIndexAtPoint: / lineIndexAtPoint: / rectForCharacterAtIndex:
• 选区操作：selectedText / selectedRanges / selectTextInRange: / clearSelection
• 搜索高亮：highlightSearchResults: / clearSearchHighlights
• 装饰元素：删除线范围、下划线范围、高亮范围、链接范围
• 响应式更新：通过 RACSubject (ReactiveObjC) 发出布局变更通知

---

标注系统

WRBookmark

书签/标注的数据模型，支持 5 种类型：

类型	说明
WRBookmarkTypeHighlight	彩色高亮
WRBookmarkTypeUnderline	下划线
WRBookmarkTypeMark	页面书签（折角）
WRBookmarkTypeNote	文字笔记
WRBookmarkTypePencil	Apple Pencil 手绘

关键属性： bookmarkId、bookId、chapterUid、chapterOffset、markText、startPos/endPos、colorStyle、anchorId、rangeKey、syncKey

持久化： toDictionary / fromDictionary、toJSONData / fromJSONData

工厂方法：

• bookmarkWithBookId:chapterUid:offset:text:type:
• highlightWithBookId:chapterUid:startPos:endPos:text:colorStyle:

WRPageHighlight

文本高亮标注模型。5 种预设颜色：黄、蓝、红、绿、紫。

方法：

• initWithBookId:chapterUid:startPos:endPos:text:color: — 创建高亮
• toBookmark — 转为 WRBookmark 进行持久化/同步
• uiColor — 返回渲染用 UIColor

WRPageUnderline

下划线标注模型。支持 4 种下划线样式：实线、虚线、波浪线、点线。

方法：

• toBookmark / fromBookmark: — 与 WRBookmark 双向转换
• underlinePathForRect: — 返回渲染用 UIBezierPath
• containsPosition: — 范围查询
• mergeWithUnderline: — 合并相邻下划线
• setNote: — 附加笔记

WRPageMark

页面书签（折角）模型。25 个方法，功能最丰富的标注类型。

关键特性：

• 支持 3 种展示模式：图标、列表、行内
• 关联标注：linkedHighlights / linkedUnderlines — 书签位置上附带的高亮和下划线
• 批量操作：marksSortedByPosition: / marksSortedByDate: / marksInChapter:fromMarks: / marksInRange:fromMarks:
• 序列化：toDictionary / fromDictionary、toJSONData / fromJSONData

WRReaderPencilNoteManager

Apple Pencil 手写笔记管理器。11 个类方法，全部为类方法调用。

支持 9 种画笔颜色/样式： 黑、灰、红、蓝、黄、绿、铅笔、钢笔、荧光笔

本地存储：

• drawingFileDirectory / drawingFilePathWithReviewItemId: — 文件路径管理
• writeDrawingDataToLocal: / writeDrawingToLocal: — 本地写入（支持 draft/published 状态）
• checkDrawingExistsWithReviewItemId: — 存在性检查
• deleteDrawingWithReviewItemId: / deleteAllReviewDrawings — 删除

云端同步：

• uploadPencilDrawing:colorStyle:onlyUploadImage:canRetry: — 上传绘制图片和数据到腾讯云 COS
• uploadPencilNoteData:suffix: — 上传 PKDrawing 序列化数据
• downloadDrawingDataFromCosWithUrl:desPath:callback: — 从 COS 下载

---

DTCoreText 定制模块

读书基于开源库 DTCoreText 做了大量私有定制。

DTHTMLAttributedStringBuilder

HTML DOM → NSAttributedString 的 SAX 风格解析构建器。WREpubTypesetter 的底层依赖。

WeRead 自定义属性键：

• DTPageBackgroundColorAttribute / DTPageBackgroundImageAttribute — 页面背景
• DTPageBreakAfterAttribute / DTPageBreakBeforeAttribute — 分页控制
• DTPageBreakInsideAvoidAttribute — 跨页避让
• DTPageRelateAttribute — 跨页关联
• DTHTMLVerticalCenterAttribute — 垂直居中
• DTHTMLTranslateTagAttribute — 翻译标签

DTHTMLElement

HTML 元素 DOM 节点。构建解析时的 DOM 树，每个节点可通过 attributedString 方法生成对应的属性字符串。

关键属性： tagName、parent/children、styleDictionary、isBlockElement、shouldAvoidPageBreakInside

DTCoreTextLayouter / DTCoreTextLayoutFrame / DTCoreTextLayoutLine / DTCoreTextGlyphRun

DTCoreText 的四层排版层次结构（与 WR 前缀版本功能对应，是底层实现）：

DTCoreTextLayouter (排版器, CTTypesetter 包装)
└── DTCoreTextLayoutFrame (排版帧, CTFrame 包装)
    └── DTCoreTextLayoutLine (排版行, CTLine 包装)
        └── DTCoreTextGlyphRun (字形运行, CTRun 包装)

• Layouter — 创建 CTTypesetter，产出 LayoutFrame，支持帧缓存
• LayoutFrame — 管理排版行数组，支持多栏、分页避让、点击测试、选区、搜索
• LayoutLine — 封装 CTLine，管理 GlyphRun 数组，提供排版指标（ascent/descent/leading/width）和点击测试
• GlyphRun — 封装 CTRun，管理字形（glyph）级别操作：位置、路径绘制、附件（图片）、字体属性、绘制方向

---

数据流

EPUB 文件 (.epub)
  ↓ WREpubParser.parse
解析 container.xml → content.opf → toc.ncx
  ↓ WREpubTypesetter.attributeStringWithFilePath
XHTML + CSS → DTHTMLAttributedStringBuilder → NSAttributedString
  ↓ WRCoreTextLayouter / WRChapterPageCount
分页排版 → [NSRange per page]
  ↓ WRPageView.drawInContext
CoreText 绘制到 CGContext
  ↓ WRPageViewController
翻页展示