253 lines
12 KiB
Markdown
253 lines
12 KiB
Markdown
# RDReaderView 功能实现逻辑
|
||
|
||
## 1. 范围与目标
|
||
|
||
- 代码范围：`Sources/RDReaderView/` 根目录（6 个 Swift 文件）
|
||
- 目标：说明分页阅读器容器如何管理四种显示模式、DataSource/Delegate 协议、翻页交互、工具栏动画、双屏适配和 RTL 支持。
|
||
- 主链路关键词：`RDReaderDataSource -> reloadData -> DisplayType 切换 -> 翻页/滚动 -> RDReaderDelegate.pageNum -> 工具栏显隐`。
|
||
|
||
## 2. 关键对象职责
|
||
|
||
### 2.1 核心容器 `RDReaderView`
|
||
|
||
- 文件：`Sources/RDReaderView/RDReaderView.swift`（~717 行）
|
||
- 入口方法：`reloadData()`
|
||
- 职责：
|
||
- 管理四种显示模式的视图层级切换
|
||
- 持有 `UIPageViewController`（pageCurl 模式）或 `UICollectionView`（滚动模式）
|
||
- 处理点击手势（左/中/右三区域）
|
||
- 管理工具栏（topToolView / bottomToolView）的显示/隐藏动画
|
||
- 检测横竖屏变化并触发重新布局
|
||
- 管理双屏配对逻辑（含封面页处理）
|
||
- RTL 语言方向支持
|
||
|
||
### 2.2 自定义布局 `RDReaderFlowLayout`
|
||
|
||
- 文件：`Sources/RDReaderView/RDReaderFlowLayout.swift`（~387 行）
|
||
- 职责：
|
||
- 继承 `UICollectionViewFlowLayout`，为三种滚动模式提供布局计算
|
||
- 水平滚动：全屏宽 item，pagingEnabled
|
||
- 垂直滚动：可变高度 item，累加计算
|
||
- 水平覆盖滚动：zIndex 分层 + 阴影效果模拟深度
|
||
- 封面感知帧计算：封面页全屏宽，后续页面两两配对半屏宽
|
||
|
||
### 2.3 内容 Cell `RDReaderContentCell`
|
||
|
||
- 文件：`Sources/RDReaderView/RDReaderContentCell.swift`（~37 行）
|
||
- 职责：
|
||
- `UICollectionViewCell` 子类，作为内容视图的薄壳宿主
|
||
- `containerView` 属性 setter 自动移除旧视图、添加新视图
|
||
- `layoutSubviews` 将 containerView 填满 contentView.bounds
|
||
|
||
### 2.4 页面子控制器 `RDReaderPageChildViewController`
|
||
|
||
- 文件：`Sources/RDReaderView/RDReaderPageChildViewController.swift`（~65 行）
|
||
- 职责：
|
||
- 仅用于 pageCurl 模式，作为 `UIPageViewController` 的子控制器
|
||
- 持有 `contentView: UIView?` 和 `pageNum: Int`
|
||
- `contentView` didSet 在 view 已加载时自动调用 `installContentView()`
|
||
|
||
### 2.5 手势控制器 `RDReaderGestureController`
|
||
|
||
- 文件：`Sources/RDReaderView/RDReaderGestureController.swift`（~42 行）
|
||
- 职责：
|
||
- 当前为占位组件，存储 topToolView / bottomToolView 引用
|
||
- 实际手势逻辑在 `RDReaderView.tapCenter()` 中实现
|
||
|
||
### 2.6 URL 入口 `RDURLReaderController`
|
||
|
||
- 文件：`Sources/RDReaderView/RDURLReaderController.swift`（~105 行）
|
||
- 职责：
|
||
- 最简入口：传入 URL 即可打开书籍
|
||
- `.epub` 扩展名 → 创建 `RDEPUBReaderController(epubURL:configuration:)`
|
||
- 其他扩展名 → 使用 `RDPlainTextBookBuilder` 构建 `RDEPUBTextBook`，然后创建 `RDEPUBReaderController(textBook:bookIdentifier:title:textFileURL:configuration:)`
|
||
- 分页失败时回退到纯 `UITextView` 展示（尝试 UTF-8 → GBK → GB2312 解码）
|
||
- 导航栏标题设为文件名（去掉扩展名）
|
||
|
||
## 3. 主流程（代码级）
|
||
|
||
### 3.1 协议定义
|
||
|
||
**RDReaderDataSource**（数据供给）：
|
||
```swift
|
||
func pageCountOfReaderView(readerView: RDReaderView) -> Int
|
||
func pageContentView(readerView: RDReaderView, pageNum: Int, containerView: UIView?) -> UIView
|
||
func pageIdentifier(readerView: RDReaderView, pageNum: Int) -> String?
|
||
@objc optional func topToolView(readerView: RDReaderView) -> UIView?
|
||
@objc optional func bottomToolView(readerView: RDReaderView) -> UIView?
|
||
```
|
||
|
||
**RDReaderDelegate**（事件回调）：
|
||
```swift
|
||
func pageNum(readerView: RDReaderView, pageNum: Int)
|
||
@objc optional func readerViewOrientationWillChange(readerView: RDReaderView, isLandscape: Bool)
|
||
```
|
||
|
||
### 3.2 初始化与数据加载
|
||
|
||
1. 调用方创建 `RDReaderView`，设置 `dataSource` 和 `delegate`。
|
||
2. 调用 `reloadData()`。
|
||
3. `reloadData` 内部调用 `switchReaderDisplayType(currentDisplayType)` 重建视图层级。
|
||
4. 同时从 `dataSource` 获取 `topToolView` 和 `bottomToolView` 并添加到视图层级。
|
||
|
||
### 3.3 四种显示模式切换
|
||
|
||
**pageCurl 模式**：
|
||
- 创建 `UIPageViewController`（transitionStyle: .pageCurl）
|
||
- 通过 `attachPageViewControllerIfNeeded()` 添加为父 VC 的 child VC
|
||
- 横屏双页时重建 `UIPageViewController`（spineLocation: .mid, isDoubleSided: true）
|
||
- RTL 时翻转导航方向
|
||
|
||
**horizontalScroll 模式**：
|
||
- 移除 pageViewController，插入 `UICollectionView`
|
||
- `RDReaderFlowLayout` 设置 scrollDirection = .horizontal, isPagingEnabled = true
|
||
- itemSize 宽度 = 容器宽度 / pagesPerScreen
|
||
- RTL 时对 collectionView 做 `scaleX: -1` 翻转，cell contentView 再翻转回来
|
||
|
||
**verticalScroll 模式**：
|
||
- 同一 collectionView，scrollDirection = .vertical, isPagingEnabled = false
|
||
- 页面高度可变，通过 `RDReaderFlowLayoutDataSoure.heigtOfVerticalScrollPage` 查询
|
||
- collectionViewContentSize 为所有页面高度之和
|
||
|
||
**horizontalCoverScroll 模式**：
|
||
- 水平分页，但带封面滑动动画
|
||
- `layoutAttributesForElements` 中：
|
||
- 仅计算当前页附近的窄窗口内的 item attributes
|
||
- 当前页之前的 item zIndex = -1，当前及之后 zIndex = 1
|
||
- 顶层页面边缘添加阴影效果
|
||
|
||
### 3.4 翻页交互
|
||
|
||
**点击手势**（`tapAction(tap:)`）：
|
||
- 屏幕分为左 1/3、中 1/3、右 1/3 三个区域
|
||
- 左区域：工具栏隐藏时翻上一页（RTL 时翻下一页）；工具栏显示时触发 `tapCenter()`
|
||
- 中区域：始终触发 `tapCenter()`
|
||
- 右区域：工具栏隐藏时翻下一页（RTL 时翻上一页）；工具栏显示时触发 `tapCenter()`
|
||
|
||
**goNextPage() / goPreviousPage()**：
|
||
- 双页模式使用 `adjacentDualPage(from:forward:)` 计算目标页
|
||
- 单页模式直接 +1 / -1
|
||
- 调用 `transitionToPage(pageNum:animated:true)` 执行跳转
|
||
|
||
**工具栏切换**（`tapCenter()`）：
|
||
- 显示时：topToolView 从上方滑入，bottomToolView 从下方滑入（CGAffineTransform translationY）
|
||
- 隐藏时：反向动画
|
||
- 工具栏显示期间禁用 collectionView 和 pageViewController 的用户交互
|
||
|
||
### 3.5 双页配对逻辑
|
||
|
||
**`dualPagePair(for pageNum:)`** 返回 `(left: Int, right: Int?)`：
|
||
- 有封面页：封面页 → (coverIndex, nil)；封面后的页面两两配对（coverIndex+1 与 coverIndex+2，coverIndex+3 与 coverIndex+4...）
|
||
- 无封面页：标准偶奇配对（0+1, 2+3, 4+5...）
|
||
|
||
**空白哨兵页**：
|
||
- `blankPageNum = Int.max`，`blankEndPageNum = Int.max - 1`
|
||
- 仅用于 pageCurl 双页模式，填充封面页独占或总页数为奇数时的右侧空白
|
||
|
||
### 3.6 横竖屏变化处理
|
||
|
||
1. `layoutSubviews()` 检测 `previousIsLandscape` 与当前 `isLandscape` 的变化
|
||
2. 异步调用 `orientationChanged(isNowLandscape:)` 避免嵌套布局
|
||
3. 通知 delegate `readerViewOrientationWillChange`
|
||
4. 更新 `layout.isLandscapeDualPage` 和 `layout.coverPageIndex`
|
||
5. pageCurl 模式：重建 UIPageViewController（spineLocation 不可变）并跳转到保存的页面
|
||
6. 滚动模式：invalidate layout，reload data，强制布局，无动画滚动到保存的 offset
|
||
|
||
### 3.7 CollectionView DataSource / Layout Delegate
|
||
|
||
**cellForItemAt**：
|
||
- 用 `dataSource.pageIdentifier` 获取重用标识符
|
||
- 出队 `RDReaderContentCell`
|
||
- 调用 `dataSource.pageContentView(pageNum:containerView:)` 传入 cell 已有的 containerView 以便复用
|
||
- RTL 水平模式对 cell.contentView 做 `scaleX: -1` 翻转
|
||
|
||
**pageNum(flowLayout:pageIndex:)**：
|
||
- 布局检测到滚动中页面变化时更新 `currentPage`
|
||
|
||
## 4. 异常与边界处理
|
||
|
||
- `currentPage` 初始值为 -1，首次设置时 delegate 会收到回调
|
||
- 空白哨兵页（Int.max / Int.max-1）在 delegate 回调中被过滤，不会通知到外部
|
||
- pageCurl 模式下 collectionView 的 DataSource 方法存在但不被调用（collectionView 已从视图层级移除）
|
||
- 横竖屏变化时异步处理避免嵌套 layoutSubviews
|
||
- `UIView.ss_superViewController` 通过响应链查找最近的父 VC，用于正确挂载 pageViewController
|
||
|
||
## 5. 数据结构与字段映射
|
||
|
||
### 5.1 显示模式
|
||
|
||
```swift
|
||
RDReaderView.DisplayType
|
||
├── .pageCurl // UIPageViewController 翻页效果
|
||
├── .horizontalScroll // UICollectionView 水平滚动
|
||
├── .verticalScroll // UICollectionView 垂直滚动
|
||
└── .horizontalCoverScroll // UICollectionView 水平覆盖动画
|
||
```
|
||
|
||
### 5.2 翻页方向
|
||
|
||
```swift
|
||
RDReaderView.PageDirection
|
||
├── .leftToRight // 默认，中文/英文
|
||
└── .rightToLeft // 日文漫画等
|
||
```
|
||
|
||
### 5.3 关键公开属性
|
||
|
||
| 属性 | 类型 | 默认值 | 用途 |
|
||
|------|------|--------|------|
|
||
| `dataSource` | `RDReaderDataSource?` | nil | 弱引用数据源 |
|
||
| `delegate` | `RDReaderDelegate?` | nil | 弱引用事件监听 |
|
||
| `currentDisplayType` | `DisplayType` | .pageCurl | 当前显示模式 |
|
||
| `toolViewAnimationDuration` | `TimeInterval` | 0.3 | 工具栏动画时长 |
|
||
| `landscapeDualPageEnabled` | `Bool` | false | 横屏双页 |
|
||
| `pageDirection` | `PageDirection` | .leftToRight | 翻页方向 |
|
||
| `coverPageIndex` | `Int?` | nil | 封面页索引 |
|
||
| `currentPage` | `Int` | -1 | 当前页码（didSet 通知 delegate） |
|
||
|
||
### 5.4 计算属性
|
||
|
||
- `pagesPerScreen: Int`：横屏 + 双页启用 + 非垂直滚动 → 2；否则 1
|
||
- `isLandscape: Bool`：`bounds.width > bounds.height`
|
||
- `hasCoverPage: Bool`：`coverPageIndex != nil`
|
||
|
||
## 6. 视图绑定规则
|
||
|
||
- 规则 1：内容视图通过 `register(contentView:contentViewWithReuseIdentifier:)` 注册，内部注册对应的 `RDReaderContentCell`
|
||
- 规则 2：Cell 复用两层：`RDReaderContentCell`（UICollectionViewCell）宿主 `containerView`（实际内容视图）
|
||
- 规则 3：`pageContentView(readerView:pageNum:containerView:)` 的 `containerView` 参数是从回收 cell 中取出的旧视图，允许数据源复用或重新渲染
|
||
- 规则 4：工具栏通过 `topToolView` / `bottomToolView` 协议方法提供，由 `RDReaderView` 管理显隐动画
|
||
- 规则 5：RTL 支持通过 collectionView `scaleX: -1` + cell contentView `scaleX: -1` 实现，文本正确显示
|
||
|
||
## 7. 通知协作与回调机制
|
||
|
||
- 无 NotificationCenter 使用
|
||
- 所有通信通过协议和闭包：
|
||
- `RDReaderDataSource`：数据供给（页数、内容视图、标识符、工具栏）
|
||
- `RDReaderDelegate`：事件通知（页面变化、横竖屏即将变化）
|
||
- `RDReaderFlowLayoutDelegate`：布局检测到页面变化时通知
|
||
- `RDReaderFlowLayoutDataSoure`：垂直滚动时提供每页高度
|
||
|
||
## 8. 联调与排查建议
|
||
|
||
- 排查 1：页面不显示
|
||
- 确认 `dataSource` 已设置且 `reloadData()` 已调用
|
||
- 确认 `pageCountOfReaderView` 返回值 > 0
|
||
- 确认 `pageContentView(pageNum:containerView:)` 返回非 nil 视图
|
||
- 排查 2：翻页无反应
|
||
- 确认工具栏是否正在显示（工具栏显示时左右点击变为切换工具栏）
|
||
- 确认 `currentPage` 的 didSet 是否被触发
|
||
- pageCurl 模式检查 `UIPageViewController` 的 dataSource 方法是否正确返回
|
||
- 排查 3：横屏双页异常
|
||
- 确认 `landscapeDualPageEnabled` 是否为 true
|
||
- pageCurl 模式需重建 UIPageViewController（spineLocation 不可变）
|
||
- 检查 `dualPagePair` 配对逻辑和空白哨兵页处理
|
||
- 排查 4：RTL 方向错误
|
||
- 确认 `pageDirection` 是否设为 `.rightToLeft`
|
||
- 水平滚动模式检查 collectionView 是否做了 `scaleX: -1`
|
||
- pageCurl 模式检查导航方向是否翻转
|
||
- 排查 5：工具栏动画异常
|
||
- 确认 `topToolView` / `bottomToolView` 是否通过 dataSource 正确提供
|
||
- 检查 `toolViewAnimationDuration` 值
|
||
- 确认工具栏显示期间用户交互是否被正确禁用/恢复
|