4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename RDReaderView -> RDEpubReaderView, update pod config and docs

Browse Source 
- Rename source module from RDReaderView to RDEpubReaderView
- Move all source files from Sources/RDReaderView/ to Sources/RDEpubReaderView/
- Update podspec: RDReaderView.podspec -> RDEpubReaderView.podspec
- Update Podfile, demo project, and CocoaPods config for new pod name
- Delete old RDReaderView pod support files from ReadViewDemo/Pods
- Add new RDEpubReaderView pod support files
- Update documentation (API ref, architecture, UML, conventions, etc.)
- Add FixedLayoutRotationTests
- Update .gitignore: exclude .DS_Store, manual unpack backups, _ssoft-output
This commit is contained in:
shenlei
2026-07-10 19:44:53 +09:00
parent d5a7755702
commit d7fcda345d
460 changed files with 38358 additions and 2300 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/ReaderView_CODE_REFERENCE.md
+92 -92
View File
@@ -6,54 +6,54 @@
## 1. 模块概述
`ReaderView` 是 ReadViewSDK 的**通用翻页容器层**，位于 EPUBUI 层之下。它提供与 EPUB 内容无关的页面展示、翻页动画、手势识别、页面预加载和双页布局能力。上层通过 `RDReaderPageProvider` 协议提供页面内容视图，ReaderView 负责容器管理和翻页调度。
`ReaderView` 是 ReadViewSDK 的**通用翻页容器层**，位于 EPUBUI 层之下。它提供与 EPUB 内容无关的页面展示、翻页动画、手势识别、页面预加载和双页布局能力。上层通过 `RDEpubReaderPageProvider` 协议提供页面内容视图，ReaderView 负责容器管理和翻页调度。
**文件清单（14 个 Swift 文件）：**
| 文件 | 核心类型 | 职责 |
|------|----------|------|
| `RDReaderView.swift` | `RDReaderView` | 主容器视图，协调所有子组件 |
| `RDReaderViewProtocols.swift` | 协议 + 枚举 | 数据源、代理、导航协议定义 |
| `RDReaderFlowLayout.swift` | `RDReaderFlowLayout` | UICollectionView 自定义布局 |
| `RDReaderGestureController.swift` | `RDReaderGestureController` | 手势控制器（预留） |
| `RDReaderContentCell.swift` | `RDReaderContentCell` | CollectionView 内容 Cell |
| `RDReaderPageChildViewController.swift` | `RDReaderPageChildViewController` | PageCurl 模式子 VC |
| `RDReaderView+PageCurl.swift` | Extension | UIPageViewController 数据源/代理 |
| `RDReaderView+CollectionView.swift` | Extension | UICollectionView 数据源/布局代理 |
| `RDReaderView+ContentAccess.swift` | Extension | 内容视图访问与复用 |
| `RDReaderView+ToolView.swift` | Extension | 工具栏安装与动画 |
| `Paging/RDReaderPagingController.swift` | `RDReaderPagingController` | 翻页状态机 |
| `Paging/RDReaderPreloadController.swift` | `RDReaderPreloadController` | 页面预加载与缓存 |
| `Paging/RDReaderSpreadResolver.swift` | `RDReaderSpreadResolver` | 双页展开计算 |
| `Paging/RDReaderTapRegionHandler.swift` | `RDReaderTapRegionHandler` | 点击区域判定 |
| `RDEpubReaderView.swift` | `RDEpubReaderView` | 主容器视图，协调所有子组件 |
| `RDEpubReaderViewProtocols.swift` | 协议 + 枚举 | 数据源、代理、导航协议定义 |
| `RDEpubReaderFlowLayout.swift` | `RDEpubReaderFlowLayout` | UICollectionView 自定义布局 |
| `RDEpubReaderGestureController.swift` | `RDEpubReaderGestureController` | 手势控制器（预留） |
| `RDEpubReaderContentCell.swift` | `RDEpubReaderContentCell` | CollectionView 内容 Cell |
| `RDEpubReaderPageChildViewController.swift` | `RDEpubReaderPageChildViewController` | PageCurl 模式子 VC |
| `RDEpubReaderView+PageCurl.swift` | Extension | UIPageViewController 数据源/代理 |
| `RDEpubReaderView+CollectionView.swift` | Extension | UICollectionView 数据源/布局代理 |
| `RDEpubReaderView+ContentAccess.swift` | Extension | 内容视图访问与复用 |
| `RDEpubReaderView+ToolView.swift` | Extension | 工具栏安装与动画 |
| `Paging/RDEpubReaderPagingController.swift` | `RDEpubReaderPagingController` | 翻页状态机 |
| `Paging/RDEpubReaderPreloadController.swift` | `RDEpubReaderPreloadController` | 页面预加载与缓存 |
| `Paging/RDEpubReaderSpreadResolver.swift` | `RDEpubReaderSpreadResolver` | 双页展开计算 |
| `Paging/RDEpubReaderTapRegionHandler.swift` | `RDEpubReaderTapRegionHandler` | 点击区域判定 |
---
## 2. 协议定义（RDReaderViewProtocols.swift）
## 2. 协议定义（RDEpubReaderViewProtocols.swift）
### 2.1 RDReaderDataSource（旧版数据源，已废弃）
### 2.1 RDEpubReaderDataSource（旧版数据源，已废弃）
```swift
@objc public protocol RDReaderDataSource: NSObjectProtocol {
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?
@objc public protocol RDEpubReaderDataSource: NSObjectProtocol {
func pageCountOfReaderView(readerView: RDEpubReaderView) -> Int
func pageContentView(readerView: RDEpubReaderView, pageNum: Int, containerView: UIView?) -> UIView
func pageIdentifier(readerView: RDEpubReaderView, pageNum: Int) -> String?
@objc optional func topToolView(readerView: RDEpubReaderView) -> UIView?
@objc optional func bottomToolView(readerView: RDEpubReaderView) -> UIView?
}
```
> 向后兼容保留，新代码应使用 `RDReaderPageProvider`。
> 向后兼容保留，新代码应使用 `RDEpubReaderPageProvider`。
### 2.2 RDReaderPageProvider（推荐数据源）
### 2.2 RDEpubReaderPageProvider（推荐数据源）
```swift
@objc public protocol RDReaderPageProvider: NSObjectProtocol {
func numberOfPages(in readerView: RDReaderView) -> Int
func readerView(_ readerView: RDReaderView, viewForPageAt index: Int, reusableView: UIView?) -> UIView
@objc optional func pageIdentifier(in readerView: RDReaderView, index: Int) -> String?
@objc optional func readerViewTopChrome(_ readerView: RDReaderView) -> UIView?
@objc optional func readerViewBottomChrome(_ readerView: RDReaderView) -> UIView?
@objc public protocol RDEpubReaderPageProvider: NSObjectProtocol {
func numberOfPages(in readerView: RDEpubReaderView) -> Int
func readerView(_ readerView: RDEpubReaderView, viewForPageAt index: Int, reusableView: UIView?) -> UIView
@objc optional func pageIdentifier(in readerView: RDEpubReaderView, index: Int) -> String?
@objc optional func readerViewTopChrome(_ readerView: RDEpubReaderView) -> UIView?
@objc optional func readerViewBottomChrome(_ readerView: RDEpubReaderView) -> UIView?
}
```
@@ -65,31 +65,31 @@
| `readerViewTopChrome(_:)` | 返回顶部工具栏视图 |
| `readerViewBottomChrome(_:)` | 返回底部工具栏视图 |
### 2.3 RDReaderDelegate
### 2.3 RDEpubReaderDelegate
```swift
@objc public protocol RDReaderDelegate: NSObjectProtocol {
func pageNum(readerView: RDReaderView, pageNum: Int)
@objc optional func readerViewOrientationWillChange(readerView: RDReaderView, isLandscape: Bool)
@objc public protocol RDEpubReaderDelegate: NSObjectProtocol {
func pageNum(readerView: RDEpubReaderView, pageNum: Int)
@objc optional func readerViewOrientationWillChange(readerView: RDEpubReaderView, isLandscape: Bool)
}
```
### 2.4 RDReaderPageNavigating
### 2.4 RDEpubReaderPageNavigating
```swift
public protocol RDReaderPageNavigating: AnyObject {
public protocol RDEpubReaderPageNavigating: AnyObject {
var currentPage: Int { get }
func reloadPages()
func transition(to page: Int, animated: Bool)
}
```
`RDReaderView` 遵循此协议，提供统一的页面导航接口。
`RDEpubReaderView` 遵循此协议，提供统一的页面导航接口。
### 2.5 枚举类型
```swift
extension RDReaderView {
extension RDEpubReaderView {
public enum DisplayType {
case pageCurl // 仿真翻页（UIPageViewController）
case horizontalScroll // 水平滑动（UICollectionView）
@@ -105,13 +105,13 @@ extension RDReaderView {
---
## 3. 核心类：RDReaderView
## 3. 核心类：RDEpubReaderView
**文件：** `RDReaderView.swift`
**文件：** `RDEpubReaderView.swift`
`RDReaderView` 是一个 `UIView` 子类，作为翻页容器的主入口。内部管理两种翻页引擎：
`RDEpubReaderView` 是一个 `UIView` 子类，作为翻页容器的主入口。内部管理两种翻页引擎：
- **PageCurl 模式**：使用 `UIPageViewController` 实现仿真翻页
- **Scroll 模式**：使用 `UICollectionView` + 自定义 `RDReaderFlowLayout` 实现滑动翻页
- **Scroll 模式**：使用 `UICollectionView` + 自定义 `RDEpubReaderFlowLayout` 实现滑动翻页
### 3.1 关键属性
@@ -124,16 +124,16 @@ extension RDReaderView {
| `coverPageIndex` | `Int?` | 封面页索引（独占一屏） |
| `pagesPerScreen` | `Int` | 每屏页数（横屏双页时为 2） |
| `preloadRadius` | `Int` | 预加载半径（默认 1） |
| `dataSource` | `RDReaderDataSource?` | 旧版数据源 |
| `pageProvider` | `RDReaderPageProvider?` | 推荐数据源 |
| `delegate` | `RDReaderDelegate?` | 事件代理 |
| `dataSource` | `RDEpubReaderDataSource?` | 旧版数据源 |
| `pageProvider` | `RDEpubReaderPageProvider?` | 推荐数据源 |
| `delegate` | `RDEpubReaderDelegate?` | 事件代理 |
| `toolViewAnimationDuration` | `TimeInterval` | 工具栏动画时长（0.3s） |
### 3.2 关键方法
```swift
/// 切换显示模式（pageCurl / horizontalScroll / verticalScroll）
public func switchReaderDisplayType(_ displayType: RDReaderView.DisplayType)
public func switchReaderDisplayType(_ displayType: RDEpubReaderView.DisplayType)
/// 跳转到指定页
public func transitionToPage(pageNum: Int, animated: Bool = false)
@@ -154,22 +154,22 @@ public func isFullScreenPage(_ pageNum: Int) -> Bool
|------|------|------|
| `pageViewController` | `UIPageViewController` | PageCurl 翻页引擎 |
| `collectionView` | `UICollectionView` | Scroll 翻页引擎 |
| `layout` | `RDReaderFlowLayout` | CollectionView 自定义布局 |
| `spreadResolver` | `RDReaderSpreadResolver` | 双页配对计算 |
| `tapRegionHandler` | `RDReaderTapRegionHandler` | 点击区域判定 |
| `preloadController` | `RDReaderPreloadController` | 页面预加载与缓存 |
| `pagingController` | `RDReaderPagingController` | 翻页状态管理 |
| `layout` | `RDEpubReaderFlowLayout` | CollectionView 自定义布局 |
| `spreadResolver` | `RDEpubReaderSpreadResolver` | 双页配对计算 |
| `tapRegionHandler` | `RDEpubReaderTapRegionHandler` | 点击区域判定 |
| `preloadController` | `RDEpubReaderPreloadController` | 页面预加载与缓存 |
| `pagingController` | `RDEpubReaderPagingController` | 翻页状态管理 |
---
## 4. 翻页状态机：RDReaderPagingController
## 4. 翻页状态机：RDEpubReaderPagingController
**文件：** `Paging/RDReaderPagingController.swift`
**文件：** `Paging/RDEpubReaderPagingController.swift`
管理 PageCurl 模式下的翻页请求队列，防止动画冲突。
```swift
struct RDReaderPagingController {
struct RDEpubReaderPagingController {
struct PageTransitionRequest: Equatable {
let pageNum: Int
let animated: Bool
@@ -180,7 +180,7 @@ struct RDReaderPagingController {
var didBuildUI: Bool // UI 是否已构建
/// 判断是否应排队请求（PageCurl 模式下动画中返回 true）
mutating func shouldQueuePageTransition(_ request: PageTransitionRequest, currentDisplayType: RDReaderView.DisplayType) -> Bool
mutating func shouldQueuePageTransition(_ request: PageTransitionRequest, currentDisplayType: RDEpubReaderView.DisplayType) -> Bool
/// 完成翻页动画，返回待处理的请求
mutating func finishPageCurlTransition() -> PageTransitionRequest?
@@ -192,9 +192,9 @@ struct RDReaderPagingController {
---
## 5. 页面预加载：RDReaderPreloadController
## 5. 页面预加载：RDEpubReaderPreloadController
**文件：** `Paging/RDReaderPreloadController.swift`
**文件：** `Paging/RDEpubReaderPreloadController.swift`
负责在当前页周围预渲染页面视图，减少翻页时的白屏时间。
@@ -224,27 +224,27 @@ func invalidate(environment: Environment)
```swift
struct Environment {
let displayType: RDReaderView.DisplayType
let displayType: RDEpubReaderView.DisplayType
let isLandscape: Bool
let pagesPerScreen: Int
let boundsSize: CGSize
let landscapeDualPageEnabled: Bool
let coverPageIndex: Int?
let totalPages: Int
let spreadResolver: RDReaderSpreadResolver
let spreadResolver: RDEpubReaderSpreadResolver
}
```
---
## 6. 双页展开计算：RDReaderSpreadResolver
## 6. 双页展开计算：RDEpubReaderSpreadResolver
**文件：** `Paging/RDReaderSpreadResolver.swift`
**文件：** `Paging/RDEpubReaderSpreadResolver.swift`
纯函数式结构体，负责双页模式下的页面配对和导航计算。
```swift
struct RDReaderSpreadResolver {
struct RDEpubReaderSpreadResolver {
/// 判断是否为全屏页（封面页独占一屏）
func isFullScreenPage(_ pageNum: Int, landscapeDualPageEnabled: Bool, isLandscape: Bool, coverPageIndex: Int?) -> Bool
@@ -265,15 +265,15 @@ struct RDReaderSpreadResolver {
---
## 7. 点击区域判定：RDReaderTapRegionHandler
## 7. 点击区域判定：RDEpubReaderTapRegionHandler
**文件：** `Paging/RDReaderTapRegionHandler.swift`
**文件：** `Paging/RDEpubReaderTapRegionHandler.swift`
将屏幕三等分，判定点击属于左/中/右区域。
```swift
struct RDReaderTapRegionHandler {
func resolveTapEvent(point: CGPoint, viewFrame: CGRect, isToolViewVisible: Bool) -> RDReaderView.TapEvent
struct RDEpubReaderTapRegionHandler {
func resolveTapEvent(point: CGPoint, viewFrame: CGRect, isToolViewVisible: Bool) -> RDEpubReaderView.TapEvent
}
```
@@ -284,9 +284,9 @@ struct RDReaderTapRegionHandler {
---
## 8. 流式布局：RDReaderFlowLayout
## 8. 流式布局：RDEpubReaderFlowLayout
**文件：** `RDReaderFlowLayout.swift`
**文件：** `RDEpubReaderFlowLayout.swift`
`UICollectionViewFlowLayout` 子类，支持水平滚动和垂直滚动两种模式。
@@ -294,7 +294,7 @@ struct RDReaderTapRegionHandler {
| 属性 | 类型 | 说明 |
|------|------|------|
| `displayType` | `RDReaderView.DisplayType` | 布局模式 |
| `displayType` | `RDEpubReaderView.DisplayType` | 布局模式 |
| `isLandscapeDualPage` | `Bool` | 是否横屏双页 |
| `coverPageIndex` | `Int?` | 封面页索引 |
| `pagesPerScreen` | `Int` | 每屏页数 |
@@ -302,12 +302,12 @@ struct RDReaderTapRegionHandler {
### 8.2 协议
```swift
public protocol RDReaderFlowLayoutDataSoure: NSObjectProtocol {
func heigtOfVerticalScrollPage(flowLayout: RDReaderFlowLayout, pageIndex: Int) -> CGFloat?
public protocol RDEpubReaderFlowLayoutDataSoure: NSObjectProtocol {
func heigtOfVerticalScrollPage(flowLayout: RDEpubReaderFlowLayout, pageIndex: Int) -> CGFloat?
}
@objc public protocol RDReaderFlowLayoutDelegate: NSObjectProtocol {
func pageNum(flowLayout: RDReaderFlowLayout, pageIndex: Int)
@objc public protocol RDEpubReaderFlowLayoutDelegate: NSObjectProtocol {
func pageNum(flowLayout: RDEpubReaderFlowLayout, pageIndex: Int)
}
```
@@ -324,28 +324,28 @@ func currentContentOffset(count: Int) -> CGPoint
---
## 9. 内容 Cell：RDReaderContentCell
## 9. 内容 Cell：RDEpubReaderContentCell
**文件：** `RDReaderContentCell.swift`
**文件：** `RDEpubReaderContentCell.swift`
`UICollectionViewCell` 子类，用于 Scroll 模式下承载页面内容视图。
```swift
class RDReaderContentCell: UICollectionViewCell {
class RDEpubReaderContentCell: UICollectionViewCell {
var containerView: UIView? // 设置时自动添加到 contentView，移除旧视图
}
```
---
## 10. PageCurl 子控制器：RDReaderPageChildViewController
## 10. PageCurl 子控制器：RDEpubReaderPageChildViewController
**文件：** `RDReaderPageChildViewController.swift`
**文件：** `RDEpubReaderPageChildViewController.swift`
`UIViewController` 子类，作为 `UIPageViewController` 的页面 VC。
```swift
class RDReaderPageChildViewController: UIViewController {
class RDEpubReaderPageChildViewController: UIViewController {
var contentView: UIView? // 内容视图，设置时自动安装到容器
var pageNum: Int // 对应页码
@@ -357,7 +357,7 @@ class RDReaderPageChildViewController: UIViewController {
## 11. Extension 汇总
### 11.1 RDReaderView+PageCurl
### 11.1 RDEpubReaderView+PageCurl
实现 `UIPageViewControllerDataSource` 和 `UIPageViewControllerDelegate`：
@@ -367,18 +367,18 @@ class RDReaderPageChildViewController: UIViewController {
- `pageViewController(_:willTransitionTo:)` — 即将翻页时预加载
**特殊页码：**
- `RDReaderView.blankPageNum`（`Int.max`）— 双页模式下的空白页
- `RDReaderView.blankEndPageNum`（`Int.max - 1`）— 末尾空白页
- `RDEpubReaderView.blankPageNum`（`Int.max`）— 双页模式下的空白页
- `RDEpubReaderView.blankEndPageNum`（`Int.max - 1`）— 末尾空白页
### 11.2 RDReaderView+CollectionView
### 11.2 RDEpubReaderView+CollectionView
实现 `UICollectionViewDataSource`、`RDReaderFlowLayoutDelegate`、`RDReaderFlowLayoutDataSoure`：
实现 `UICollectionViewDataSource`、`RDEpubReaderFlowLayoutDelegate`、`RDEpubReaderFlowLayoutDataSoure`：
- `collectionView(_:cellForItemAt:)` — 复用预加载视图或创建新 Cell
- `collectionView(_:numberOfItemsInSection:)` — 返回总页数
- `pageNum(flowLayout:pageIndex:)` — 滚动时更新当前页码
### 11.3 RDReaderView+ContentAccess
### 11.3 RDEpubReaderView+ContentAccess
提供内容视图的注册、复用和查询：
@@ -396,7 +396,7 @@ public func pageContentView(pageNum: Int) -> UIView?
public func resolvedSinglePageSize(pageNum: Int? = nil) -> CGSize
```
### 11.4 RDReaderView+ToolView
### 11.4 RDEpubReaderView+ToolView
管理顶部/底部工具栏的安装、显示/隐藏动画：
@@ -420,11 +420,11 @@ func updateToolViewHeightConstraintsIfNeeded()
| 模式 | 应用 |
|------|------|
| **策略模式** | `DisplayType` 切换 PageCurl / Scroll 两种翻页策略 |
| **适配器模式** | `RDReaderLegacyDataSourceAdapter` 将旧 `RDReaderDataSource` 适配为 `RDReaderPageProvider` |
| **命令队列** | `RDReaderPagingController` 管理翻页请求队列 |
| **缓存签名** | `RDReaderPreloadController.CacheSignature` 检测环境变化自动失效 |
| **适配器模式** | `RDEpubReaderLegacyDataSourceAdapter` 将旧 `RDEpubReaderDataSource` 适配为 `RDEpubReaderPageProvider` |
| **命令队列** | `RDEpubReaderPagingController` 管理翻页请求队列 |
| **缓存签名** | `RDEpubReaderPreloadController.CacheSignature` 检测环境变化自动失效 |
| **关注点分离** | Extension 将不同功能拆分到独立文件 |
| **纯函数** | `RDReaderSpreadResolver` 和 `RDReaderTapRegionHandler` 无状态计算 |
| **纯函数** | `RDEpubReaderSpreadResolver` 和 `RDEpubReaderTapRegionHandler` 无状态计算 |
---
@@ -434,7 +434,7 @@ func updateToolViewHeightConstraintsIfNeeded()
用户点击屏幕
│
▼
RDReaderTapRegionHandler.resolveTapEvent()
RDEpubReaderTapRegionHandler.resolveTapEvent()
│
├── .left → goPreviousPage() ──→ spreadResolver.nextPage(forward: false)
├── .right → goNextPage() ──→ spreadResolver.nextPage(forward: true)