react-native-video中文文档

拼搏现实的明天。 2022-02-20 06:06 446阅读 0赞

一个react-native视频播放组件，可以实现视频播放的效果。  
要求react-native版本 >= 0.40.0；对于RN支持0.19.0 - 0.39.0，请使用1.0之前的版本。

### 最新版本(3.0.0)改动 ###

3.0版对现有行为进行了许多更改。 请参阅\#更新

## 目录 ##

*  安装
 *  使用
 *  更新

### 一、安装 ###

使用npm安装依赖库：

npm install --save react-native-video
    
     
      
     
      
       1

或者用yarn：

yarn add react-native-video
    
     
      
     
      
       1

#### IOS环境下： ####

直接运行下面命令来链接react-native-video库。

react-native link 
    
     
      
     
      
       1

如果你想允许其他应用在你的视频组件上播放音乐，请打开AppDelegate.m文件并且添加：

AppDelegate.m

#import <AVFoundation/AVFoundation.h> // import
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
      ...
      [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryAmbient error:nil];  // allow
      ...
    }
     
      
     
      
       1
       2
       3
       4
       5
       6
       7
       8

#### Android环境下： ####

直接运行下面命令来链接react-native-video库。

react-native link 
    
     
      
     
      
       1

如果上面的方式失败了，那么你可以尝试手动添加配置，这步比较麻烦。

android/settings.gradle  
较新的ExoPlayer库适用于大多数人。(推荐使用这个库)

include ':react-native-video'
    project(':react-native-video').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-video/android-exoplayer')
     
      
     
      
       1
       2

如果您需要使用旧的基于Android MediaPlayer的播放器，请改用以下内容：

include ':react-native-video'
    project(':react-native-video').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-video/android')
     
      
     
      
       1
       2

android/app/build.gradle

dependencies {
       ...
       compile project(':react-native-video')
    }
     
      
     
      
       1
       2
       3
       4

MainApplication.java  
在java文件顶部位置记得添加import：

import com.brentvatne.react.ReactVideoPackage;
     
      
     
      
       1

将ReactVideoPackage类添加到导出的包列表中:

@Override
    protected List<ReactPackage> getPackages() {
        return Arrays.asList(
                new MainReactPackage(),
                new ReactVideoPackage()
        );
    }
     
      
     
      
       1
       2
       3
       4
       5
       6
       7

### 二、使用 ###

//在渲染函数中，假设你的项目中有一个名为“background.mp4”的文件。 
    //如果你愿意，可以在一个屏幕上添加多个视频。
    <Video source={
       {uri: "background"}}   // 可以是一个 URL 或者 本地文件
           ref={(ref) => {
             this.player = ref
           }}                                      
           onBuffer={
       this.onBuffer}                // 远程视频缓冲时的回调
           onEnd={
       this.onEnd}                      // 播放完成后的回调
           onError={
       this.videoError}               // 播放失败后的回调
           onFullscreenPlayerWillPresent={
       this.fullScreenPlayerWillPresent} // 全屏启动前的回调
           onFullscreenPlayerDidPresent={
       this.fullScreenPlayerDidPresent}   // 全屏启动后的回调
           onFullscreenPlayerWillDismiss={
       this.fullScreenPlayerWillDismiss} // 全屏停止前的回调
           onFullscreenPlayerDidDismiss={
       this.fullScreenPlayerDidDismiss}  // 全屏停止后的回调
           style={styles.backgroundVideo} />
    
    // 稍后触发全屏
    this.player.presentFullscreenPlayer()
    
    // 禁止全屏
    this.player.dismissFullscreenPlayer()
    
    // 设置视频播放的位置（从0秒开始）
    this.player.seek(0)
    
    // 设置组件样式
    var styles = StyleSheet.create({
      backgroundVideo: {
        position: 'absolute',
        top: 0,
        left: 0,
        bottom: 0,
        right: 0,
      },
    });
     
      
     
      
       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16
       17
       18
       19
       20
       21
       22
       23
       24
       25
       26
       27
       28
       29
       30
       31
       32
       33
       34

#### 可配置属性 ####

*  [allowsExternalPlayback][]
 *  [audioOnly][]
 *  [ignoreSilentSwitch][]
 *  [muted][]
 *  [paused][]
 *  [playInBackground][]
 *  [playWhenInactive][]
 *  [poster][]
 *  [posterResizeMode][]
 *  [progressUpdateInterval][]
 *  [rate][]
 *  [repeat][]
 *  [resizeMode][]
 *  [selectedTextTrack][]
 *  [stereoPan][]
 *  [textTracks][]
 *  [useTextureView][]
 *  [volume][]

#### 事件属性 ####

*  [onLoad][]
 *  [onLoadStart][]
 *  [onProgress][]
 *  [onTimedMetadata][]

#### 方法 ####

*  [seek][]

##### 1、可配置参数 #####

*allowsExternalPlayback*  
指示播放器是否允许切换到AirPlay或HDMI等外部播放模式。  
\* true(默认) - 运行切换到其他外部播放模式  
\* false - 不允许切换到其他外部播放模式  
适用平台：IOS

--------------------

*audioOnly*  
指示播放器是否应仅播放音轨而不是显示视频轨道，而是显示视频poster(海报)。  
\* false(默认) - 仅正常播放视频  
\* true - 展示海报和播放视频  
如果audioOnly设置为true，那么poster属性必须有值设置进去。  
适用平台：IOS、Android通用

--------------------

*ignoreSilentSwitch*  
控制iOS静默开关行为。  
\* “inherit”(默认) - 使用默认的AVPlayer开关行为  
\* “ignore” - 即使设置了静音开关，也要播放音频  
\* “obey” - 如果设置了静音开关，请勿播放音频  
适用平台：IOS

--------------------

*muted*  
控制音频是否静音。  
\* false(默认) - 不要静音  
\* true - 静音  
适用平台：IOS、Android通用

--------------------

*paused*  
控制播放器是否暂停。  
\* false(默认) - 暂停播放  
\* true - 不要暂停播放  
适用平台：IOS、Android通用

--------------------

*playInBackground*  
确定应用程序在后台时是否应继续播放媒体。 这允许客户继续收听音频。  
\* false (默认) - 不继续播放视频  
\* true - 后台继续播放视频

注意：要在IOS适用此功能，你还必须：  
\* [Enable Background Audio][] 在你的Xcode项目中  
\* 将ignoreSilentSwitch 属性值prop设置为”ignore”  
适用平台：iOS、Android ExoPlayer、 Android MediaPlayer

--------------------

*playWhenInactive*  
在通知或控制中心位于视频前面时是否应继续播放媒体。  
\* false(默认) - 不继续播放视频  
\* true - 继续播放视频  
适用平台：IOS

--------------------

*poster*  
加载视频时要显示的图像值：带有海报URL的字符串，例如“[https://baconmockup.com/300/200/][https_baconmockup.com_300_200]”。  
适用平台：IOS、Android

--------------------

*posterResizeMode*  
确定当帧与原始视频尺寸不匹配时如何调整海报图像的大小。  
\* “contain”(默认) - 均匀缩放图像（保持图像的纵横比），使图像的尺寸（宽度和高度）等于或小于视图的相应尺寸（减去填充）  
\* “center” - 使图像沿两个维度居中。 如果图像大于视图，请将其均匀缩小以使其包含在视图中  
\* “cover” - 均匀缩放图像（保持图像的纵横比），使图像的尺寸（宽度和高度）等于或大于视图的相应尺寸（减去填充）  
\* “none” - 不调整大小  
\* “repeat” - 重复图像以覆盖视图的框架。 图像将保持其大小和纵横比 （仅限iOS）  
\* “stretch” - 独立缩放宽度和高度，这可能会改变src的宽高比  
适用平台：IOS、Android

--------------------

*progressUpdateInterval*  
onProgress事件之间的毫秒延迟（以毫秒为单位）。  
默认: 250.0  
适用平台：IOS、Android

--------------------

*rate*  
视频播放的速率。  
\* 0.0 - 暂停播放  
\* 1.0 - 正常速率播放  
\* 其他值 - 自定义速率，例如0.5慢速播放或者2.0快速播放  
适用平台：IOS、Android

注意：对于Android的播放器，rate属性仅在Android6.0或者更高版本中生效。

--------------------

*repeat*  
确定在到达结尾时是否重复播放视频。  
\* flase(默认) - 不重复播放  
\* true - 重复播放  
适用平台：IOS、Android

--------------------

*resizeMode*  
确定当帧与原始视频尺寸不匹配时如何调整视频大小。  
\* “none”(默认) - 不匹配大小  
\* “contain” - 均匀缩放视频（保持视频的宽高比），使视频的尺寸（宽度和高度）等于或小于视图的相应尺寸（减去填充）  
\* “cover” - 均匀缩放视频（保持视频的宽高比），使图像的尺寸（宽度和高度）等于或大于视图的相应尺寸（减去填充）  
\* “stretch” - 独立缩放宽度和高度，这可能会改变src的宽高比  
适用平台：IOS、 Android ExoPlayer、Android MediaPlayer

--------------------

*selectedTextTrack*  
配置显示哪个文本轨道（标题或副标题）（如果有）。

selectedTextTrack={ { type: Type, value: Value }}
     
      
     
      
       1
       2
       3
       4

例子：

selectedTextTrack={ { type: "title", value: "English Subtitles" }}
     
      
     
      
       1
       2
       3
       4

<table> 
 <thead> 
  <tr> 
   <th>Type</th> 
   <th>Value</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>“system”(默认)</td> 
   <td>N/A</td> 
   <td>仅在启用了字幕的系统首选项时显示标题</td> 
  </tr> 
  <tr> 
   <td>“disabled”</td> 
   <td>N/A</td> 
   <td>不显示文本轨道</td> 
  </tr> 
  <tr> 
   <td>“title”</td> 
   <td>string</td> 
   <td>显示标题为值的文本轨道，例如 “法国1”</td> 
  </tr> 
  <tr> 
   <td>“language”</td> 
   <td>string</td> 
   <td>显示指定为值的语言显示文本轨道，例如“FR”</td> 
  </tr> 
  <tr> 
   <td>“index”</td> 
   <td>number</td> 
   <td>显示指定为值的索引的文本轨道，例如0</td> 
  </tr> 
 </tbody> 
</table>

iOS和Android（仅限4.4及更高版本）均提供设置，以便为听障人士提供字幕。 如果选择“系统”并启用了字幕设置，iOS / Android将查找与该客户的语言匹配的标题并显示它。  
如果匹配指定类型（和值，如果适用）的轨道不可用，则不会显示任何文本轨道。 如果多个曲目符合条件，则将使用第一个匹配。  
适用平台：Android ExoPlayer，IOS

--------------------

*stereoPan*  
调整左右音频通道的平衡。 接受-1.0和1.0之间的任何值。  
\* -1.0 - 满左音频  
\* 0.0(默认) - 居中  
\* 1.0 - 满右音频  
适用平台：Android MediaPlayer

--------------------

*textTracks*  
加载一个或多个“sidecar”文本轨道。 这需要一组表示每个轨道的对象。 每个对象应具有以下格式：

<table> 
 <thead> 
  <tr> 
   <th>Property</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>title</td> 
   <td>文本轨道的名称</td> 
  </tr> 
  <tr> 
   <td>language</td> 
   <td>代表语言的2个字母ISO 639-1代码</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>Mime类型的轨道 ：TextTrackType.SRT - .srt SubRip Subtitle、TextTrackType.TTML - .ttml TTML、TextTrackType.VTT - .vtt WebVTT(这个也一般用不到)</td> 
  </tr> 
  <tr> 
   <td>uri</td> 
   <td>文本轨道的URL。目前，仅支持在网络服务器上托管的种类</td> 
  </tr> 
 </tbody> 
</table>

例子：

import { TextTrackType }, Video from 'react-native-video';
    
    textTracks={[
      {
        title: "English CC",
        language: "en",
        type: "text/vtt", TextTrackType.VTT,
        uri: "https://bitdash-a.akamaihd.net/content/sintel/subtitles/subtitles_en.vtt"
      },
      {
        title: "Spanish Subtitles",
        language: "es",
        type: "application/x-subrip", TextTrackType.SRT,
        uri: "https://durian.blender.org/wp-content/content/subtitles/sintel_es.srt"
      }
    ]}
     
      
     
      
       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16

这不支持iOS，因为AVPlayer不支持它。 必须将文本轨道作为HLS播放列表的一部分加载。  
适用平台：Android ExoPlayer

--------------------

*useTextureView*  
输出到TextureView而不是默认的SurfaceView。 通常，您需要使用SurfaceView，因为它更高效并提供更好的性能。 但是，SurfaceViews有两个限制：  
\* 它无法使用动画，转换或缩放  
\* 你无法覆盖多个SurfaceView  
useTextureView只能在设置源的同时进行设置。  
\* false(默认) - 使用SurfaceView  
\* true - 使用TextureView  
适用平台：Android ExoPlayer

--------------------

*volume*  
调整音量  
\* 1.0 - 满音量  
\* 0.0 - 将音频静音  
\* 其他值 - 减小音量  
适用平台：IOS、Android

--------------------

##### 2、事件参数 #####

*onLoad*  
加载媒体并准备播放时调用的回调函数。  
Payload（有效负载）：

<table> 
 <thead> 
  <tr> 
   <th>Property</th> 
   <th>Value</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>currentPosition</td> 
   <td>number</td> 
   <td>视频开始播放的时间（以秒为单位）</td> 
  </tr> 
  <tr> 
   <td>duration</td> 
   <td>number</td> 
   <td>视频时间长度（以秒为单位）</td> 
  </tr> 
  <tr> 
   <td>naturalSize</td> 
   <td>object</td> 
   <td>属性：width - 视频编码的宽度（以像素为单位）；height - 视频编码的高度（以像素为单位）；orientation - “portrait”或者”landscape”</td> 
  </tr> 
  <tr> 
   <td>textTracks</td> 
   <td>array</td> 
   <td>一组文本跟踪信息对象，具有以下属性：index ,title ,language,type</td> 
  </tr> 
 </tbody> 
</table>

{
      canPlaySlowForward: true,
      canPlayReverse: false,
      canPlaySlowReverse: false,
      canPlayFastForward: false,
      canStepForward: false,
      canStepBackward: false,
      currentTime: 0,
      duration: 5910.208984375,
      naturalSize: {
         height: 1080
         orientation: 'landscape'
         width: '1920'
      },
      textTracks: [
        { title: '#1 French', language: 'fr', index: 0, type: 'text/vtt' },
        { title: '#2 English CC', language: 'en', index: 1, type: 'text/vtt' },
        { title: '#3 English Director Commentary', language: 'en', index: 2, type: 'text/vtt' }
      ]
    }
    
     
      
     
      
       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16
       17
       18
       19
       20

适用平台：IOS、Android

--------------------

*onLoadStart*  
媒体开始加载时调用的回调函数。  
Payload（有效负载）：

<table> 
 <thead> 
  <tr> 
   <th>Property</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>isNetwork</td> 
   <td>boolean</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>string</td> 
  </tr> 
  <tr> 
   <td>uri</td> 
   <td>string</td> 
  </tr> 
 </tbody> 
</table>

例子：

{
      isNetwork: true,
      type: '',
      uri: 'https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8'
    }
    
     
      
     
      
       1
       2
       3
       4
       5

适用平台：IOS、Android

--------------------

*onProgress*  
视频播放过程中每个间隔进度单位（通常不足一秒，你可以打印日志测试下）调用的回调，其中包含有关媒体当前正在播放的位置的信息。

<table> 
 <thead> 
  <tr> 
   <th>Property</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>currentTime</td> 
   <td>number</td> 
  </tr> 
  <tr> 
   <td>playableDuration</td> 
   <td>number</td> 
  </tr> 
  <tr> 
   <td>seekableDuration</td> 
   <td>number</td> 
  </tr> 
 </tbody> 
</table>

例子：

{
      currentTime: 5.2,
      playableDuration: 34.6,
      seekableDuration: 888
    }
    
     
      
     
      
       1
       2
       3
       4
       5

--------------------

*onTimedMetadata*  
当定时元数据可用时调用的回调函数.

<table> 
 <thead> 
  <tr> 
   <th>Property</th> 
   <th>Type</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>metadata</td> 
   <td>array</td> 
   <td>Array of metadata objects</td> 
  </tr> 
 </tbody> 
</table>

例子：

{
      metadata: [
        { value: 'Streaming Encoder', identifier: 'TRSN' },
        { value: 'Internet Stream', identifier: 'TRSO' },
        { value: 'Any Time You Like', identifier: 'TIT2' }
      ]
    }
    
     
      
     
      
       1
       2
       3
       4
       5
       6
       7

适用平台：IOS、Android ExoPlayer

--------------------

##### 3、方法 #####

方法对引用Video元素的ref引用进行操作。 你可以使用以下代码创建引用：

return (
      <Video source={...}
        ref => (this.player = ref) />
    );
    
     
      
     
      
       1
       2
       3
       4

*seek(seconds)*  
seek(这里翻译成定位)到由秒表示的指定位置。 seconds是一个浮点值。  
注意：seek()只能在onLoad事件触发后调用。  
例子：

this.player.seek(200); // 将开始播放时间定为3min20s处
    
     
      
     
      
       1

适用平台：IOS、Android

--------------------

*seek(seconds, tolerance) - 精确的seek*  
默认情况下，iOS在目标位置的100毫秒内寻找。 如果您需要更高的准确度，可以使用搜索公差方法：

seek(seconds, tolerance) 
    
     
      
     
      
       1

tolerance是允许的秒位置的最大距离（以毫秒为单位）。 使用更精确的公差可能导致寻求更长时间。 如果要精确搜索，请将容差设置为0。  
例子：

this.player.seek(120, 50); // 定位到2分钟精度 +/- 50毫秒处
    
     
      
     
      
       1

适用平台：IOS

--------------------

#### 三、更新 ####

Veriosn 3.0

###### 所有平台现在都可以自动播放 ######

以前，在Android ExoPlayer上，如果未设置暂停的道具，则媒体不会自动开始播放。唯一可行的方法是设置paused = \{false\}。如果未设置暂停，则已更改为自动播放，以便跨平台的行为保持一致。

###### 从后台返回时，所有平台现在都保持暂停状态 ######

以前，在Android MediaPlayer上，如果您在应用程序进入后台并设置暂停的道具时设置了AppState事件，那么当您返回应用程序时视频将暂停，它将被忽略。

请注意，Windows没有应用程序进入后台的概念，因此这不适用于此。

###### 默认情况下使用Android SDK 27 ######

版本3.0将Android构建工具和SDK更新为版本27. React Native正在切换到SDK 27，以准备Google要求新的Android应用程序在2018年8月之前使用SDK 26。

您将需要安装版本27 SDK和版本27.0.3 buildtools或修改build.gradle文件以配置react-native-video以使用与应用程序其余部分相同的构建设置，如下所述。

###### 使用应用build设置 ######

您需要在顶级build.gradle文件（而不是app / build.gradle）中创建project.ext部分。使用app / build.gradle文件中的值填写下面示例中的值。

//顶级build文件，您可以在其中添加所有子项目/模块共有的配置选项。
    
    buildscript {
        ... //各种其他设置都在这里
    }
    
    allprojects {
        ... //各种其他设置都在这里
    
        project.ext {
            compileSdkVersion = 23
            buildToolsVersion =“23.0.1”
    
            minSdkVersion = 16
            targetSdkVersion = 22
        }
    }
     
      
     
      
       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16
       17

如果遇到Could not find com.android.support:support-annotations:27.0.0.。重新安装Android支持存储库。

###### 这里提供一个出现上述 “Could not find com.android.support:support-annotations:27.0.0.”错误时的解决方法。 ######

这是从gituhb的issue上找到的：  
只需在项目的android / build.gradle中指定Google的maven存储库：

allprojects { repositories { maven { url 'https://maven.google.com' }
        }
    }
     
      
     
      
       1
       2
       3
       4
       5

这是因为Android原生库依赖于最新版本的Android支持注释库，该库历史上是通过SDK管理器安装的，但现在只能从[https://maven.google.com][https_maven.google.com]获取。

[allowsExternalPlayback]: https://github.com/react-native-community/react-native-video#allowsexternalplayback
[audioOnly]: https://github.com/react-native-community/react-native-video#audioonly
[ignoreSilentSwitch]: https://github.com/react-native-community/react-native-video#ignoresilentswitch
[muted]: https://github.com/react-native-community/react-native-video#muted
[paused]: https://github.com/react-native-community/react-native-video#paused
[playInBackground]: https://github.com/react-native-community/react-native-video#playinbackground
[playWhenInactive]: https://github.com/react-native-community/react-native-video#playwheninactive
[poster]: https://github.com/react-native-community/react-native-video#poster
[posterResizeMode]: https://github.com/react-native-community/react-native-video#posterresizemode
[progressUpdateInterval]: https://github.com/react-native-community/react-native-video#progressupdateinterval
[rate]: https://github.com/react-native-community/react-native-video#rate
[repeat]: https://github.com/react-native-community/react-native-video#repeat
[resizeMode]: https://github.com/react-native-community/react-native-video#resizemode
[selectedTextTrack]: https://github.com/react-native-community/react-native-video#selectedtexttrack
[stereoPan]: https://github.com/react-native-community/react-native-video#stereopan
[textTracks]: https://github.com/react-native-community/react-native-video#texttracks
[useTextureView]: https://github.com/react-native-community/react-native-video#usetextureview
[volume]: https://github.com/react-native-community/react-native-video#volume
[onLoad]: https://github.com/react-native-community/react-native-video#onload
[onLoadStart]: https://github.com/react-native-community/react-native-video#onloadstart
[onProgress]: https://github.com/react-native-community/react-native-video#onprogress
[onTimedMetadata]: https://github.com/react-native-community/react-native-video#ontimedmetadata
[seek]: https://github.com/react-native-community/react-native-video#seek
[Enable Background Audio]: https://developer.apple.com/library/archive/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionBasics/AudioSessionBasics.html#//apple_ref/doc/uid/TP40007875-CH3-SW3
[https_baconmockup.com_300_200]: https://baconmockup.com/300/200/
[https_maven.google.com]: https://maven.google.com