React Native Track Player 入门指南#

1. 基础设置#

在开始使用 React Native Track Player 之前，建议先了解不同平台支持的功能差异，这有助于您在开发过程中避免不必要的问题。

提示：关于各平台支持的功能详细对比，请参考《平台支持》文档。

1.1 注册播放服务#

播放服务是 React Native Track Player 的核心组件，它负责处理后台播放和远程控制事件。

首先，在项目中创建一个播放服务文件。以下是 JavaScript 版本的示例：

1
const TrackPlayer = require('react-native-track-player');
2

3
module.exports = async function() {
4
    // 在这里添加事件监听器
5
    // 更详细的事件处理请参考《播放服务》文档
6
};

然后，在应用的入口文件中注册播放服务（通常在项目根目录的 index.js 文件中）：

1
// AppRegistry.registerComponent(...);
2
TrackPlayer.registerPlaybackService(() => require('./service'));

注意：如果你使用 TypeScript，可以创建更结构化的播放服务。详细信息请参考《播放服务》文档。

1.2 设置播放器#

接下来，你需要设置播放器。这通常需要不到一秒钟的时间：

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

3
await TrackPlayer.setupPlayer();
4
// 播放器已准备好使用

请确保在与 TrackPlayer 的任何其他功能交互之前完成设置方法，以避免不稳定。

2. 控制播放器#

2.1 向播放队列添加轨道#

你可以使用 URL 或通过在应用包或文件系统中引用文件来向播放器添加轨道。

首先，你需要创建一个轨道对象，这是一个普通的 JavaScript 对象，包含描述轨道的多个属性：

1
var track1 = {
2
    url: 'http://example.com/avaritia.mp3', // 从网络加载媒体
3
    title: 'Avaritia',
4
    artist: 'deadmau5',
5
    album: 'while(1<2)',
6
    genre: 'Progressive House, Electro House',
7
    date: '2014-05-20T07:00:00+00:00', // RFC 3339 格式
8
    artwork: 'http://example.com/cover.png', // 从网络加载封面
9
    duration: 402 // 持续时间（秒）
10
};
11

12
const track2 = {
13
    url: require('./coelacanth.ogg'), // 从应用包加载媒体
14
    title: 'Coelacanth I',
15
    artist: 'deadmau5',
16
    artwork: require('./cover.jpg'), // 从应用包加载封面
17
    duration: 166
18
};
19

20
const track3 = {
21
    url: 'file:///storage/sdcard0/Downloads/artwork.png', // 从文件系统加载媒体
22
    title: 'Ice Age',
23
    artist: 'deadmau5',
24
    // 从文件系统加载封面：
25
    artwork: 'file:///storage/sdcard0/Downloads/cover.png',
26
    duration: 411
27
};

然后将这些轨道添加到队列中：

1
// 你可以将项目添加到队列中
2
await TrackPlayer.add([track1, track2, track3]);

2.2 获取播放器信息#

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

3
const state = await TrackPlayer.getState();
4
if (state === State.Playing) {
5
    console.log('播放器正在播放');
6
};
7

8
let trackIndex = await TrackPlayer.getCurrentTrack();
9
let trackObject = await TrackPlayer.getTrack(trackIndex);
10
console.log(`标题: ${trackObject.title}`);
11

12
const position = await TrackPlayer.getPosition();
13
const duration = await TrackPlayer.getDuration();
14
console.log(`${duration - position} 秒剩余。`);

2.3 更改播放状态#

1
TrackPlayer.play();
2
TrackPlayer.pause();
3
TrackPlayer.reset();
4

5
// 跳转到 12.5 秒：
6
TrackPlayer.seekTo(12.5);
7

8
// 将音量设置为 50%：
9
TrackPlayer.setVolume(0.5);

2.4 控制队列#

1
// 跳转到特定轨道索引：
2
await TrackPlayer.skip(trackIndex);
3

4
// 跳转到队列中的下一个轨道：
5
await TrackPlayer.skipToNext();
6

7
// 跳转到队列中的上一个轨道：
8
await TrackPlayer.skipToPrevious();
9

10
// 从队列中移除两个轨道：
11
await TrackPlayer.remove([trackIndex1, trackIndex2]);
12

13
// 检索队列中的轨道对象：
14
const tracks = await TrackPlayer.getQueue();
15
console.log(`第一个标题: ${tracks[0].title}`);

3. 播放事件#

你可以订阅播放器事件，这些事件描述了播放状态的变化性质。例如，订阅 Event.PlaybackTrackChanged 事件以在轨道更改时收到通知，或订阅 Event.PlaybackState 事件以在播放器缓冲、播放、暂停和停止时收到通知。

3.1 示例#

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

3
const PlayerInfo = () => {
4
    const [trackTitle, setTrackTitle] = useState<string>();
5

6
    // 进行初始设置，设置初始 trackTitle..
7

8
    useTrackPlayerEvents([Event.PlaybackTrackChanged], async event => {
9
        if (event.type === Event.PlaybackTrackChanged && event.nextTrack != null) {
10
            const track = await TrackPlayer.getTrack(event.nextTrack);
11
            const {title} = track || {};
12
            setTrackTitle(title);
13
        }
14
    });
15

16
    return (
17
        <Text>{trackTitle}</Text>
18
    );
19
}

4. 进度更新#

音乐应用通常需要一种自动方式来显示正在播放轨道的进度。为此，我们创建了 useProgress 钩子，它会自动更新自己。

4.1 示例#

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

3
const MyPlayerBar = () => {
4
    const progress = useProgress();
5

6
    return (
7
            // 注意：formatTime 和 ProgressBar 只是示例：
8
            <View>
9
                <Text>{formatTime(progress.position)}</Text>
10
                <ProgressBar
11
                    progress={progress.position}
12
                    buffered={progress.buffered}
13
                />
14
            </View>
15
        );
16
}