Expo 视频 (expo-video)

提供 API 以实现应用中的视频播放的库。

expo-video 是一个跨平台、高性能的视频组件，用于 React Native 和 Expo，并支持 Web。

¥expo-video is a cross-platform, performant video component for React Native and Expo with Web support.

安装

¥Installation

If you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.

应用配置中的配置

¥Configuration in app config

如果你在项目中使用配置插件（EAS 构建 或 npx expo run:[android|ios]），则可以使用其内置的 配置插件 配置 expo-video。该插件允许你配置无法在运行时设置的各种属性，并且需要构建新的应用二进制文件才能生效。如果你的应用不使用 EAS Build，则你需要手动配置包。

¥You can configure expo-video using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use EAS Build, then you'll need to manually configure the package.

Example app.json with config plugin

{
"expo": {
  "plugins": [
    [
      "expo-video",
      {
        "supportsBackgroundPlayback": true,
        "supportsPictureInPicture": true
      }
    ]
  ],
}
}

Configurable properties

用法

¥Usage

这是一个带有播放和暂停按钮的视频的简单示例。

¥Here's a simple example of a video with a play and pause button.

import { useEvent } from 'expo';
import { useVideoPlayer, VideoView } from 'expo-video';
import { StyleSheet, View, Button } from 'react-native';

const videoSource =
'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4';

export default function VideoScreen() {
const player = useVideoPlayer(videoSource, player => {
  player.loop = true;
  player.play();
});

const { isPlaying } = useEvent(player, 'playingChange', { isPlaying: player.playing });

return (
  <View style={styles.contentContainer}>
    <VideoView style={styles.video} player={player} allowsFullscreen allowsPictureInPicture />
    <View style={styles.controlsContainer}>
      <Button
        title={isPlaying ? 'Pause' : 'Play'}
        onPress={() => {
          if (isPlaying) {
            player.pause();
          } else {
            player.play();
          }
        }}
      />
    </View>
  </View>
);
}

const styles = StyleSheet.create({
contentContainer: {
  flex: 1,
  padding: 10,
  alignItems: 'center',
  justifyContent: 'center',
  paddingHorizontal: 50,
},
video: {
  width: 350,
  height: 275,
},
controlsContainer: {
  padding: 10,
},
});

推荐资源

¥Receiving events

VideoPlayer 属性中的更改不会更新 React 状态。因此，要显示有关 VideoPlayer 当前状态的信息，必须监听它发出的 events。事件系统基于 expo 包中的 EventEmitter 类和 hooks。有几种方法可以监听事件：

¥The changes in properties of the VideoPlayer do not update the React state. Therefore, to display the information about the current state of the VideoPlayer, it is necessary to listen to the events it emits. The event system is based on the EventEmitter class and hooks from the expo package. There are a few ways to listen to events:

useEvent 钩

¥useEvent hook

创建一个监听器，该监听器将返回可在组件中使用的状态值。它还会在组件卸载时自动清理。

¥Creates a listener that will return a stateful value that can be used in a component. It also cleans up automatically when the component unmounts.

import { useEvent } from 'expo';
// ... Other imports, definition of the component, creating the player etc.

const { status, error } = useEvent(player, 'statusChange', { status: player.status });
// Rest of the component...

useEventListener 钩

¥useEventListener hook

围绕 Player.addListener 和 Player.removeListener 方法构建，创建具有自动清理功能的事件监听器。

¥Built around the Player.addListener and Player.removeListener methods, creates an event listener with automatic cleanup.

import { useEventListener } from 'expo';
// ...Other imports, definition of the component, creating the player etc.

useEventListener(player, 'statusChange', ({ status, error }) => {
  setPlayerStatus(status);
  setPlayerError(error);
  console.log('Player status changed: ', status);
});
// Rest of the component...

Player.addListener 方法

¥Player.addListener method

监听事件的最灵活方式，但需要手动清理和更多样板代码。

¥Most flexible way to listen to events, but requires manual cleanup and more boilerplate code.

// ...Imports, definition of the component, creating the player etc.

useEffect(() => {
  const subscription = player.addListener('statusChange', ({ status, error }) => {
    setPlayerStatus(status);
    setPlayerError(error);
    console.log('Player status changed: ', status);
  });

  return () => {
    subscription.remove();
  };
}, []);
// Rest of the component...

从资源目录播放本地媒体

¥Playing local media from the assets directory

expo-video 支持播放使用 require 功能加载的本地媒体。你可以直接将结果用作源，或者如果你还想配置其他属性，则将其分配给 VideoSource 的 assetId 参数。

¥expo-video supports playing local media loaded using the require function. You can use the result as a source directly, or assign it to the assetId parameter of a VideoSource if you also want to configure other properties.

import { VideoSource } from 'expo-video';

const assetId = require('./assets/bigbuckbunny.mp4');

const videoSource: VideoSource = {
  assetId,
  metadata: {
    title: 'Big Buck Bunny',
    artist: 'The Open Movie Project',
  },
};

const player1 = useVideoPlayer(assetId); // You can use the `asset` directly as a video source
const player2 = useVideoPlayer(videoSource);

预加载视频

¥Preloading videos

在播放另一个视频时，可以先加载视频，然后再在视图中显示它。这允许后续视频之间更快地转换并提供更好的用户体验。

¥While another video is playing, a video can be loaded before showing it in the view. This allows for quicker transitions between subsequent videos and a better user experience.

要预加载视频，你必须创建一个带有视频源的 VideoPlayer。即使播放器未连接到 VideoView，它也会填充缓冲区。一旦连接到 VideoView，它将能够开始播放而无需缓冲。

¥To preload a video, you have to create a VideoPlayer with a video source. Even when the player is not connected to a VideoView, it will fill the buffers. Once it is connected to the VideoView, it will be able to start playing without buffering.

在某些情况下，在屏幕生命周期的后期预加载视频是有益的。在这种情况下，应该创建一个带有 null 源的 VideoPlayer。要开始预加载，请使用 replace() 函数将播放器源替换为视频源。

¥In some cases, it is beneficial to preload a video later in the screen lifecycle. In that case, a VideoPlayer with a null source should be created. To start preloading, replace the player source with a video source using the replace() function.

以下是如何预加载视频的示例：

¥Here is an example of how to preload a video:

import { useVideoPlayer, VideoView, VideoSource } from 'expo-video';
import { useState, useCallback } from 'react';
import { StyleSheet, Text, TouchableOpacity, View } from 'react-native';

const bigBuckBunnySource: VideoSource =
'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4';

const elephantsDreamSource: VideoSource =
'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4';

export default function PreloadingVideoPlayerScreen() {
const player1 = useVideoPlayer(bigBuckBunnySource, player => {
  player.play();
});

const player2 = useVideoPlayer(elephantsDreamSource, player => {
  player.currentTime = 20;
});

const [currentPlayer, setCurrentPlayer] = useState(player1);

const replacePlayer = useCallback(async () => {
  currentPlayer.pause();
  if (currentPlayer === player1) {
    setCurrentPlayer(player2);
    player1.pause();
    player2.play();
  } else {
    setCurrentPlayer(player1);
    player2.pause();
    player1.play();
  }
}, [player1, currentPlayer]);

return (
  <View style={styles.contentContainer}>
    <VideoView player={currentPlayer} style={styles.video} nativeControls={false} />
    <TouchableOpacity style={styles.button} onPress={replacePlayer}>
      <Text style={styles.buttonText}>Replace Player</Text>
    </TouchableOpacity>
  </View>
);
}

const styles = StyleSheet.create({
contentContainer: {
  flex: 1,
  padding: 10,
  alignItems: 'center',
  justifyContent: 'center',
  paddingHorizontal: 50,
},
button: {
  alignItems: 'center',
  justifyContent: 'center',
  borderRadius: 3,
  paddingVertical: 8,
  paddingHorizontal: 12,
  backgroundColor: '#4630ec',
},
buttonText: {
  fontSize: 12,
  fontWeight: 'bold',
  color: '#eeeeee',
  textAlign: 'center',
},
video: {
  width: 300,
  height: 168.75,
  marginVertical: 20,
},
});

不使用其他 EAS 服务

¥Using the VideoPlayer directly

在大多数情况下，应使用 useVideoPlayer 钩子来创建 VideoPlayer 实例。它管理播放器的生命周期，并确保在卸载组件时正确处理它。但是，在某些高级用例中，可能需要创建一个在卸载组件时不会自动销毁的 VideoPlayer。在这些情况下，可以使用 createVideoPlayer 函数创建 VideoPlayer。你需要了解这种方法带来的风险，因为当不再需要播放器时，你有责任调用 release() 方法。如果处理不当，这种方法可能会导致内存泄漏。

¥In most cases, the useVideoPlayer hook should be used to create a VideoPlayer instance. It manages the player's lifecycle and ensures that it is properly disposed of when the component is unmounted. However, in some advanced use cases, it might be necessary to create a VideoPlayer that does not get automatically destroyed when the component is unmounted. In those cases, the VideoPlayer can be created using the createVideoPlayer function. You need be aware of the risks that come with this approach, as it is your responsibility to call the release() method when the player is no longer needed. If not handled properly, this approach may lead to memory leaks.

import { createVideoPlayer } from 'expo-video';
const player = createVideoPlayer(videoSource);

API

import { VideoView, useVideoPlayer } from 'expo-video';

Component

Component Methods

Hooks

Classes

Methods

Types