React Native Track Player 从 v2 升级到 v3 的完整迁移指南

React Native Track Player 从 v2 升级到 v3 的完整迁移指南

react-native-track-player A fully fledged audio module created for music apps. Provides audio playback, external media controls, background mode and more! 项目地址: https://gitcode.com/gh_mirrors/re/react-native-track-player

前言

React Native Track Player 是一个功能强大的音频播放库，专为 React Native 应用设计。随着 v3 版本的发布，该库在 Android 平台上的行为发生了重要变化，主要是为了适应现代 Android 系统对后台服务的严格管理。本文将详细介绍从 v2 迁移到 v3 的关键变化和必要步骤。

核心变化概述

v3 版本最大的改变集中在 Android 平台上处理音频服务的方式：

1. 服务生命周期管理：Android 系统现在完全控制音频服务的生命周期，应用无法手动停止服务
2. 永久性通知：音频控制通知现在会一直显示，这是 Android 系统的强制要求
3. API 简化：移除了 destroy 和 stop 方法，引入了更符合现代 Android 开发模式的新配置

详细迁移步骤

1. 配置参数变更

stopWithApp 重命名为 stoppingAppPausesPlayback

await TrackPlayer.updateOptions({
-  stopWithApp: true,
+  stoppingAppPausesPlayback: true,
  // 其他配置...
});

这个变更不仅仅是名称上的变化，更准确地反映了功能行为：当应用停止时，播放会被暂停而非完全停止。

2. 移除废弃方法

v3 版本移除了两个关键方法：

// 以下代码需要从你的应用中完全移除
TrackPlayer.destroy();
TrackPlayer.stop();

替代方案：现在应该使用 pause() 方法来暂停播放，系统会在适当的时候自动管理服务生命周期。

3. 配置文件简化

移除 track-player.json

v3 版本原生支持 HLS、Dash 和 Smoothstreaming 格式，不再需要额外的配置文件：

- track-player.json

注意：你仍然需要在 Track 对象中正确指定音频类型（type）。

4. Android 构建配置更新

SDK 版本要求

必须将 compileSdkVersion 和 targetSdkVersion 至少升级到 31（Android 12）：

// android/build.gradle
compileSdkVersion = 31
targetSdkVersion = 31

行为变化详解

Android 服务管理

在 v3 中，最显著的变化是 Android 音频服务的行为：

1. 服务不可手动停止：系统完全控制服务生命周期
2. 永久通知：这是 Android 系统的强制要求，确保用户可以随时控制播放
3. 后台行为：应用切换到后台时，播放会自动暂停（取决于 stoppingAppPausesPlayback 设置）

用户体验影响

这些变化带来了一些用户体验上的调整：

1. 用户会始终看到播放控制通知
2. 点击通知会返回应用（行为可能因设备厂商而异）
3. 应用无法完全"结束"播放服务，只能暂停播放

最佳实践建议

1. UI 适配：更新你的应用界面，不再提供"完全停止"的选项，改为"暂停"
2. 状态管理：重新检查你的播放状态管理逻辑，适应新的生命周期模型
3. 错误处理：更新错误处理代码，因为某些旧方法调用现在会抛出异常
4. 测试重点：特别关注应用在后台时的行为和多任务场景下的表现

常见问题解答

Q：为什么不能手动停止服务了？ A：这是 Android 系统的限制，为了优化资源管理和电池寿命，系统现在严格控制后台服务。

Q：通知可以自定义吗？ A：可以，你仍然可以通过 updateOptions 方法自定义通知的外观和行为，但不能完全移除它。

Q：如何实现以前 destroy 的功能？ A：现在只需暂停播放并让系统管理资源，不再需要手动销毁播放器。

结语

React Native Track Player v3 的这些变化主要是为了适应现代移动操作系统，特别是 Android 的平台要求。虽然需要一些迁移工作，但这些改进使得库更加稳定和符合平台规范。遵循本指南进行迁移后，你的应用将能够更好地在最新版本的 Android 上运行，同时提供更符合用户期望的音频体验。

react-native-track-player A fully fledged audio module created for music apps. Provides audio playback, external media controls, background mode and more! 项目地址: https://gitcode.com/gh_mirrors/re/react-native-track-player