138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# 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 与页面稳定性。
|
||
**应对**：统一截断/换行规则，增加长文案样本回归。
|
||
|