# iPad Adaptation（技术计划）

## 1. 计划目标

基于 `spec.md`，落地“全应用 iPad 适配（含 iOS Widget）”实施方案，确保：

- 客户端所有页面在 iPad 下可用、可读、可交互；
- 以 **竖屏** 为主目标完成逐页适配与验收；
- iOS Widget 在 iPad 相关尺寸下展示稳定；
- 全过程保持 **iPhone 零回归**。

## 2. 默认技术决策

- **适配方式**：React Native 断点 + 条件样式（不改 iPhone 基线参数）。
- **iPad 判定**：`Platform.OS === 'ios' && Math.min(width, height) >= 768`。
- **尺寸获取**：统一使用 `useWindowDimensions()`，避免 `Dimensions.get()` 静态值问题。
- **布局原则**：页面采用“最大内容宽度 + 居中 + 弹性留白”。
- **改造策略**：按页面逐个交付，单页完成后冻结，待确认再进入下一页。

## 3. 工程配置基线（先决条件）

### 3.1 原生配置核查

- `app.json` 中 `expo.ios.supportsTablet = true`（已要求）。
- iOS 工程目标设备族支持 iPad（`TARGETED_DEVICE_FAMILY` 需包含 `1,2`）。
- 方向策略与产品要求一致（当前优先竖屏；若仅竖屏，则 iPad 也收敛为竖屏策略）。
- 避免 iPad 以 iPhone 兼容模式运行（该模式会导致系统黑边）。

### 3.2 运行模式与验收环境

- iPad 模拟器：至少 1 台主流尺寸（如 11-inch）。
- iPad 真机：至少 1 台（若可用），用于确认系统级显示行为。
- iPhone 回归机型：至少小屏 + 大屏各 1 个。

## 4. 页面适配实施策略（逐页）

### 4.1 页面分批顺序

1. 启动链路：`splash / consent / index`  
2. Onboarding 全流程页  
3. 主应用页：`home`、详情/弹层、设置、收藏等  
4. 边缘页：`modal`、`not-found`、其他辅助页

### 4.2 单页改造标准模板

每页按以下模板执行：

1. 梳理页面结构：首屏视觉区、正文区、底部操作区、浮层区。  
2. 抽离 iPad 分支参数：最大宽度、字号、行高、间距、按钮尺寸。  
3. 保持 iPhone 参数不变：原样式分支保留。  
4. 自测：
   - iPad 竖屏显示完整；
   - 文案不截断、按钮可点击；
   - iPhone 关键路径不回归。  
5. 输出截图与验收点，待确认后冻结该页。

### 4.3 可复用样式基线（建议）

- 页面容器：`flex: 1` + `width/height: '100%'` + `alignSelf: 'stretch'`。  
- 内容最大宽度：按页面类型设置（例如 560/620/680 分级），统一居中。  
- 底部操作区：基于安全区与窗口高度计算，不使用硬编码魔法值。  
- 文案区：限制最大阅读宽度，iPad 适度增大字号与行高。  
- 图片/插画：按比例缩放，优先保持构图稳定，不压缩变形。

## 5. iOS Widget 适配计划

### 5.1 覆盖范围

- 小/中/大组件在 iPad 下的展示一致性；
- 文案长度、换行与截断策略；
- 图形与文本的层级、边距、留白；
- 浅色模式基线（深色模式按资源情况补充）。

### 5.2 实施要点

- 统一组件内边距与字号层级映射；
- 对长文本提供优雅截断（避免溢出与跳变）；
- 验证不同语言长度对布局影响；
- 输出尺寸矩阵截图作为最终验收材料。

## 6. iPhone 零回归保障

- 所有 iPad 适配均以条件分支或断点参数实现；
- 禁止直接覆盖 iPhone 基线字号/间距；
- 每完成一页，执行 iPhone 冒烟回归：
  - 启动流程；
  - Onboarding 关键交互；
  - Home 关键按钮与弹层；
  - Settings/Favorites 基础可用性。

## 7. 验收清单与交付物

### 7.1 页面级验收清单

- 布局完整：无重叠、无错位、无异常黑边；
- 文案可读：不截断（可接受预期截断场景需说明）；
- 交互可用：触控面积合理、按钮不被遮挡；
- 状态一致：加载/空态/异常态显示正常；
- iPhone 回归：关键路径无变化。

### 7.2 交付物

- 每页适配说明（改动点 + 参数策略）；
- iPad 改前/改后截图；
- iPhone 回归截图；
- Widget 各尺寸截图；
- 最终页面覆盖矩阵与验收记录。

## 8. 分阶段里程碑

1. **M1 基线搭建**  
   - 完成原生配置核查与适配基线工具/约定；
   - 输出页面清单与验收模板。  

2. **M2 页面逐页适配**  
   - 按既定顺序逐页改造；
   - 每页交付后等待确认，再继续下一页。  

3. **M3 Widget 收口**  
   - 完成 iPad 尺寸矩阵验证；
   - 修复文本/间距/层级问题。  

4. **M4 全量回归与发布前验收**  
   - iPad 全页验收 + iPhone 零回归确认；
   - 形成最终验收文档。

## 9. 风险与应对

- **风险**：页面存在大量固定像素值，局部改动引发联动。  
  **应对**：参数分层、按区块替换、单页冻结机制。

- **风险**：iPad 多窗口/舞台管理导致尺寸波动。  
  **应对**：以竖屏全屏为主验收，同时保留窗口变化最小兼容策略。

- **风险**：多语言文案长度影响 widget 与页面稳定性。  
  **应对**：统一截断/换行规则，增加长文案样本回归。