React Native Track Player 后台模式#

1
import TrackPlayer, { AppKilledPlaybackBehavior } from 'react-native-track-player';
2

3
await TrackPlayer.updateOptions({
4
    android: {
5
        // 配置应用关闭后的播放行为
6
        appKilledPlaybackBehavior: AppKilledPlaybackBehavior.StopPlaybackAndRemoveNotification
7
    },
8
    // 其他配置...
9
});

1
// 检测通知点击
2
import { Linking } from 'react-native';
3

4
Linking.addEventListener('url', (event) => {
5
    if (event.url === 'trackplayer://notification.click') {
6
        // 自定义通知点击行为，例如导航到播放器界面
7
        navigation.navigate('Player');
8
    }
9
});

1
await TrackPlayer.updateOptions({
2
    android: {
3
        // 通知频道 ID
4
        channelId: 'music-player',
5
        // 通知频道名称
6
        channelName: '音乐播放器',
7
        // 通知频道描述
8
        channelDescription: '控制音乐播放',
9
        // 通知频道重要性
10
        channelImportance: TrackPlayer.CHANNEL_IMPORTANCE_LOW,
11
        // 是否显示通知计数
12
        channelShowBadge: true
13
    },
14
    // 其他配置...
15
});

1
await TrackPlayer.updateOptions({
2
    // 通知控制按钮
3
    notificationCapabilities: [
4
        TrackPlayer.CAPABILITY_PLAY,
5
        TrackPlayer.CAPABILITY_PAUSE,
6
        TrackPlayer.CAPABILITY_SKIP_TO_NEXT,
7
        TrackPlayer.CAPABILITY_SKIP_TO_PREVIOUS,
8
        TrackPlayer.CAPABILITY_STOP,
9
        TrackPlayer.CAPABILITY_SEEK_TO
10
    ],
11
    // 锁定屏幕控制按钮
12
    capabilities: [
13
        TrackPlayer.CAPABILITY_PLAY,
14
        TrackPlayer.CAPABILITY_PAUSE,
15
        TrackPlayer.CAPABILITY_SKIP_TO_NEXT,
16
        TrackPlayer.CAPABILITY_SKIP_TO_PREVIOUS
17
    ],
18
    // 其他配置...
19
});

1
import TrackPlayer from 'react-native-track-player';
2

3
await TrackPlayer.updateOptions({
4
    ios: {
5
        // 允许在静音模式下播放
6
        playsInSilentModeIOS: true,
7
        // 配置音频会话类别
8
        category: TrackPlayer.IOSCategory.Playback,
9
        // 配置音频会话模式
10
        mode: TrackPlayer.IOSMode.Default
11
    },
12
    // 其他配置...
13
});

1
import TrackPlayer from 'react-native-track-player';
2

3
await TrackPlayer.updateOptions({
4
    ios: {
5
        // 配置音频会话类别
6
        category: TrackPlayer.IOSCategory.Playback,
7
        // 配置音频会话模式
8
        mode: TrackPlayer.IOSMode.Default,
9
        // 是否允许混音
10
        allowsMixingWithOthers: false
11
    },
12
    // 其他配置...
13
});

1
// 注册媒体会话操作
2
if ('mediaSession' in navigator) {
3
    navigator.mediaSession.setActionHandler('play', () => TrackPlayer.play());
4
    navigator.mediaSession.setActionHandler('pause', () => TrackPlayer.pause());
5
    navigator.mediaSession.setActionHandler('previoustrack', () => TrackPlayer.skipToPrevious());
6
    navigator.mediaSession.setActionHandler('nexttrack', () => TrackPlayer.skipToNext());
7
    navigator.mediaSession.setActionHandler('seekto', (details) => {
8
        if (details.seekTime) {
9
            TrackPlayer.seekTo(details.seekTime * 1000);
10
        }
11
    });
12
}
13

14
// 更新媒体会话元数据
15
function updateMediaSession(track) {
16
    if ('mediaSession' in navigator) {
17
        navigator.mediaSession.metadata = new MediaMetadata({
18
            title: track.title,
19
            artist: track.artist,
20
            album: track.album,
21
            artwork: [
22
                { src: track.artwork, sizes: '96x96', type: 'image/png' },
23
                { src: track.artwork, sizes: '128x128', type: 'image/png' },
24
                { src: track.artwork, sizes: '192x192', type: 'image/png' },
25
                { src: track.artwork, sizes: '256x256', type: 'image/png' },
26
                { src: track.artwork, sizes: '384x384', type: 'image/png' },
27
                { src: track.artwork, sizes: '512x512', type: 'image/png' },
28
            ]
29
        });
30
    }
31
}

1
// 注册 Service Worker
2
if ('serviceWorker' in navigator) {
3
    window.addEventListener('load', () => {
4
        navigator.serviceWorker.register('/service-worker.js')
5
            .then((registration) => {
6
                console.log('Service Worker 注册成功:', registration.scope);
7
            })
8
            .catch((error) => {
9
                console.log('Service Worker 注册失败:', error);
10
            });
11
    });
12
}

1
import TrackPlayer from 'react-native-track-player';
2

3
await TrackPlayer.updateOptions({
4
    // 媒体控制通知配置
5
    notificationCapabilities: [
6
        TrackPlayer.CAPABILITY_PLAY,
7
        TrackPlayer.CAPABILITY_PAUSE,
8
        TrackPlayer.CAPABILITY_SKIP_TO_NEXT,
9
        TrackPlayer.CAPABILITY_SKIP_TO_PREVIOUS,
10
        TrackPlayer.CAPABILITY_SEEK_TO
11
    ],
12
    // 锁定屏幕控制配置
13
    capabilities: [
14
        TrackPlayer.CAPABILITY_PLAY,
15
        TrackPlayer.CAPABILITY_PAUSE,
16
        TrackPlayer.CAPABILITY_SKIP_TO_NEXT,
17
        TrackPlayer.CAPABILITY_SKIP_TO_PREVIOUS
18
    ],
19
    // Android 特定配置
20
    android: {
21
        appKilledPlaybackBehavior: AppKilledPlaybackBehavior.ContinuePlayback
22
    }
23
});

1
await TrackPlayer.updateOptions({
2
    // 通知标题
3
    notificationCapabilities: [
4
        TrackPlayer.CAPABILITY_PLAY,
5
        TrackPlayer.CAPABILITY_PAUSE,
6
        TrackPlayer.CAPABILITY_SKIP_TO_NEXT,
7
        TrackPlayer.CAPABILITY_SKIP_TO_PREVIOUS
8
    ],
9
    // Android 通知自定义
10
    android: {
11
        // 通知频道 ID
12
        channelId: 'music-player',
13
        // 通知频道名称
14
        channelName: '音乐播放器',
15
        // 通知频道描述
16
        channelDescription: '控制音乐播放',
17
        // 通知小图标
18
        smallIcon: 'ic_notification',
19
        // 大图标
20
        largeIcon: 'ic_launcher',
21
        // 通知颜色
22
        iconColor: '#FF0000',
23
        // 通知控制按钮颜色
24
        playIcon: 'ic_play',
25
        pauseIcon: 'ic_pause',
26
        previousIcon: 'ic_previous',
27
        nextIcon: 'ic_next',
28
        // 停止图标
29
        stopIcon: 'ic_stop'
30
    },
31
    // iOS 通知自定义
32
    ios: {
33
        // 应用图标
34
        appIcon: 'AppIcon',
35
        // 播放图标
36
        playIcon: 'play',
37
        // 暂停图标
38
        pauseIcon: 'pause',
39
        // 上一曲图标
40
        previousIcon: 'previous',
41
        // 下一曲图标
42
        nextIcon: 'next'
43
    }
44
});

1
// 播放新曲目时更新元数据
2
await TrackPlayer.load({
3
    id: 'track-1',
4
    url: 'https://example.com/track.mp3',
5
    title: '歌曲标题',
6
    artist: '艺术家名称',
7
    album: '专辑名称',
8
    artwork: 'https://example.com/artwork.jpg'
9
});

1
import { AppState, AppStateStatus } from 'react-native';
2

3
const appState = AppState.currentState;
4
let backgroundTime = 0;
5

6
const handleAppStateChange = (nextAppState: AppStateStatus) => {
7
    if (appState.match(/inactive|background/) && nextAppState === 'active') {
8
        // 应用从后台返回前台
9
        console.log('应用进入前台');
10
        // 更新播放状态
11
    } else if (appState === 'active' && nextAppState.match(/inactive|background/)) {
12
        // 应用从前台进入后台
13
        console.log('应用进入后台');
14
        backgroundTime = Date.now();
15
    }
16
    appState = nextAppState;
17
};
18

19
AppState.addEventListener('change', handleAppStateChange);

1
await TrackPlayer.updateOptions({
2
    android: {
3
        // 音频焦点模式
4
        audioFocusMode: TrackPlayer.AUDIO_FOCUS_MODE_GAIN,
5
        // 音频流类型
6
        audioAttributes: {
7
            contentType: TrackPlayer.AUDIO_CONTENT_TYPE_MUSIC,
8
            flags: TrackPlayer.AUDIO_FLAG_AUDIBILITY_ENFORCED,
9
            usage: TrackPlayer.AUDIO_USAGE_MEDIA
10
        }
11
    },
12
    // 其他配置...
13
});

1
// 监听音频中断事件
2
import { Audio } from 'expo-av';
3

4
Audio.setAudioModeAsync({
5
    allowsRecordingIOS: false,
6
    playsInSilentModeIOS: true,
7
    shouldDuckAndroid: true,
8
    staysActiveInBackground: true,
9
    playThroughEarpieceAndroid: false
10
});
11

12
const handleAudioInterruption = (interruption) => {
13
    if (interruption.isPlaying) {
14
        // 中断结束，恢复播放
15
        TrackPlayer.play();
16
    } else {
17
        // 中断开始，暂停播放
18
        TrackPlayer.pause();
19
    }
20
};
21

22
// 注册中断监听器
23
Audio.addAudioInterruptionListener(handleAudioInterruption);

1
// Android 音频路由变化监听
2
import { AudioManager } from 'react-native-audio-manager';
3

4
AudioManager.setListener((result) => {
5
    if (result.event === 'headsetPlug') {
6
        if (result.isPlugged) {
7
            console.log('耳机已插入');
8
        } else {
9
            console.log('耳机已拔出');
10
        }
11
    } else if (result.event === 'audiobecomingnoisy') {
12
        console.log('音频变得嘈杂，暂停播放');
13
        TrackPlayer.pause();
14
    }
15
});
16

17
// 注册监听
18
AudioManager.registerListener();
19

20

21
### 7.3 远程控制不工作
22

23
如果远程控制（如锁屏控制）不工作：
24
- **Android**: 确保通知正在显示且已配置正确的通知频道
25
- **iOS**: 在真实设备上测试，而非模拟器
26
- **Web**: 浏览器不支持媒体会话 API 或需要 HTTPS
27
- **跨平台**: 确保已正确配置 `capabilities` 和 `notificationCapabilities`
28

29
### 7.4 iOS 审核注意事项
30

31
在提交 iOS 应用到 App Store 时，需要注意：
32
- 必须明确说明应用需要后台音频功能
33
- 应用必须在后台播放时有明确的用户价值
34
- 避免在后台播放无意义的音频
35

36
## 8. 最佳实践
37

38
1. **始终注册播放服务**: 确保在应用启动时注册播放服务
39
2. **正确配置后台模式**: 特别是在 iOS 平台上
40
3. **处理应用生命周期**: 监听应用进入前台/后台的事件
41
4. **优化资源使用**: 在后台时减少不必要的网络请求和计算
42
5. **测试真实设备**: 始终在真实设备上测试后台音频功能
43
6. **请求必要权限**: 在使用前请求通知和音频权限
44
7. **提供清晰的用户控制**: 让用户可以轻松开启/关闭后台播放
45
8. **遵循平台指南**: 遵守各平台的后台处理最佳实践
46
9. **处理边缘情况**: 如网络中断、音频文件错误等
47
10. **考虑电池寿命**: 避免在后台过度使用资源
48

49
后台模式是音乐播放器应用的核心功能之一。通过正确配置和使用 React Native Track Player 的后台音频功能，你可以为用户提供流畅的音乐播放体验，即使应用在后台运行或设备屏幕关闭。
50

51
## 9. 性能优化
52

53
### 9.1 内存优化
54

55
在后台播放音频时，内存管理非常重要：
56

57
1. **及时释放资源**: 当不再需要播放服务时，调用 `TrackPlayer.destroy()` 释放资源
58
2. **限制后台活动**: 减少后台任务的频率和复杂度
59
3. **优化网络请求**: 使用缓存和批量请求减少网络开销
60
4. **避免内存泄漏**: 正确管理事件监听器和定时器
61

62
```javascript
63
// 组件卸载时清理资源
64
useEffect(() => {
65
    return () => {
66
        // 移除事件监听器
67
        AppState.removeEventListener('change', handleAppStateChange);
68
        // 如果不再需要播放服务，销毁它
69
        if (shouldDestroy) {
70
            TrackPlayer.destroy();
71
        }
72
    };
73
}, []);