react-native-video中文文档

简介

一个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

或者用yarn：

yarn add react-native-video

IOS环境下：

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

react-native link 

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

AppDelegate.m

#import <AVFoundation/AVFoundation.h>  // import

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  ...
  [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryAmbient error:nil];  // allow
  ...
}

Android环境下：

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

react-native link 

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

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

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

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

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

android/app/build.gradle

dependencies {
   ...
   compile project(':react-native-video')
}

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

import com.brentvatne.react.ReactVideoPackage;

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

@Override
protected List<ReactPackage> getPackages() {
    return Arrays.asList(
            new MainReactPackage(),
            new ReactVideoPackage()
    );
}

二、使用

//在渲染函数中，假设你的项目中有一个名为“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,
  },
});

可配置属性

• 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/”。
适用平台：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
}}

例子：

selectedTextTrack={{
  type: "title",
  value: "English Subtitles"
}}

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

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

---

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

---

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

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

例子：

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"
  }
]}

这不支持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（有效负载）：

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

 {
  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' }
  ]
}

适用平台：IOS、Android

---

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

Property	Description
isNetwork	boolean
type	string
uri	string

例子：

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

适用平台：IOS、Android

---

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

Property	Description
currentTime	number
playableDuration	number
seekableDuration	number

例子：

{
  currentTime: 5.2,
  playableDuration: 34.6,
  seekableDuration: 888
}

---

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

Property	Type	Description
metadata	array	Array of metadata objects

例子：

{
  metadata: [
    { value: 'Streaming Encoder', identifier: 'TRSN' },
    { value: 'Internet Stream', identifier: 'TRSO' },
    { value: 'Any Time You Like', identifier: 'TIT2' }
  ]
}

适用平台：IOS、Android ExoPlayer

---

3、方法

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

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

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

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

适用平台：IOS、Android

---

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

seek(seconds, tolerance) 

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

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

适用平台：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
    }
}

如果遇到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' }
    }
}

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