Skip to content

feat(android): 新增手机横屏沉浸式播放模式 & 新增依赖导入#27

Open
Shomi-FJS wants to merge 2 commits into
SPlayer-Dev:devfrom
Shomi-FJS:full
Open

feat(android): 新增手机横屏沉浸式播放模式 & 新增依赖导入#27
Shomi-FJS wants to merge 2 commits into
SPlayer-Dev:devfrom
Shomi-FJS:full

Conversation

@Shomi-FJS
Copy link
Copy Markdown

📌 变更类型

  • ✨ feat — 新功能
  • 🐞 fix — Bug 修复
  • 🎨 style — 仅样式 / 格式,不影响逻辑
  • ♻️ refactor — 重构,不改变外部行为
  • ⚡ perf — 性能优化
  • 📝 docs — 仅文档
  • 🧪 test — 新增 / 修改测试
  • 🔧 chore — 构建 / 脚本 / 依赖
  • 🚀 ci — 仅 CI 配置
  • ⏪ revert — 回滚

📝 变更说明

一、核心功能:手机横屏沉浸式播放模式

为手机端补齐横屏沉浸式全屏播放体验,让用户在手机横屏时可获得接近平板/桌面的播放界面,同时充分利用手机横屏的横向空间显示歌词。

新增

  • 横屏沉浸式入口与状态机FullPlayerMobile 顶栏新增横屏入口按钮,触发竖屏 → 沉浸式横屏切换;横屏顶部菜单同时承担退出入口。
  • 横屏紧凑布局 FullPlayerMobileLandscape.vue:左封面 + 右歌词的横屏专用布局,适配手机横屏窄高场景。
  • 横竖屏切换过渡协调器 useOrientationTransition.ts:黑场升起 → 触发原生旋转 → 揭幕的"舞台揭幕"式过渡,避免旋转过程中坐标系错乱与视觉抖动;遵循 prefers-reduced-motion,低动效场景跳过动画。
  • 横屏专属配置项(与竖屏字段隔离):
    • lyricFontSizeLandscape 横屏歌词字号
    • landscapeCoverOffsetX 封面 X 偏移
    • landscapeLyricPaddingX 歌词区左右内边距
    • PlayerQuickActionsMenu 中按当前模式动态显示对应控件。
  • 原生协作:新增 @capacitor/screen-orientation 依赖,配合 MainActivity / AndroidNativePlaybackPlugin 实现 SENSOR_LANDSCAPE 锁定与状态栏管理。
  • 过渡蒙层 OrientationOverlay.vue + animate.scss:黑场、Hero 封面、stagger 三层动画样式。

重构 / 行为隔离

  • 纯净歌词模式按朝向隔离:新增 pureLyricModeLandscape 字段与 effectivePureLyricMode getter;左上角按钮在沉浸式横屏下只切横屏字段,避免污染竖屏设置。
  • 页面缩放扩展到横屏沉浸式 (usePageZoom):手机端竖屏与横屏沉浸式共享同一缩放值,避免进入沉浸式后界面突变回 100%。
  • 沉浸式状态栏接管:useImmersive 在 isImmersiveFullscreen 期间跳过 androidShowStatusBar 恢复逻辑,由 native applyImmersiveMode 统一管控。

二、Bug 修复(顺手)

  • 设置迁移链断裂setting.ts → checkAndMigrate 旧实现把 currentState 当迁移前快照,循环内不更新;导致 v3→v6(enableTTMLLyric)、v5→v8(excludeUserKeywords/Regexes)等跨版本迁移读取到 undefined,最终 $patch 把默认值覆盖为 undefined。修复:每步 Object.assign(currentState, migrationUpdates) 同步合并。
  • 持久化死字段:status.ts 的 persist.pick 引用了 StatusState 中并不存在的 playSongType,已删除。

三、依赖

  • 新增 @capacitor/screen-orientation,用于横屏锁定与方向感知;配套更新 android/build.gradlecapacitor.settings.gradlepnpm-lock.yaml

🔗 关联 Issue

Closes #

📱 影响范围

  • 🎵 播放引擎 / 音频
  • 📝 歌词 / 桌面歌词
  • 🔔 通知栏 / MediaSession
  • 🌐 在线音乐 (网易云 / Jellyfin / Navidrome / Emby / Subsonic / Last.fm)
  • 🧩 内置 API (nodejs-mobile)
  • 🎨 UI / 主题 / 布局
  • 📦 构建 / 打包 / 签名
  • 📱 Capacitor / 原生 Android 代码
  • 📄 文档 / README

✅ 自检清单

  • 本 PR 目标分支为 dev
  • 本地已执行 pnpm lint 且无 warning
  • 本地已执行 pnpm typecheck 且无报错
  • 已在 至少一台真机 上构建并验证关键路径
  • UI 改动已兼顾 手机竖屏 + 平板横屏 两种布局
  • 新增 / 修改的文案使用中文,与项目整体风格一致
  • 未引入不必要的依赖 / 大体积资源(仅新增官方 @capacitor/screen-orientation
  • 未修改签名密钥 / CI Secrets 相关文件

📸 截图 / 录屏

IMG_20260526_065810

🧪 测试方式

  1. 入场:手机端打开任意歌曲,进入全屏播放器,点击顶栏左上「全屏」图标 → 应触发黑场升起 → 自动旋转到横屏 → 揭幕显示横屏紧凑布局,过程中无抖动 / 错位。
  2. 退场:在横屏沉浸式下点击顶栏右上「退出全屏」或「下拉」图标 → 应黑场覆盖 → 旋转回竖屏 → 揭幕显示原全屏播放器。
  3. 横屏专属配置:进入横屏后展开快捷操作菜单,应仅出现「横屏模式字号」「横屏封面位置」「横屏歌词边距」三项;调节后立即生效;退出回竖屏后不影响竖屏字号。
  4. 纯净歌词隔离:横屏点左上角「纯净歌词」按钮开启 → 退出回竖屏 → 竖屏的纯净歌词状态应保持原样不被改动。
  5. 缩放联动:在设置里把手机缩放调到 90%/110% → 进入沉浸式横屏,整体应保持相同缩放,不会突变回 100%。
  6. 降级路径:开启系统「减少动效」(prefers-reduced-motion: reduce) → 入/退场应直接切换状态而无动画,不出现卡死。
  7. 设置迁移:从旧版本(schemaVersion < 21)升级安装 → 启动后检查 enableOnlineTTMLLyricexcludeLyricsUserKeywords/Regexes 等字段不应为 undefined,保持有效默认值。

💬 其他说明

  • 横竖屏切换协调器主动放弃了"hero 跨 viewport 流转"方案——旋转后 fromRect 坐标系失效,会产生坐标错乱。当前采用"舞台揭幕":横屏布局先就位再揭幕,视觉更稳。
  • pureLyricModeLandscapepureLyricMode 各自独立持久化,下次进同一模式各自记忆。
  • 横屏专属配置默认值:字号 24 / 封面 X 偏移 52 / 歌词内边距 58;已通过 v21 schema 迁移落地。
  • 已知限制:横屏沉浸式当前仅在 Android Capacitor 环境启用(isCapacitorAndroid && isPhone),其它平台保持原行为。

Shomi-FJS added 2 commits May 25, 2026 15:36
详细提交内容:
- 在package.json中新增screen-orientation插件依赖
- 在android/build.gradle中添加该插件的本地依赖项目
- 在capacitor.settings.gradle中配置插件的安卓项目路径
- 更新pnpm-lock.yaml以锁定screen-orientation插件版本
- 新增横屏沉浸式全屏播放模式,支持隐藏状态栏与导航手势条
- 新增横屏专属歌词字号、封面偏移、歌词内边距配置项
- 新增横竖屏切换过渡动画与状态锁逻辑
- 新增横屏紧凑播放器布局,适配手机横屏场景
- 隔离横屏与竖屏的纯净歌词模式与设置
- 适配Android原生沉浸式横屏逻辑与配置迁移
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant