feat: Enhance mobile and tablet support with responsive layout adjustments and new navigation components

2026-02-04 03:36:29 +08:00 · 2025-08-01 16:36:28 +08:00
parent 942703509e
commit 9e9e4597cc
35 changed files with 4082 additions and 634 deletions
--- a/docs/MOBILE_TABLET_ADAPTATION.md
+++ b/docs/MOBILE_TABLET_ADAPTATION.md
@@ -0,0 +1,308 @@
+# OrionTV 手机端和平板端适配方案
+
+## 项目概述
+
+OrionTV 是一个基于 React Native TVOS 的视频流媒体应用，目前专为 Android TV 和 Apple TV 平台设计。本文档详细描述了将应用适配到 Android 手机和平板设备的完整方案。
+
+## 当前状态分析
+
+### TV端特征
+- **技术栈**: React Native TVOS 0.74.x + Expo 51
+- **导航**: Stack 导航结构，适合遥控器操作
+- **布局**: 固定5列网格布局 (`NUM_COLUMNS = 5`)
+- **交互**: TV遥控器专用事件处理 (`useTVRemoteHandler`)
+- **组件**: TV专用组件 (`VideoCard.tv.tsx`)
+- **UI元素**: 大间距、大按钮，适合10英尺距离观看
+
+### 现有页面结构
+1. **index.tsx** - 首页：分类选择 + 5列视频网格
+2. **detail.tsx** - 详情页：横向布局，海报+信息+播放源
+3. **search.tsx** - 搜索页：搜索框 + 5列结果网格
+4. **play.tsx** - 播放页：全屏视频播放器 + TV遥控器控制
+5. **settings.tsx** - 设置页：TV遥控器导航 + 远程输入配置
+6. **favorites.tsx** - 收藏页：网格布局展示收藏内容
+7. **live.tsx** - 直播页：直播流播放
+8. **_layout.tsx** - 根布局：Stack导航 + 全局状态管理
+
+## 适配目标
+
+### 设备分类
+- **手机端** (< 768px): 单手操作，纵向为主，触摸交互
+- **平板端** (768px - 1024px): 双手操作，横竖屏，触摸+键盘
+- **TV端** (> 1024px): 遥控器操作，横屏，10英尺距离
+
+### 响应式设计原则
+1. **内容优先**: 保持核心功能一致性
+2. **渐进增强**: 根据屏幕尺寸增加功能
+3. **平台原生感**: 符合各平台交互习惯
+4. **性能优化**: 避免不必要的重新渲染
+
+## 技术实施方案
+
+### 阶段1: 响应式基础架构
+
+#### 1.1 创建响应式 Hook
+```typescript
+// hooks/useResponsiveLayout.ts
+export interface ResponsiveConfig {
+  deviceType: 'mobile' | 'tablet' | 'tv';
+  columns: number;
+  cardWidth: number;
+  cardHeight: number;
+  spacing: number;
+  isPortrait: boolean;
+}
+```
+
+#### 1.2 设备检测逻辑
+- 基于 `Dimensions.get('window')` 获取屏幕尺寸
+- 监听方向变化 `useDeviceOrientation()`
+- 平台检测 `Platform.OS` 和 TV 环境变量
+
+#### 1.3 断点定义
+```typescript
+const BREAKPOINTS = {
+  mobile: { min: 0, max: 767 },
+  tablet: { min: 768, max: 1023 },
+  tv: { min: 1024, max: Infinity }
+};
+```
+
+### 阶段2: 多平台组件系统
+
+#### 2.1 VideoCard 组件族
+- **VideoCard.mobile.tsx**: 纵向卡片，大触摸目标
+- **VideoCard.tablet.tsx**: 中等卡片，平衡布局  
+- **VideoCard.tv.tsx**: 保持现有实现
+
+#### 2.2 组件选择器
+```typescript
+// components/VideoCard/index.tsx
+export const VideoCard = (props) => {
+  const { deviceType } = useResponsiveLayout();
+  
+  switch(deviceType) {
+    case 'mobile': return <VideoCardMobile {...props} />;
+    case 'tablet': return <VideoCardTablet {...props} />;
+    case 'tv': return <VideoCardTV {...props} />;
+  }
+};
+```
+
+### 阶段3: 导航系统重构
+
+#### 3.1 手机端导航
+- **底部Tab导航**: 首页、搜索、收藏、设置
+- **Header导航**: 返回按钮、标题、操作按钮
+- **抽屉导航**: 次要功能入口
+
+#### 3.2 平板端导航  
+- **侧边栏导航**: 持久化主导航
+- **Master-Detail**: 列表+详情分屏
+- **Tab Bar**: 内容区域二级导航
+
+#### 3.3 TV端导航
+- **保持现有**: Stack导航结构
+- **遥控器优化**: Focus管理和按键导航
+
+### 阶段4: 页面逐一适配
+
+#### 4.1 首页 (index.tsx)
+**手机端改进:**
+- 1-2列网格布局
+- 分类用横向滚动标签
+- 下拉刷新
+- 上拉加载更多
+
+**平板端改进:**
+- 2-3列网格布局  
+- 左侧分类侧边栏
+- 内容区域可滚动
+- 支持横竖屏切换
+
+**TV端保持:**
+- 5列网格布局
+- 遥控器导航
+- 现有交互逻辑
+
+#### 4.2 详情页 (detail.tsx)
+**手机端改进:**
+- 纵向布局：海报→信息→播放源→剧集
+- 海报占屏幕宽度40%
+- 播放源横向滚动
+- 剧集网格4-5列
+
+**平板端改进:**
+- 左右分栏：海报+信息 | 播放源+剧集
+- 海报固定尺寸  
+- 播放源卡片式布局
+- 剧集6-8列网格
+
+#### 4.3 搜索页 (search.tsx)
+**手机端改进:**
+- 优化键盘输入体验
+- 搜索历史和推荐
+- 2列结果网格
+- 筛选和排序功能
+
+**平板端改进:**
+- 更大的搜索框
+- 3列结果网格
+- 侧边栏筛选选项
+- 搜索建议下拉
+
+#### 4.4 播放页 (play.tsx)
+**手机端改进:**
+- 触摸控制替代遥控器
+- 手势操作：双击暂停、滑动调节
+- 竖屏小窗播放模式
+- 亮度和音量调节
+
+**平板端改进:**
+- 触摸+手势控制
+- 画中画模式支持
+- 外接键盘快捷键
+- 更大的控制按钮
+
+#### 4.5 设置页 (settings.tsx)
+**手机端改进:**
+- 分组设置列表
+- 原生选择器和开关
+- 键盘友好的输入框
+- 滚动优化
+
+**平板端改进:**
+- 左侧设置分类，右侧设置详情
+- 更大的输入区域
+- 实时预览效果
+- 批量操作支持
+
+### 阶段5: 组件库升级
+
+#### 5.1 触摸优化组件
+- **TouchableButton**: 44px最小触摸目标
+- **SwipeableCard**: 支持滑动操作
+- **PullToRefresh**: 下拉刷新组件
+- **InfiniteScroll**: 无限滚动加载
+
+#### 5.2 手势处理
+- **PinchToZoom**: 双指缩放
+- **SwipeNavigation**: 滑动导航
+- **LongPressMenu**: 长按菜单
+- **DoubleTapHandler**: 双击处理
+
+#### 5.3 响应式工具
+- **ResponsiveText**: 自适应字体大小
+- **ResponsiveSpacing**: 自适应间距
+- **ConditionalRender**: 条件渲染组件
+- **OrientationHandler**: 方向变化处理
+
+### 阶段6: 构建和部署
+
+#### 6.1 构建脚本更新
+```json
+{
+  "scripts": {
+    "android-mobile": "EXPO_USE_METRO_WORKSPACE_ROOT=1 expo run:android",
+    "android-tablet": "EXPO_USE_METRO_WORKSPACE_ROOT=1 expo run:android --device tablet",
+    "android-tv": "EXPO_TV=1 EXPO_USE_METRO_WORKSPACE_ROOT=1 expo run:android"
+  }
+}
+```
+
+#### 6.2 配置文件适配
+- **app.json**: 多平台配置
+- **metro.config.js**: 条件资源加载
+- **package.json**: 平台特定依赖
+
+#### 6.3 资源文件
+- 手机端应用图标 (48dp-192dp)
+- 平板端应用图标 (优化尺寸)
+- 启动屏适配不同分辨率
+- 自适应图标 (Adaptive Icons)
+
+## 测试计划
+
+### 测试设备覆盖
+- **手机**: Android 5.0-14, 屏幕 4"-7"
+- **平板**: Android 平板 7"-12", 横竖屏
+- **TV**: 保持现有测试覆盖
+
+### 测试要点
+1. **响应式布局**: 不同屏幕尺寸正确显示
+2. **交互体验**: 触摸、手势、导航流畅
+3. **性能表现**: 启动速度、滚动性能、内存使用
+4. **兼容性**: 不同Android版本和设备
+
+### 自动化测试
+- Jest单元测试覆盖新组件
+- E2E测试核心用户流程
+- 视觉回归测试UI一致性
+- 性能基准测试
+
+## 风险评估
+
+### 技术风险
+- **复杂度增加**: 多平台适配增加维护成本
+- **性能影响**: 条件渲染可能影响性能
+- **测试覆盖**: 需要覆盖更多设备组合
+
+### 缓解策略
+- 渐进式迁移，优先核心功能
+- 性能监控和优化
+- 自动化测试保证质量
+- 代码复用最大化
+
+## 实施时间表
+
+### 第1周: 基础架构
+- [ ] 响应式Hook开发
+- [ ] 多平台组件框架
+- [ ] 基础样式系统
+
+### 第2周: 核心页面适配
+- [ ] 首页手机/平板适配
+- [ ] 详情页手机/平板适配
+- [ ] 搜索页手机/平板适配
+
+### 第3周: 功能完善
+- [ ] 播放页适配
+- [ ] 设置页适配
+- [ ] 导航系统重构
+
+### 第4周: 优化和测试
+- [ ] 组件库升级
+- [ ] 性能优化
+- [ ] 全面测试
+
+## 成功指标
+
+### 用户体验指标
+- 应用启动时间 < 3秒
+- 页面切换流畅度 > 95%
+- 触摸响应延迟 < 100ms
+- 用户满意度 > 4.5/5
+
+### 技术指标
+- 代码复用率 > 80%
+- 自动化测试覆盖率 > 90%
+- 应用包大小增长 < 20%
+- 内存使用优化 > 15%
+
+---
+
+## 附录
+
+### 参考资料
+- [React Native 响应式设计指南]
+- [Material Design 自适应布局]
+- [TV应用设计最佳实践]
+
+### 相关文档
+- 项目架构文档 (CLAUDE.md)
+- TV端开发指南
+- 组件库使用手册
+
+---
+*最后更新: 2025-08-01*
+*版本: 1.0*