react-player

<h1 align='center'> ReactPlayer </h1> <p align='center'> <a href='https://www.npmjs.com/package/react-player'><img src='https://yellow-cdn.veclightyear.com/0a4dffa0/f4e0e7b8-1ed9-49a5-810e-5f092faa5f44.svg' alt='最新npm版本'></a> <a href='https://codecov.io/gh/CookPete/react-player'><img src='https://yellow-cdn.veclightyear.com/0a4dffa0/73dd2c76-2eb3-4862-b990-4e73dfb1b820.svg' alt='测试覆盖率'></a> <a href='https://www.patreon.com/cookpete'><img src='https://yellow-cdn.veclightyear.com/0a4dffa0/c2fbca79-c271-4420-b0b4-f03e03d4363a.svg' alt='在Patreon上成为赞助商'></a> </p> <p align='center'> 一个React组件，用于播放各种URL，包括文件路径、YouTube、Facebook、Twitch、SoundCloud、Streamable、Vimeo、Wistia、Mixcloud、DailyMotion和Kaltura。不使用React？<a href='#standalone-player'>没问题。</a> </p>

---

使用Next.js并需要处理视频上传/处理？请查看 next-video。

✨ ReactPlayer的未来

ReactPlayer的维护将由 Mux 接管。Mux团队参与过许多备受尊敬的项目，并致力于改进开发者的视频工具。

ReactPlayer将保持开源，但修复和发布的频率会随时间增加。感谢社区中每个人一直以来的支持。

使用方法

npm install react-player # 或 yarn add react-player

import React from 'react'
import ReactPlayer from 'react-player'

// 渲染YouTube视频播放器
<ReactPlayer url='https://www.youtube.com/watch?v=LXb3EKWsInQ' />

默认情况下，ReactPlayer支持多种类型的url。如果你只使用一种类型，可以使用react-player/youtube这样的导入来减少你的包大小。查看配置键了解所有播放器键。

import React from 'react'
import ReactPlayer from 'react-player/youtube'

// 只加载YouTube播放器
<ReactPlayer url='https://www.youtube.com/watch?v=LXb3EKWsInQ' />

如果你的构建系统支持import()语句，使用react-player/lazy来懒加载适合你传入的url的播放器。这会在你的输出中添加几个reactPlayer分块，但减少了主包的大小。

import React from 'react'
import ReactPlayer from 'react-player/lazy'

// 懒加载YouTube播放器
<ReactPlayer url='https://www.youtube.com/watch?v=ysz5S6PUM-U' />

演示页面：https://cookpete.github.io/react-player

该组件解析URL并加载适当的标记和外部SDK，以播放来自各种来源的媒体。可以传入属性来控制播放和响应缓冲或媒体结束等事件。查看演示源代码获取完整示例。

对于不直接使用npm模块的平台，安装后在dist目录中有一个压缩版的ReactPlayer。要自己生成这个文件，请检出仓库并运行npm run build:dist。

自动播放

从Chrome 66开始，视频必须设置为muted才能自动播放。一些播放器，如Facebook，在用户与视频交互之前无法取消静音，因此你可能需要启用controls以允许用户自己取消视频静音。请设置muted={true}。

属性

属性	描述	默认值
url	要播放的视频或歌曲的URL<br/>  ◦  可以是数组或MediaStream对象
playing	设置为true或false来暂停或播放媒体	false
loop	设置为true或false来循环播放媒体	false
controls	设置为true或false来显示原生播放器控件<br/>  ◦  对于Vimeo视频，隐藏控件必须由视频所有者启用	false
light	设置为true只显示视频缩略图，点击时加载完整播放器<br />  ◦  传入图片URL可覆盖预览图	false
volume	设置播放器音量，介于0和1之间<br/>  ◦  null在所有播放器上使用默认音量#357	null
muted	使播放器静音<br/>  ◦  仅当设置了volume时有效	false
playbackRate	设置播放器的播放速率<br />  ◦  仅YouTube、Wistia和文件路径支持	1
width	设置播放器宽度	640px
height	设置播放器高度	360px
style	为根元素添加内联样式	{}
progressInterval	onProgress回调之间的时间间隔，以毫秒为单位	1000
playsinline	在支持的地方应用playsinline属性	false
pip	设置为true或false来启用或禁用画中画模式<br/>  ◦  仅在播放文件URL时在特定浏览器中可用	false
stopOnUnmount	如果使用pip，可能需要使用stopOnUnmount={false}以便在ReactPlayer卸载后继续在画中画模式下播放	true
fallback	如果使用延迟加载，用作回退的元素或组件	null
wrapper	用作容器元素的元素或组件	div
playIcon	在light模式下用作播放图标的元素或组件
previewTabIndex	设置在light模式下使用的tab索引	0
config	覆盖各种播放器的选项，参见config prop

回调属性

回调属性接受一个在各种播放器事件上触发的函数：

属性	描述
onReady	当媒体加载完毕并准备播放时调用。如果playing设置为true，媒体将立即播放
onStart	当媒体开始播放时调用
onPlay	当媒体在暂停或缓冲后开始或恢复播放时调用
onProgress	包含played和loaded进度（以分数表示），以及playedSeconds和loadedSeconds（以秒表示）的回调<br />  ◦  例如{ played: 0.12, playedSeconds: 11.3, loaded: 0.34, loadedSeconds: 16.7 }
onDuration	包含媒体时长（以秒为单位）的回调
onPause	当媒体暂停时调用
onBuffer	当媒体开始缓冲时调用
onBufferEnd	当媒体完成缓冲时调用<br />  ◦  适用于文件、YouTube和Facebook
onSeek	当媒体进行跳转时调用，带有seconds参数
onPlaybackRateChange	当播放器的播放速率改变时调用<br />  ◦  仅YouTube、Vimeo（如果启用）、Wistia和文件路径支持
onPlaybackQualityChange	当播放器的播放质量改变时调用<br />  ◦  仅YouTube支持（如果启用）
onEnded	当媒体播放结束时调用<br />  ◦  当loop设置为true时不触发
onError	当尝试播放媒体时发生错误时调用
onClickPreview	当用户点击light模式预览时调用
onEnablePIP	当启用画中画模式时调用
onDisablePIP	当禁用画中画模式时调用

Config属性

有一个单独的config属性用于覆盖每种类型播放器的设置：

<ReactPlayer
  url={url}
  config={{
    youtube: {
      playerVars: { showinfo: 1 }
    },
    facebook: {
      appId: '12345'
    }
  }}
/>

每个播放器的设置位于不同的键下：

键	选项
youtube	playerVars: 覆盖默认播放器参数<br />embedOptions: 覆盖默认嵌入选项<br />onUnstarted: 当状态变为unstarted时调用（通常是视频无法自动播放时）
facebook	appId: 你自己的Facebook应用ID<br />version: Facebook SDK版本<br />playerId: 覆盖播放器ID以实现一致的服务器端渲染（与react-uid一起使用）<br />attributes: 传递给fb-video元素的额外数据属性
soundcloud	options: 覆盖默认播放器选项
vimeo	playerOptions: 覆盖默认参数<br />title: 设置播放器iframe的title属性
mux	attributes: 应用元素属性<br />version: Mux播放器版本
wistia	options: 覆盖默认播放器选项<br />playerId: 覆盖播放器ID以实现一致的服务器端渲染（与react-uid一起使用）
mixcloud	options: 覆盖默认播放器选项
dailymotion	params: 覆盖默认播放器变量
twitch	options: 覆盖默认播放器选项<br />playerId: 覆盖播放器ID以实现一致的服务器端渲染（与react-uid一起使用）
file	attributes: 应用元素属性<br />forceVideo: 始终渲染<video>元素<br />forceAudio: 始终渲染<audio>元素<br />forceHLS: 对HLS流使用hls.js<br />forceSafariHLS: 对HLS流使用hls.js，即使在Safari上<br />forceDisableHLS: 禁用对HLS流使用hls.js<br />forceDASH: 始终对DASH流使用dash.js<br />forceFLV: 始终使用flv.js<br />hlsOptions: 覆盖默认的hls.js选项<br />hlsVersion: 覆盖从jsdelivr加载的hls.js版本，默认：0.13.1<br />dashVersion: 覆盖从cdnjs加载的dash.js版本，默认：2.9.2<br />flvVersion: 覆盖从jsdelivr加载的flv.js版本，默认：1.5.0

方法

静态方法

方法	描述
ReactPlayer.canPlay(url)	判断是否可以播放一个URL。这不能检测由于隐私设置、流媒体权限等原因而无法播放的媒体。在这种情况下，尝试播放后会调用onError属性。任何不匹配任何模式的URL都会回退到原生HTML5媒体播放器。
ReactPlayer.canEnablePiP(url)	判断一个URL是否可以在画中画模式中播放
ReactPlayer.addCustomPlayer(CustomPlayer)	添加自定义播放器。参见添加自定义播放器
ReactPlayer.removeCustomPlayers()	移除使用addCustomPlayer()添加的所有播放器

实例方法

使用ref来调用播放器的实例方法。参见演示应用中的示例。

方法	描述
seekTo(amount, type)	跳转到指定的秒数，如果amount介于0和1之间则为比例<br />  ◦  type参数允许你指定'seconds'或'fraction'来覆盖默认行为
getCurrentTime()	返回已播放的秒数<br />  ◦  如果不可用则返回null
getSecondsLoaded()	返回已加载的秒数<br />  ◦  如果不可用或不支持则返回null
getDuration()	返回当前播放媒体的时长（以秒为单位）<br />  ◦  如果时长不可用则返回null
getInternalPlayer()	返回当前正在播放的内部播放器<br />  ◦  例如YouTube播放器实例，或播放视频文件时的<video>元素<br />  ◦  使用getInternalPlayer('hls')获取hls.js播放器<br />  ◦  使用getInternalPlayer('dash')获取dash.js播放器<br />  ◦  如果内部播放器不可用则返回null
showPreview()	使用light模式时，返回到预览覆盖层

高级用法

轻量级播放器

light属性将渲染一个带有简单播放图标的视频缩略图，只有在用户与图像交互后才会加载完整的播放器。使用Noembed来获取视频URL的缩略图。注意，不支持自动获取Facebook、Wistia、Mixcloud和文件URL的缩略图，且不保证持续支持其他URL。

如果你想传入自己的缩略图使用，将light设置为图片URL而不是true。

你也可以通过light属性传递一个组件：

<ReactPlayer light={<img src='https://example.com/thumbnail.png' alt='缩略图' />} />

预览图片和播放图标的样式可以通过覆盖CSS类 react-player__preview、react-player__shadow 和 react-player__play-icon 来修改。

响应式播放器

将 width 和 height 设置为 100%，并将播放器包裹在一个固定宽高比的盒子中，即可得到一个响应式播放器:

class ResponsivePlayer extends Component {
  render () {
    return (
      <div className='player-wrapper'>
        <ReactPlayer
          className='react-player'
          url='https://www.youtube.com/watch?v=ysz5S6PUM-U'
          width='100%'
          height='100%'
        />
      </div>
    )
  }
}

.player-wrapper {
  position: relative;
  padding-top: 56.25%; /* 播放器比例: 100 / (1280 / 720) */
}

.react-player {
  position: absolute;
  top: 0;
  left: 0;
}

查看 jsFiddle 示例

SDK 覆盖

你可以使用任何播放器SDK的自定义版本，只要在播放器挂载前正确设置 window 全局变量即可。例如，要使用 hls.js 的本地版本，可以在你的应用中添加 <script src='/path/hls.js'></script>。如果在 ReactPlayer 挂载时 window.Hls 可用，它将使用该版本，而不是从 cdnjs 加载 hls.js。更多信息请参见 #605。

独立播放器

如果你没有使用 React，你仍然可以使用独立库来渲染播放器:

<script src='https://cdn.jsdelivr.net/npm/react-player/dist/ReactPlayer.standalone.js'></script>
<script>
  const container = document.getElementById('container')
  const url = 'https://www.youtube.com/watch?v=d46Azg3Pm4c'

  renderReactPlayer(container, { url, playing: true })

  function pausePlayer () {
    renderReactPlayer(container, { url, playing: false })
  }
</script>

查看 jsFiddle 示例

添加自定义播放器

如果你有自己的播放器，并且与 ReactPlayer 的内部架构兼容，你可以使用 addCustomPlayer 添加它:

import YourOwnPlayer from './somewhere';
ReactPlayer.addCustomPlayer(YourOwnPlayer);

使用 removeCustomPlayers 清除所有自定义播放器:

ReactPlayer.removeCustomPlayers();

你有责任确保自定义播放器能跟上 ReactPlayer 后续版本的任何内部变化。

移动设备注意事项

由于各种限制，无法保证 ReactPlayer 在移动设备上正常运行。例如，YouTube 播放器文档解释说某些移动浏览器在播放前需要用户交互:

在某些移动浏览器(如 Chrome 和 Safari)中，HTML5 <video> 元素只允许通过用户交互(如点击播放器)来启动播放。

多个源和音轨

将 YouTube URL 数组传递给 url 属性将加载它们作为无标题播放列表。

<ReactPlayer
  url={[
    'https://www.youtube.com/watch?v=oUFJJNQGwhk',
    'https://www.youtube.com/watch?v=jNgP6d9HraI'
  ]}
/>

播放文件路径时，可以将源数组传递给 url 属性以渲染多个 <source> 标签。

<ReactPlayer playing url={['foo.webm', 'foo.ogg']} />

你也可以通过使用带有 src 和 type 属性的对象来为每个源指定 type。

<ReactPlayer
  playing
  url={[
    {src: 'foo.webm', type: 'video/webm'},
    {src: 'foo.ogg', type: 'video/ogg'}
  ]}
/>

可以使用 config.file 添加字幕的 <track> 元素:

<ReactPlayer
  playing
  url='foo.webm'
  config={{ file: {
    tracks: [
      {kind: 'subtitles', src: 'subs/subtitles.en.vtt', srcLang: 'en', default: true},
      {kind: 'subtitles', src: 'subs/subtitles.ja.vtt', srcLang: 'ja'},
      {kind: 'subtitles', src: 'subs/subtitles.de.vtt', srcLang: 'de'}
    ]
  }}}
/>

迁移到 v2.0

ReactPlayer v2.0 更改了单个播放器的导入方式，并添加了懒加载播放器。同时移除了对 preload 的支持，以及一些其他变更。有关信息请参见 MIGRATING.md。

支持的媒体

• YouTube 视频使用 YouTube iFrame Player API
• Facebook 视频使用 Facebook Embedded Video Player API
• SoundCloud 音轨使用 SoundCloud Widget API
• Streamable 视频使用 Player.js
• Vimeo 视频使用 Vimeo Player API
• Mux 视频使用 <mux-player> 元素
• Wistia 视频使用 Wistia Player API
• Twitch 视频使用 Twitch Interactive Frames API
• DailyMotion 视频使用 DailyMotion Player API
• Vidyard 视频使用 Vidyard Player API
• Kaltura 的 react-player 实现使用 embed.ly 的 Player.js API，但也可以使用 Kaltura 特定的 API，参见 Kaltura Player API
• 支持的文件类型使用 <video> 或 <audio> 元素播放
  • HLS 流使用 hls.js 播放
  • DASH 流使用 dash.js 播放

贡献

在创建拉取请求之前，请查看贡献指南。

致谢

• 感谢所有贡献者。
• 特别感谢我的Patreon支持者！

<table> <tr> <td align='center'> <a href='https://the100.tv'><img src='https://the100.tv/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fthe100-tv-alone-2k.2e7c7877.png&w=384&q=75' width='120' /><br />Jackson Doherty</a> </td> <td align='center'> <a href='https://github.com/jaxomlotus'><img src='https://avatars.githubusercontent.com/u/485706?s=120&v=4' /><br />Joseph Fung</a> </td> </tr> </table>