# 横竖屏切换支持方案讨论

## 需求背景

`Doc/EPUB_MAINTENANCE.md` 与 `Doc/ARCHITECTURE.md` 都把“横竖屏切换支持”列为当前阅读器的高优先级待补能力。

目标不是单纯“屏幕旋转后不崩”，而是让 EPUB 阅读器在横竖屏切换后具备以下稳定行为：

1. 正文重新按新视口尺寸分页或重排
2. 阅读位置尽量准确恢复，不明显跳章、跳页
3. 工具栏、目录、标注、搜索状态不异常
4. pageCurl / horizontalScroll / verticalScroll / horizontalCoverScroll 四种展示模式行为一致
5. WebView、DTCoreText、fixed layout 三条正文路径都能正确处理

## 代码事实

### 已有基础

当前仓库并不是完全没有横竖屏处理基础：

- `RDReaderView.layoutSubviews()` 会检测 `previousIsLandscape` 与 `isLandscape` 的变化  
  文件：`Sources/RDReaderView/RDReaderView.swift`
- `RDReaderView.orientationChanged(isNowLandscape:)` 已能：
  - 通知 `readerViewOrientationWillChange`
  - 更新 `layout.isLandscapeDualPage`
  - `pageCurl` 模式下重建 `UIPageViewController`
  - 滚动模式下 `invalidateLayout + reloadData + setContentOffset`
- `RDEPUBReaderController.readerViewOrientationWillChange(...)` 当前会直接调用 `repaginatePreservingCurrentLocation()`
- `RDEPUBReaderController.repaginatePreservingCurrentLocation()` 已具备“先记录当前位置，再重新分页，再恢复位置”的主链路
- `RDEPUBLocation` 已采用 `href + progression + lastProgression + fragment` 模型，本身适合应对字号变化和尺寸变化后的重定位

结论：

- 基础设施已经存在
- 真正缺的是“时机是否稳定、入口是否统一、三条正文路径是否都覆盖、是否会重复触发”

### 当前实现存在的问题

#### 问题 1：方向变化回调被 `landscapeDualPageEnabled` 绑定

`RDReaderView.layoutSubviews()` 目前有：

```swift
guard landscapeDualPageEnabled, bounds.width > 0, bounds.height > 0 else { return }
```

这意味着：

- 只有开启 `landscapeDualPageEnabled` 时才会进入方向变化检测
- 如果宿主关闭横屏双页，但正文仍然会因为宽高变化而需要重排，此时不会触发回调

这对以下场景不正确：

1. `textReflowable` 文本书籍在横竖屏切换后，行宽必然变化，应重新分页
2. `webInteractive` 可重排正文在横竖屏切换后，列分页宽度变化，应重新分页
3. fixed layout 在 spread 模式下也可能因视口变化而需要重新生成页面模型

#### 问题 2：重新分页触发时机偏早

当前 `readerViewOrientationWillChange` 是从 `RDReaderView.layoutSubviews()` 中异步抛出。

这有几个风险：

1. 此时上层 VC 的 `view.bounds`、safe area、sheet 布局动画可能还在变化中
2. `paginatePublication()` 如果过早读取 `currentLayoutContext().viewportSize`，可能拿到中间态尺寸
3. `RDReaderView` 自己已经在同一轮变化里做了 `reloadData` / `transitionToPage`，而 `RDEPUBReaderController` 又会发起新一轮分页，容易出现双重刷新

#### 问题 3：职责边界不够清晰

目前横竖屏变化同时由两层在做事：

- `RDReaderView`：处理双页布局、pageCurl 容器重建、滚动模式 offset 恢复
- `RDEPUBReaderController`：处理 EPUB 重新分页

但两层之间没有一个明确的“统一入口”来协调：

1. 是否真的需要重分页
2. 什么时候用最终尺寸重分页
3. 何时忽略重复触发
4. 何时只刷新布局，不重做完整分页

#### 问题 4：文档状态与代码状态不一致

文档把横竖屏切换标为“未实现”，但代码里已经有半套逻辑。

这说明当前更准确的描述应当是：

- “已有局部实现”
- “尚未形成稳定、完整、可验收的横竖屏支持闭环”

## 需求拆解

为了让“横竖屏切换支持”真正完成，建议把需求拆成四部分：

### 1. 稳定感知视口变化

不仅要感知“横屏/竖屏布尔值变化”，还要感知：

- 宽高尺寸变化
- safe area 变化
- iPad 分屏、多窗口、sheet 尺寸变化

因此，真正要监听的不是“orientation”，而是“阅读视口发生了足以影响分页的变化”。

### 2. 统一触发重新分页

所有需要重排正文的场景都应走统一入口，例如：

```swift
handleViewportChange(reason: .orientationTransition)
```

由它统一负责：

1. 读取当前位置
2. 比较旧 viewport 与新 viewport
3. 防抖与去重
4. 发起分页
5. 恢复定位

### 3. 区分“容器布局刷新”和“正文重分页”

不是所有变化都必须触发完整分页，但横竖屏切换通常都需要：

- `textReflowable`：重建 `RDEPUBTextBook`
- `webInteractive`：重跑 `RDEPUBPaginator`
- `webFixedLayout`：重建 fixed spread snapshot

而 `RDReaderView` 自己的 pageCurl 双页容器重建仍可保留，但不应和正文分页时机互相打架。

### 4. 建立回归验收矩阵

横竖屏切换是高联动场景，至少要验证：

1. 无选区、无工具栏时切换
2. 有目录面板、设置面板、标注列表时切换
3. 搜索命中页、标注页、末页时切换
4. `landscapeDualPageEnabled = true / false`
5. pageCurl / scroll 系列模式

## 技术路线对比

### 路线 A：继续依赖 `RDReaderView.readerViewOrientationWillChange`

思路：

- 保留现有 `layoutSubviews() -> orientationChanged -> delegate`
- 在 `RDEPUBReaderController` 内增强去重、防抖和最终尺寸判断

优点：

1. 改动范围小
2. 能延续现有 `RDReaderView` 双页逻辑

风险：

1. 触发时机仍然偏依赖 `layoutSubviews()`
2. 仍容易与 VC 生命周期中的尺寸变化打架
3. 继续把“正文分页”绑定到“容器方向回调”，抽象层次不够稳定

### 路线 B：由 `RDEPUBReaderController.viewWillTransition(to:with:)` 统一接管

思路：

1. 在 `RDEPUBReaderController` 实现 `viewWillTransition(to:with:)`
2. 利用 `transitionCoordinator` 等待旋转动画接近完成
3. 在 completion 中读取最终 `viewportSize`
4. 统一调用 `handleViewportChange(reason:)`
5. `RDReaderView.readerViewOrientationWillChange` 只保留容器级双页重建职责，不再直接触发正文分页

优点：

1. 分页时机更接近最终尺寸
2. 更符合 UIKit 对旋转和尺寸变化的生命周期
3. 更容易做重复触发抑制
4. 更适合以后扩展到 iPad 分屏、多窗口

风险：

1. 需要重新梳理 `RDReaderView` 与 `RDEPUBReaderController` 的职责分界
2. 需要验证 pageCurl 双页重建与正文分页之间的顺序

### 推荐结论

建议采用：

**主路线：路线 B，由 `RDEPUBReaderController.viewWillTransition(to:with:)` 统一接管正文重分页**  
**保留 `RDReaderView` 现有方向变化逻辑，但将其职责收敛为容器布局刷新和双页模式内部处理**

原因：

1. 需求本质是“视口变化后的正文重排”，最合理的宿主是控制器，而不是容器内部的 `layoutSubviews()`
2. 现有 `RDReaderView` 回调机制已经能服务内部双页布局，但不适合作为 EPUB 正文分页的唯一入口
3. `viewWillTransition` + `transitionCoordinator` 更容易拿到稳定尺寸，并减少重复分页

## 推荐方案

### 方案总览

引入一条统一的横竖屏处理主链路：

```swift
viewWillTransition(to:with:)
  -> scheduleViewportTransition(reason: .orientation)
  -> handleViewportChangeIfNeeded(finalViewportSize)
  -> repaginatePreservingCurrentLocation()
  -> finishPagination(restoreLocation:)
```

同时把 `RDReaderView` 内部职责收敛为：

1. 更新 `layout.isLandscapeDualPage`
2. pageCurl 模式下重建 `UIPageViewController`
3. 滚动模式刷新 collectionView 布局

不再让 EPUBUI 直接在 `readerViewOrientationWillChange` 中立即重新分页。

### 关键改动建议

#### Task O1：增加控制器级旋转入口

文件：

- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`

改动：

- 实现 `viewWillTransition(to:with:)`
- 在 `transitionCoordinator` completion 中比较新旧 viewport
- 统一调 `handleViewportChange(reason:)`

完成定义：

- 旋转后分页使用最终尺寸，而不是中间态尺寸

#### Task O2：引入 viewport 去重与防抖

文件：

- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`

改动：

- 保存最近一次已应用的 `viewportSignature`
- 仅当宽高变化超过阈值时才触发重新分页
- 防止 `viewDidLayoutSubviews`、`orientation callback`、`viewWillTransition` 连续多次重复触发

推荐结构：

```swift
private struct RDEPUBViewportSignature: Equatable {
    let width: CGFloat
    let height: CGFloat
    let safeTop: CGFloat
    let safeBottom: CGFloat
}
```

完成定义：

- 一次横竖屏切换只触发一次有效正文重分页

#### Task O3：调整 `readerViewOrientationWillChange` 职责

文件：

- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
- 如有必要 `Sources/RDReaderView/RDReaderView.swift`

改动：

- `RDEPUBReaderController.readerViewOrientationWillChange` 不再直接 `repaginatePreservingCurrentLocation()`
- 保留它作为兼容钩子，或仅做轻量状态标记

完成定义：

- 容器内部布局刷新与正文分页不再相互打架

#### Task O4：放宽 `RDReaderView` 的方向检测前置条件

文件：

- `Sources/RDReaderView/RDReaderView.swift`

改动：

- 去掉 `layoutSubviews()` 中对 `landscapeDualPageEnabled` 的硬性 guard
- 方向变化检测应独立于“是否启用横屏双页”

完成定义：

- 即使 `landscapeDualPageEnabled == false`，视口变化仍可被上层感知并触发重分页

注意事项：

- 双页布局本身仍然只在 `landscapeDualPageEnabled == true` 时开启
- 但“是否需要感知尺寸变化”不能绑定到这个开关

#### Task O5：验证三条正文路径的恢复策略

文件：

- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
- `Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift`
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`

改动：

- 验证 `restoreReadingLocation()` 在以下路径都稳定：
  - `textReflowable`
  - `webInteractive`
  - `webFixedLayout`

完成定义：

- 横竖屏切换后，恢复位置不明显跳页、跳章

#### Task O6：补文档与验收矩阵

文件：

- `Doc/EPUB_MAINTENANCE.md`
- `Doc/ARCHITECTURE.md`
- 如有必要 `Doc/EPUBUI_功能实现逻辑.md`

改动：

- 将“横竖屏切换未做”更新为更准确的实现状态
- 补充最终采用的触发时机与回归清单

完成定义：

- 文档与代码状态一致

## 风险点

1. **pageCurl 双页重建顺序**
   `RDReaderView` 自己会重建 `UIPageViewController`，如果 `RDEPUBReaderController` 同时触发分页，需要验证两者先后顺序
2. **重复分页**
   旋转时 UIKit 常伴随多次 layout / safe area 变化，如果没有 `viewportSignature`，很容易多次重排
3. **iPad 场景复杂度**
   分屏、多窗口、Stage Manager 下不一定发生“方向变化”，但一定发生“视口变化”，所以方案必须以 viewport 为核心
4. **fixed layout spread 恢复**
   横屏双页和竖屏单页之间切换时，恢复到哪一页的左页 / 右页，需要以 `RDEPUBLocation` 为准而不是旧页号

## 推荐实施顺序

1. 先做 `O1 + O2`，把控制器级 viewport 变化入口和防抖建起来
2. 再做 `O3 + O4`，把旧的 delegate 触发职责收窄
3. 然后验证 `O5`，重点跑三条正文路径和四种展示模式
4. 最后做 `O6`，同步文档与验收矩阵

## 验收标准

1. 横竖屏切换后，`textReflowable` 路径会按新尺寸重新分页，并恢复到接近原阅读位置
2. 横竖屏切换后，`webInteractive` 路径会重新分页，并恢复到接近原阅读位置
3. 横竖屏切换后，`webFixedLayout` 路径会按新 spread 规则重建页面模型，并恢复到正确资源
4. `landscapeDualPageEnabled == false` 时，横竖屏切换仍然会触发必要的重排
5. 一次旋转只触发一次有效正文重分页，不出现连续多次闪烁刷新
6. pageCurl / horizontalScroll / verticalScroll / horizontalCoverScroll 四种模式下都不出现明显错页、白页或工具栏错位

## 结论

横竖屏切换支持不是“从零开始新增一套能力”，而是要把当前分散在 `RDReaderView` 和 `RDEPUBReaderController` 里的半套逻辑收敛成一个稳定闭环。

最推荐的方向是：

- `RDEPUBReaderController` 用 `viewWillTransition(to:with:)` 统一接管正文级重分页
- `RDReaderView` 保留容器级双页布局和 pageCurl 重建职责
- 以 `viewport` 变化而不是 `isLandscape` 布尔值作为真正的分页触发依据

这样既能复用现有代码，又能把“文档标注为未完成”的横竖屏需求收敛成可实现、可回归、可交付的一阶段方案。