ReactPlayer

一个React组件，用于播放各种URL，包括文件路径、YouTube、Facebook、Twitch、SoundCloud、Streamable、Vimeo、Wistia、Mixcloud、DailyMotion和Kaltura。不使用React？没问题。

使用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}。

属性

回调属性

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

Config属性

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

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

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

方法

静态方法

实例方法

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

高级用法

轻量级播放器

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支持者！

Jackson Doherty

Joseph Fung