项目文章

搜索 TinyTools

Plyr是一款简单、轻量且可定制的HTML5播放器

29.4k 文档演示 Github仓库 Gitee仓库

Plyr 是一款简单、轻量、可访问且可定制的 HTML5、YouTube 和 Vimeo 媒体播放器，支持现代浏览器。

功能

📼 HTML 视频和音频，YouTube 和 Vimeo - 支持主流格式
💪 无障碍访问 - 全面支持 VTT 字幕和屏幕阅读器
🔧 可自定义 - 使用您想要的标记，让播放器呈现您想要的外观
😎 简洁的 HTML - 使用合适的元素。例如，<input type="range"> 表示音量，<progress> 表示进度，以及 <button> 表示按钮。无需
<span> 或 <a href="#"> 按钮 hack
📱 自适应 - 适用于任何屏幕尺寸
💵 广告变现 - 通过您的视频赚钱
📹 流媒体播放 - 支持 hls.js、Shaka 和 dash.js 流媒体播放
🎛 API - 通过标准化 API 切换播放、音量、搜索等功能
🎤 事件 - 无需费心处理 Vimeo 和 YouTube API，所有事件均已标准化，适用于所有格式
🔎 全屏 - 支持原生全屏，并可回退至“全屏”模式
⌨️ 快捷键 - 支持键盘快捷键
🖥 画中画 - 支持画中画模式
📱 Playsinline - 支持 playsinline 属性
🏎 速度控制 - 动态调整速度
📖 多字幕 - 支持多字幕轨道
🌎 i18n 支持 - 支持控件的国际化
👌 预览缩略图 - 支持显示预览缩略图
🤟 无需框架 - 使用原生 ES6 JavaScript 编写，无需 jQuery
💁‍♀️ Sass - 可纳入您的构建流程

演示

您可以使用我们的精简模板在 Codepen 中试用 Plyr：HTML5 视频、HTML5 音频、YouTube、Vimeo。对于流媒体，我们还提供了与以下媒体类型的集成示例：Dash.js、Hls.js 和 Shaka Player

快速设置

HTML

Plyr 扩展了标准的 HTML5 媒体元素标记，因此您只需要这些类型即可。

HTML5 视频

html 复制代码

<video id="player" playsinline controls data-poster="/path/to/poster.jpg">
  <source src="/path/to/video.mp4" type="video/mp4" />
  <source src="/path/to/video.webm" type="video/webm" />

  <!-- Captions are optional -->
  <track kind="captions" label="English captions" src="/path/to/captions.vtt" srclang="en" default />
</video>

注意：海报图片应使用 data-poster 指定。这是为了防止它被下载两次。如果您确定图片会被缓存，仍然可以使用 poster 属性来实现真正的渐进式增强。

HTML5 Audio

html 复制代码

<audio id="player" controls>
  <source src="/path/to/audio.mp3" type="audio/mp3" />
  <source src="/path/to/audio.ogg" type="audio/ogg" />
</audio>

对于 YouTube 和 Vimeo 播放器，Plyr 使用渐进式增强功能来增强默认的 <iframe> 嵌入。以下是一些示例。plyr__video-embed 类名将使嵌入内容具有响应式功能。您可以将 autoplay、loop、hl（仅限 YouTube）和 playsinline（仅限 YouTube）查询参数添加到 URL，它们将自动设置为配置选项。对于 YouTube，应更新 origin 以反映您托管嵌入内容的域名，或者您可以选择忽略它。

YouTube

我们建议对嵌入式播放器使用渐进式增强。您可以选择使用 <iframe> 作为源元素（Plyr 将逐步增强）或使用具有两个基本数据属性的 bog 标准 <div> - data-plyr-provider 和 data-plyr-embed-id。

html 复制代码

<div class="plyr__video-embed" id="player">
  <iframe
    src="https://www.youtube.com/embed/bTqVqk7FSmY?origin=https://plyr.io&amp;iv_load_policy=3&amp;modestbranding=1&amp;playsinline=1&amp;showinfo=0&amp;rel=0&amp;enablejsapi=1"
    allowfullscreen
    allowtransparency
    allow="autoplay"
  ></iframe>
</div>

注意：plyr__video-embed 类名将使播放器成为响应式 16:9（最常见的）iframe 嵌入。当 plyr 本身启动时，将使用您自定义的 ratio 配置选项。

或者使用 <div> 非渐进增强方法：

html 复制代码

<div id="player" data-plyr-provider="youtube" data-plyr-embed-id="bTqVqk7FSmY"></div>

注意：data-plyr-embed-id 可以是视频 ID 或媒体 URL。

Vimeo

与上面的 YouTube 类似。

html 复制代码

<div class="plyr__video-embed" id="player">
  <iframe
    src="https://player.vimeo.com/video/76979871?loop=false&amp;byline=false&amp;portrait=false&amp;title=false&amp;speed=true&amp;transparent=0&amp;gesture=media"
    allowfullscreen
    allowtransparency
    allow="autoplay"
  ></iframe>
</div>

或者使用 <div> 的非渐进增强方法：

html 复制代码

<div id="player" data-plyr-provider="vimeo" data-plyr-embed-id="76979871"></div>

JavaScript

您可以将 Plyr 作为 ES6 模块使用，如下所示：

js 复制代码

import Plyr from 'plyr';

const player = new Plyr('#player');

或者，您可以在结束 </body> 标签之前引入 plyr.js 脚本，然后在 JS 中创建一个新的 Plyr 实例，如下所示。

html 复制代码

<script src="path/to/plyr.js"></script>
<script>
const player = new Plyr('#player');
</script>

有关高级设置的更多信息，请参阅初始化。

您可以使用我们的 CDN（由 Cloudflare 提供）来处理 JavaScript。有两个版本：一个包含 polyfill，一个不包含 polyfill。我建议将 polyfill 作为应用程序的一部分单独管理，但为了更方便，您可以使用 polyfill 构建。

html 复制代码

<script src="https://cdn.plyr.io/3.8.3/plyr.js"></script>

...或者...

html 复制代码

<script src="https://cdn.plyr.io/3.8.3/plyr.polyfilled.js"></script>

CSS

将 plyr.css 样式表添加到您的 <head> 中。

html 复制代码

<link rel="stylesheet" href="path/to/plyr.css" />

如果您想使用我们的 CDN（由 Cloudflare 提供）作为默认 CSS，您可以使用以下命令：

html 复制代码

<link rel="stylesheet" href="https://cdn.plyr.io/3.8.3/plyr.css" />

SVG 精灵图

SVG 精灵图会自动从我们的 CDN（由 Cloudflare 提供）加载。如需更改，请参阅下方的选项。
作为参考，CDN 托管的 SVG 精灵图可以在 https://cdn.plyr.io/3.8.3/plyr.svg 找到。

自托管

如果您不想创建构建系统将 Plyr 包含为 npm 模块，您可以使用预构建的文件。您有以下几种选择：

从上面的 CDN 链接下载文件，它们已经最小化。
从 unpkg 或类似服务下载文件。
使用 npm i && npm run build 自行构建项目，它会安装依赖项并将构建版本导出到 dist。

高级

自定义 CSS

如果您想更改用于播放器渲染的任何设计标记，可以使用 CSS 自定义属性来实现。

以下是属性列表及其用途：

名称	描述	默认 / 后备
`--plyr-color-main`	主 UI 颜色。	`#00b3ff`
`--plyr-video-background`	使用 Alpha 通道视频和海报图片时，视频和海报包装器的背景颜色。	`rgba(0, 0, 0, 1)`
`--plyr-focus-visible-color`	当元素为 `:focus-visible`（键盘聚焦）时，用于焦点样式的颜色。	`--plyr-color-main`
`--plyr-badge-background`	菜单中徽章的背景颜色。	`#4a5464`
`--plyr-badge-text-color`	徽章的文本颜色。	`#ffffff`
`--plyr-badge-border-radius`	徽章使用的边框半径。	`2px`
`--plyr-captions-background`	字幕背景颜色。	`rgba(0, 0, 0, 0.8)`
`--plyr-captions-text-color`	字幕文本使用的颜色。	`#ffffff`
`--plyr-control-icon-size`	控件中使用的图标的大小。	`18px`
`--plyr-control-spacing`	控件之间的间距（有时使用倍数 - 例如 `10px / 2 = 5px`）。	`10px`
`--plyr-control-padding`	控件内部的填充。	`--plyr-control-spacing * 0.7` (`7px`)
`--plyr-control-radius`	控件上使用的边框半径。	`3px`
`--plyr-control-toggle-checked-background`	已选中菜单项使用的背景颜色。	`--plyr-color-main`
`--plyr-video-controls-background`	视频控件的背景。	`linear-gradient(rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.75))`
`--plyr-video-control-color`	视频控件的文本/图标颜色。	`#ffffff`
`--plyr-video-control-color-hover`	视频控件为 `:hover`、`:focus` 和 `:focus-visible`（等效）时使用的文本/图标颜色。	`#ffffff`
`--plyr-video-control-background-hover`	视频控件为 `:hover`、`:focus` 和 `:focus-visible`（等效）时使用的背景颜色。	`--plyr-color-main`
`--plyr-audio-controls-background`	音频控件的背景。	`#ffffff`
`--plyr-audio-control-color`	音频控件的文本/图标颜色。	`#4a5464`
`--plyr-audio-control-color-hover`	音频控件为 `:hover`、`:focus` 和 `:focus-visible`（等效）时使用的文本/图标颜色。	`#ffffff`
`--plyr-audio-control-background-hover`	视频控件为 `:hover`、`:focus` 和 `:focus-visible`（等效）时使用的背景颜色。	`--plyr-color-main`
`--plyr-menu-background`	菜单的背景颜色。	`rgba(255, 255, 255, 0.9)`
`--plyr-menu-color`	菜单项的文本/图标颜色。	`#4a5464`
`--plyr-menu-shadow`	菜单上使用的阴影。	`0 1px 2px rgba(0, 0, 0, 0.15)`
`--plyr-menu-radius`	菜单上的边框半径。	`4px`
`--plyr-menu-arrow-size`	菜单底部箭头的大小。	`6px`
`--plyr-menu-item-arrow-color`	菜单中箭头的颜色。	`#728197`
`--plyr-menu-item-arrow-size`	菜单中箭头的大小。	`4px`
`--plyr-menu-border-color`	子菜单页面顶部后退按钮底部的边框颜色。	`#dcdfe5`
`--plyr-menu-border-shadow-color`	子菜单页面顶部后退按钮边框下方的阴影。	`#ffffff`
`--plyr-progress-loading-size`	滑块加载状态下条纹的大小。	`25px`
`--plyr-progress-loading-background`	滑块加载状态下的背景颜色。	`rgba(35, 40, 47, 0.6)`
`--plyr-video-progress-buffered-background`	视频进度条中缓冲区指示的填充颜色。	`rgba(255, 255, 255, 0.25)`
`--plyr-audio-progress-buffered-background`	音频进度条中缓冲区指示的填充颜色。	`rgba(193, 200, 209, 0.6)`
`--plyr-range-thumb-height`	进度条手柄/缩略图的高度。	`13px`
`--plyr-range-thumb-background`	进度条手柄/缩略图的背景。	`#ffffff`
`--plyr-range-thumb-shadow`	滑块/缩略图的阴影。	`0 1px 1px rgba(215, 26, 18, 0.15), 0 0 0 1px rgba(215, 26, 18, 0.2)`
`--plyr-range-thumb-active-shadow-width`	滑块/缩略图处于 `:active`（按下）状态时的阴影宽度。	`3px`
`--plyr-range-track-height`	滑块/进度条的高度。	`5px`
`--plyr-range-fill-background`	滑块/进度条的填充颜色。	`--plyr-color-main`
`--plyr-video-range-track-background`	滑块/进度条的背景。	`--plyr-video-progress-buffered-background`
`--plyr-video-range-thumb-active-shadow-color`	视频滑块手柄/缩略图处于 `:active`（按下）状态时的阴影颜色。	`rgba(255, 255, 255, 0.5)`
`--plyr-audio-range-track-background`	滑块/进度条的背景。	`--plyr-video-progress-buffered-background`
`--plyr-audio-range-thumb-active-shadow-color`	音频滑块手柄/缩略图处于 `:active`（按下）状态时的阴影颜色。	`rgba(215, 26, 18, 0.1)`
`--plyr-tooltip-background`	工具提示的背景颜色。	`rgba(255, 255, 255, 0.9)`
`--plyr-tooltip-color`	工具提示的文本颜色。	`#4a5464`
`--plyr-tooltip-padding`	工具提示的填充。	`calc(var(--plyr-control-spacing) / 2))`
`--plyr-tooltip-arrow-size`	工具提示下方箭头的大小。	`4px`
`--plyr-tooltip-radius`	工具提示的边框半径。	`3px`
`--plyr-tooltip-shadow`	工具提示的阴影。	`0 1px 2px rgba(0, 0, 0, 0.15)`
`--plyr-font-family`	播放器中使用的字体系列。
`--plyr-font-size-base`	基本字体大小。主要用于字幕。	`15px`
`--plyr-font-size-small`	较小的字体大小。主要用于字幕。	`13px`
`--plyr-font-size-large`	较大的字体大小。主要用于字幕。	`18px`
`--plyr-font-size-xlarge`	更大的字体大小。主要用于字幕。	`21px`
`--plyr-font-size-time`	时间的字体大小。	`--plyr-font-size-small`
`--plyr-font-size-menu`	菜单中使用的字体大小。	`--plyr-font-size-small`
`--plyr-font-size-badge`	徽章使用的字体大小。	`9px`
`--plyr-font-weight-regular`	常规字体粗细。	`400`
`--plyr-font-weight-bold`	粗体字体粗细。	`600`
`--plyr-line-height`	播放器中使用的行高。	`1.7`
`--plyr-font-smoothing`	是否在播放器中启用字体抗锯齿功能。	`false`

您可以在 CSS 中为所有播放器设置它们：

css 复制代码

:root {
  --plyr-color-main: #1ac266;
}

...or for a specific class name:

css 复制代码

.player {
  --plyr-color-main: #1ac266;
}

...or in your HTML:

html 复制代码

<video class="player" style="--plyr-color-main: #1ac266;">...</video>

Sass

您可以使用 /src/sass 目录下的 plyr.scss 文件作为构建的一部分，并根据你的设计修改变量。Sass 要求你
使用 autoprefixer（你应该已经使用了！），因为所有声明都使用了 W3C 定义。

HTML 标记使用 BEM 方法，以 plyr 作为块，例如 .plyr__controls。你可以更改选项中的类钩子，以匹配你编写的任何自定义 CSS。
更多信息，请查看 JavaScript 源代码。

SVG

Plyr 控件中使用的图标以 SVG 精灵图的形式加载。该精灵图默认从我们的 CDN 自动加载。如果你已经拥有图标构建系统，
则可以包含源 plyr 图标（源图标请参阅 /src/sprite）。

使用 `iconUrl` 选项

不过，您可以指定自己的 iconUrl 选项，Plyr 会判断 URL 是否为绝对路径，是否由于当前浏览器的限制而需要通过 AJAX/CORS 加载。
或者，如果是相对路径，则直接使用该路径即可。

如果您在网站上使用 <base> 标签，则可能需要使用类似这样的代码：svgfixer.js

更多关于 SVG 精灵的信息，请访问：http://css-tricks.com/svg-sprites-use-better-icon-fonts/，以及 AJAX 技术，
请访问：http://css-tricks.com/ajaxing-svg-sprite/

跨域 (CORS)

您会注意到示例 <video> 元素上的 crossorigin 属性。这是因为 TextTrack 字幕是从其他域名加载的。如果您的
TextTrack 字幕也托管在其他域名上，则需要添加此属性，并确保您的主机已设置正确的标头。有关 CORS 的更多信息，请查看 MDN 文档：
https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS

如果您需要将凭据（例如 Cookie、授权标头或证书）附加到预览缩略图请求，请使用 withCredentials 选项，如下所示：

js 复制代码

const player = new Plyr(video, {
  previewThumbnails: {
    enabled: true,
    src: 'https://cdn.example.com/storyboard.vtt',
    withCredentials: true,
  },
});

字幕

支持 WebVTT 字幕。要添加字幕轨道，请查看上面的 HTML 示例并查找 <track> 元素。请务必
验证您的字幕文件。

JavaScript

初始化

您可以指定构造函数使用的一系列参数：

一个 CSS 字符串选择器
一个 HTMLElement
一个 jQuery 对象

注意：如果传递了 NodeList、Array 或 jQuery 对象，则将使用第一个元素进行设置。要设置多个播放器，请参阅下面的多个播放器。

单个播放器

传递一个与 querySelector 兼容的 CSS 字符串选择器：

js 复制代码

const player = new Plyr('#player');

传递一个 HTMLElement：

js 复制代码

const player = new Plyr(document.getElementById('player'));

js 复制代码

const player = new Plyr(document.querySelector('.js-player'));

HTMLElement 或字符串选择器可以是目标 <video>、<audio> 或 <div> 的封装器，用于嵌入。

多个播放器

这里您有两个选择。您可以使用简单的数组循环来映射构造函数：

js 复制代码

const players = Array.from(document.querySelectorAll('.js-player')).map((p) => new Plyr(p));

...或者使用静态方法，传入 CSS 字符串选择器、NodeList、HTMLElement 的 Array 或 JQuery 对象：

js 复制代码

const players = Plyr.setup('.js-player');

这两个选项都会返回一个数组，数组中的元素按照字符串选择器、源 NodeList 或 Array 在 DOM 中的顺序排列。

选项

构造函数的第二个参数是 options 对象：

js 复制代码

const player = new Plyr('#player', {
title: '示例标题',
});

选项可以像上面一样作为对象传递给构造函数，也可以作为 JSON 数据传入每个目标元素的 data-plyr-config 属性中：

html 复制代码

<video src="/path/to/video.mp4" id="player" controls data-plyr-config='{ "title": "示例标题" }'></video>

请注意，JSON 数据用单引号括起来，对象键用双引号括起来。只有字符串值才需要双引号。

选项	类型	默认值	描述
`enabled`	布尔值	`true`	完全禁用 Plyr。这将允许您执行用户代理检查或类似操作，以编程方式为特定 UA 启用或禁用 Plyr。示例如下。
`debug`	布尔值	`false`	在控制台中显示调试信息
`controls`	数组、函数或元素	`['play-large', 'play', 'progress', 'current-time', 'mute', 'volume', 'captions', 'settings', 'pip', 'airplay', 'fullscreen']`	如果传递的是函数，则假定您的方法将返回控件的元素或 HTML 字符串。三个参数将传递给您的函数：`id`（播放器的唯一 ID）、`seektime`（以秒为单位的寻道时间步长）和 `title`（媒体标题）。有关如何构建 HTML 的更多信息，请参阅 CONTROLS.md。
`settings`	数组	`['captions', 'quality', 'speed', 'loop']`	如果使用默认控件，您可以指定要在菜单中显示的设置
`i18n`	对象	请参阅 defaults.js	用于 UI 中文本的国际化 (i18n)。
`loadSprite`	布尔值	`true`	加载由 `iconUrl` 选项指定的 SVG 精灵（如果是 URL）。如果为 `false`，则假定您自行处理精灵加载。
`iconUrl`	字符串	`https://cdn.plyr.io/3.8.3/plyr.svg`	指定 SVG 精灵的 URL 或路径。更多信息请参阅 SVG 部分。
`iconPrefix`	字符串	`plyr`	指定默认控件中使用的图标的 ID 前缀（例如，“plyr-play”应为“plyr”）。这是为了防止在使用自己的 SVG 精灵但使用默认控件时发生冲突。大多数人可以忽略此选项。
`blankVideo`	字符串	`https://cdn.plyr.io/static/blank.mp4`	指定用于正确取消网络请求的空白视频文件的 URL 或路径。
`autoplay`²	布尔值	`false`	加载时自动播放媒体。如果 `<video>` 或 `<audio>` 元素上存在 `autoplay` 属性，则该属性将自动设置为 true。
`autopause`¹	布尔值	`true`	一次只允许一个播放器播放。
`playsinline`³	布尔值	`true`	允许在 iOS 上进行内联播放。请注意，这对 iPadOS 无效。
`seekTime`	数字	`10`	用户点击快进或快退时定位的时间（以秒为单位）。
`volume`	数字	`1`	一个介于 0 和 1 之间的数字，表示播放器的初始音量。
`muted`	布尔值	`false`	是否以静音方式开始播放。如果 `<video>` 或 `<audio>` 元素上存在 `muted` 属性，则会自动设置为 true。
`clickToPlay`	布尔值	`true`	点击（或轻触）视频容器可切换播放/暂停。
`disableContextMenu`	布尔值	`true`	禁用视频右键菜单，帮助进行非常原始的混淆，以防止内容下载。
`hideControls`	布尔值	`true`	在鼠标或焦点 2 秒无移动后、控件元素模糊（Tab 键移出）、播放开始或进入全屏时自动隐藏视频控件。只要移动鼠标、控件元素获得焦点或播放暂停，控件就会立即重新显示。
`resetOnEnd`	布尔值	false	播放完成后，将播放重置为开始。
`keyboard`	对象	`{ focused: true, global: false }`	仅为获得焦点的播放器或全局启用键盘快捷键
`tooltips`	Object	`{ controls: false, seek: true }`	`controls`：在 `:hover` 和 `:focus` 上将控件标签显示为工具提示（默认情况下，标签仅供屏幕阅读器使用）。`seek`：显示一个定位工具提示，用于在点击时指示媒体将定位到的位置。
`duration`	Number	`null`	指定媒体的自定义时长。
`displayDuration`	Boolean	`true`	在当前时间显示中，在“metadataloaded”事件（启动时）上显示媒体的时长。仅当 `preload` 属性未设置为 `none`（或根本没有设置）并且您选择不显示时长时，此功能才有效（请参阅 `controls` 选项）。
`invertTime`	Boolean	`true`	将当前时间显示为倒计时，而不是增量计数器。
`toggleInvert`	布尔值	`true`	允许用户点击切换上述内容。
`listeners`	Object	`null`	允许在默认处理程序之前将事件监听器绑定到控件。有关可用的监听器，请参阅 `defaults.js`。如果您的处理程序阻止事件的默认设置（`event.preventDefault()`），则默认处理程序将不会触发。
`captions`	Object	`{ active: false, language: 'auto', update: false }`	`active`：切换字幕是否默认处于活动状态。`language`：设置要加载的默认语言（如果可用）。'auto' 使用浏览器语言。`update`：监听曲目更改并更新菜单。某些流媒体库需要此功能，但可能会导致语言选项不可选。
`fullscreen`	Object	`{ enabled: true, fallback: true, iosNative: false, container: null }`	`enabled`：切换是否启用全屏。`fallback`：允许回退到全屏解决方案（`true`/`false`/`'force'`）。`iosNative`：进入全屏模式时是否使用原生 iOS 全屏（无自定义控件）。`container`：播放器元素祖先的选择器，允许上下文内容在全屏模式下保持可见。非祖先元素将被忽略。
`ratio`	字符串	`null`	强制所有视频的宽高比。格式为 `'w:h'` - 例如 `'16:9'` 或 `'4:3'`。如果未指定，则 HTML5 和 Vimeo 默认使用视频的原生分辨率。由于 YouTube 无法通过 SDK 提供尺寸，因此强制使用 16:9 作为合理的默认值。
`storage`	对象	`{ enabled: true, key: 'plyr' }`	`enabled`：允许使用本地存储来存储用户设置。`key`：要使用的键名。
`speed`	对象	`{ selected: 1, options: [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 4] }`	`selected`：默认播放速度。`options`：UI 中显示的速度选项。YouTube 和 Vimeo 将忽略 0.5-2 范围之外的任何选项，因此此范围之外的选项将自动隐藏。
`quality`	对象	`{ default: 576, options: [4320, 2880, 2160, 1440, 1080, 720, 576, 480, 360, 240] }`	`default` 是默认质量级别（如果您的源中存在该级别）。`options` 是要显示的选项。这用于过滤可用的源。
`loop`	Object	`{ active: false }`	`active`：是否循环播放当前视频。如果 `<video>` 或 `<audio>` 元素上存在 `loop` 属性，则会自动设置为 true。这是一个用于支持未来功能的对象。
`ads`	Object	`{ enabled: false, publisherId: '', tagUrl: '' }`	`enabled`：是否启用广告。`publisherId`：您唯一的 vi.ai 发布者 ID。如果您不使用 Vi，`tagUrl` 是自定义 VAST 标签的 URL。
`urls`	Object	查看源代码。	如果您想覆盖任何 API URL，可以在此处进行。您还可以为下载按钮设置自定义下载 URL。
`vimeo`	Object	`{ byline: false, portrait: false, title: false, speed: true, transparent: false }`	请参阅 Vimeo 嵌入选项。部分选项会根据其他配置选项自动设置，例如：`loop`、`autoplay`、`muted`、`gesture`、`playsinline`
`youtube`	Object	`{ noCookie: false, rel: 0, showinfo: 0, iv_load_policy: 3, modestbranding: 1 }`	请参阅 YouTube 嵌入选项。唯一的自定义选项是 `noCookie`，用于使用不使用 Cookie 的 YouTube 替代方案（适用于 GDPR 等）。有些选项会根据其他配置选项自动设置，即：`autoplay`、`hl`、`controls`、`disablekb`、`playsinline`、`cc_load_policy`、`cc_lang_pref`、`widget_referrer`
`previewThumbnails`	Object	`{ enabled: false, src: '', withCredentials: false }`	`enabled`：是否启用预览缩略图（必须由您生成）。`src`：必须为字符串或字符串数组，表示包含图片 URL 的 VTT 文件的 URL。有关预览缩略图的更多信息，请见下文。`withCredentials`：是否将凭据（例如 Cookie 和授权标头）附加到请求。
`mediaMetadata`	Object	`{ title: '', artist: '', album: '', artwork: [] }`	Media Session API 的 MediaMetadata 接口允许网页提供丰富的媒体元数据以显示在平台 UI 中。
`markers`	Object	`{ enabled: false, points: [] }`	`enabled`：是否启用标记。`points` 是一个 `{ time: number; label: string; }` 对象的数组，其中 `time` 表示标记位置（以秒为单位），`label` 是要显示的 HTML 字符串。

仅限 Vimeo
自动播放通常不推荐使用，因为它会降低用户体验。许多浏览器也禁用了此功能。在提出问题之前，请先做好功课。更多信息请访问：

YouTube 不支持通过其 API 以编程方式切换原生全屏播放器。这意味着在 iOS 上你有两个选择，但都不完美：

使用 fallback/faux 全屏选项，覆盖整个视口（这是默认设置）
将 playsinline 设置为 false 和/或 fullscreen.iosNative 设置为 true - 这两个选项都会隐藏 UI 中的全屏切换按钮（由于上述 API 问题），这意味着 iOS 将使用其原生播放器播放视频。

API

Plyr 对象包含方法、setter 和 getter。

对象

访问 Plyr 对象的最简单方法是将调用构造函数的返回值设置为一个变量。例如：

js 复制代码

const player = new Plyr('#player', {
/* options */
});

您也可以通过任何事件访问该对象：

js 复制代码

element.addEventListener('ready', (event) => {
const player = event.detail.plyr;
});

方法

方法使用示例：

js 复制代码

player.play(); // 开始播放
player.fullscreen.enter(); // 进入全屏

方法	参数	说明
`play()`¹	-	开始播放。
`pause()`	-	暂停播放。
`togglePlay(toggle)`¹	Boolean	切换播放，如果不传递参数，则根据当前状态切换。
`stop()`	-	停止播放并重置为开始。
`restart()`	-	重新开始播放。
`rewind(seekTime)`	Number	按指定的搜索时间倒退播放。如果不传递参数，则使用默认搜索时间。
`forward(seekTime)`	Number	按指定的搜索时间快进。如果不传递参数，则使用默认搜索时间。
`increaseVolume(step)`	Number	按指定的步长增加音量。如果未传递任何参数，则使用默认步长。
`decreaseVolume(step)`	Number	按指定步长增加音量。如果未传递任何参数，则使用默认步长。
`toggleCaptions(toggle)`	Boolean	切换字幕显示。如果未传递任何参数，则将根据当前状态切换。
`fullscreen.enter()`	-	进入全屏模式。如果不支持全屏，则使用后备的“全窗口/视口”模式。
`fullscreen.exit()`	-	退出全屏模式。
`fullscreen.toggle()`	-	切换全屏模式。
`airplay()`	-	在支持的设备上触发 AirPlay 对话框。
`setPreviewThumbnails(source: PreviewThumbnailsOptions)`	-	设置当前源的预览缩略图。
`toggleControls(toggle)`	布尔值	切换控件（仅限视频）。采用可选的真值强制打开/关闭。
`on(event, function)`	字符串，函数	为指定事件添加事件监听器。
`once(event, function)`	字符串，函数	为指定事件添加一次事件监听器。
`off(event, function)`	字符串，函数	删除指定事件的事件监听器。
`supports(type)`	字符串	检查是否支持某种 MIME 类型。
`destroy()`	-	销毁实例并垃圾回收所有元素。

对于 HTML5 播放器，play() 将为大多数浏览器（例如 Chrome、Firefox、Opera、Safari 和 Edge）返回一个 Promise（根据本文撰写时的 MDN 记录）。

Getters 和 Setters

Setters 示例：

js 复制代码

player.volume = 0.5; // 将音量设置为 50%
player.currentTime = 10; // 播放至 10 秒

Getters 示例：

js 复制代码

player.volume; // 0.5;
player.currentTime; // 10
player.fullscreen.active; // false;

属性	获取方法	设置方法	描述
`isHTML5`	✓	-	返回一个布尔值，指示当前播放器是否为 HTML5。
`isEmbed`	✓	-	返回一个布尔值，指示当前播放器是否为嵌入式播放器。
`playing`	✓	-	返回一个布尔值，指示当前播放器是否正在播放。
`paused`	✓	-	返回一个布尔值，指示当前播放器是否已暂停。
`stopped`	✓	-	返回一个布尔值，指示当前播放器是否已停止。
`ended`	✓	-	返回一个布尔值，指示当前播放器是否已完成播放。
`buffered`	✓	-	返回一个介于 0 和 1 之间的浮点数，指示缓冲的媒体量
`currentTime`	✓	✓	获取或设置播放器的当前时间。该设置器接受以秒为单位的浮点数。
`seeking`	✓	-	返回一个布尔值，指示当前播放器是否正在定位。
`duration`	✓	-	返回当前媒体的时长。
`volume`	✓	✓	获取或设置播放器的音量。该设置器接受介于 0 和 1 之间的浮点数。
`muted`	✓	✓	获取或设置播放器的静音状态。该设置器接受布尔值。
`hasAudio`	✓	-	返回一个布尔值，指示当前媒体是否有音轨。
`speed`	✓	✓	获取或设置播放器的速度。该设置器接受配置中指定的选项中的值。通常最小值为 0.5。
`quality`¹	✓	✓	获取或设置播放器的质量。该设置器接受配置中指定的选项中的值。
`loop`	✓	✓	获取或设置播放器的当前循环状态。该设置器接受布尔值。
`source`	✓	✓	获取或设置播放器的当前源。该设置器接受一个对象。有关示例，请参阅下面的 source setter。
`poster`	✓	✓	获取或设置播放器的当前海报图像。设置器接受一个字符串；更新后的海报图片的 URL。
`previewThumbnails`	✓	✓	获取或设置播放器的当前预览缩略图源。设置器接受一个字符串
`autoplay`	✓	✓	获取或设置播放器的自动播放状态。设置器接受一个布尔值。
`currentTrack`	✓	✓	通过索引获取或设置字幕轨道。`-1` 表示轨道缺失或字幕未激活
`language`	✓	✓	获取或设置播放器的首选字幕语言。设置器接受一个 ISO 两字母语言代码。对语言的支持取决于您添加的字幕。如果您的字幕没有任何语言数据，或者您有多个使用相同语言的轨道，您可能需要改用 `currentTrack`。
`fullscreen.active`	✓	-	返回一个布尔值，指示当前播放器是否处于全屏模式。
`fullscreen.enabled`	✓	-	返回一个布尔值，指示当前播放器是否启用了全屏。
`pip`¹	✓	✓	获取或设置播放器的画中画状态。设置器接受布尔值。目前仅支持 Safari 10+（在 MacOS Sierra+ 和 iOS 10+ 上）和 Chrome 70+。
`ratio`	✓	✓	获取或设置视频宽高比。该设置方法接受与 `ratio` 选项相同格式的字符串。
`download`	✓	✓	获取或设置下载按钮的 URL。该设置方法接受包含有效绝对 URL 的字符串。

仅限 HTML5

`.source` 设置器

这允许动态更改播放器源和类型。

视频示例：

js 复制代码

player.source = {
  type: 'video',
  title: 'Example title',
  sources: [
    {
      src: '/path/to/movie.mp4',
      type: 'video/mp4',
      size: 720,
    },
    {
      src: '/path/to/movie.webm',
      type: 'video/webm',
      size: 1080,
    },
  ],
  poster: '/path/to/poster.jpg',
  previewThumbnails: {
    src: '/path/to/thumbnails.vtt',
  },
  tracks: [
    {
      kind: 'captions',
      label: 'English',
      srclang: 'en',
      src: '/path/to/captions.en.vtt',
      default: true,
    },
    {
      kind: 'captions',
      label: 'French',
      srclang: 'fr',
      src: '/path/to/captions.fr.vtt',
    },
  ],
};

Audio example:

js 复制代码

player.source = {
  type: 'audio',
  title: 'Example title',
  sources: [
    {
      src: '/path/to/audio.mp3',
      type: 'audio/mp3',
    },
    {
      src: '/path/to/audio.ogg',
      type: 'audio/ogg',
    },
  ],
};

YouTube example:

js 复制代码

player.source = {
  type: 'video',
  sources: [
    {
      src: 'bTqVqk7FSmY',
      provider: 'youtube',
    },
  ],
};

Vimeo example

js 复制代码

player.source = {
  type: 'video',
  sources: [
    {
      src: '76979871',
      provider: 'vimeo',
    },
  ],
};

注意：YouTube 和 Vimeo 的 src 属性可以是视频 ID 或完整 URL。

属性	类型	说明
`type`	字符串	`video` 或 `audio`。注意：YouTube 和 Vimeo 目前不支持作为音频源。
`title`	字符串	可选。新媒体的标题。用于播放按钮和外部容器上的 `aria-label` 属性。YouTube 和 Vimeo 会自动填充。
`sources`	数组	这是一个源数组。对于 HTML5 媒体，此对象的属性直接映射到 HTML 属性，因此可以根据需要向对象添加更多属性。
`poster`¹	字符串	海报图片的 URL（仅限 HTML5 视频）。
`tracks`¹	字符串	轨道对象数组。数组中的每个元素都直接映射到轨道元素，任何键都直接映射到 HTML 属性，因此如上例所示，它将呈现为 `<track kind="captions" label="English" srclang="en" src="https://cdn.selz.com/plyr/1.0/example_captions_en.vtt" default>`，法语版本也是如此。布尔值将转换为 HTML5 无值属性。
`previewThumbnails`¹	对象	与 `previewThumbnails` 构造函数选项中的对象相同。这意味着您可以通过 `src` 键更改缩略图 vtt，或者通过传递 `{ enabled: false }` 为下一个视频禁用缩略图插件。

仅限 HTML5

事件

您可以在设置 Plyr 的目标元素上监听事件（请参阅表格下方的示例）。某些事件仅适用于 HTML5 音频和视频。使用您对实例的
引用，您可以使用 on() API 方法或 addEventListener()。您可以通过 event.detail.plyr 属性访问 API。以下是示例：

js 复制代码

player.on('ready', (event) => {
const instance = event.detail.plyr;
});

标准媒体事件

事件类型	描述
`progress`	定期发送，以通知相关方媒体下载进度。当前已下载的媒体量信息可在媒体元素的 `buffered` 属性中找到。
`playing`	媒体开始播放时发送（首次播放、暂停后播放或播放结束后重新开始播放）。
`play`	媒体暂停后开始播放时发送；即在前一个 `pause` 事件后恢复播放时发送。
`pause`	播放暂停时发送。
`timeupdate`	元素的 `currentTime` 属性指示的时间已更改。
`volumechange`	音量改变时发送（设置音量和更改 `muted` 状态时）。
`seeking`	当搜索操作开始时发送。
`seeked`	当搜索操作完成时发送。
`ratechange`	当播放速度改变时发送。
`ended`	当播放完成时发送。_注意：_如果 `autoplay` 为 true，则不会触发。
`enterfullscreen`	当播放器进入全屏模式（旧版浏览器的全屏或全窗口回退模式）时发送。
`exitfullscreen`	当播放器退出全屏模式时发送。
`captionsenabled`	当字幕启用时发送。
`captionsdisabled`	当字幕禁用时发送。
`languagechange`	当字幕语言更改时发送。
`controlshidden`	当控件隐藏时发送。
`controlsshown`	当控件显示时发送。
`ready`	当实例准备好进行 API 调用时触发。

仅限 HTML5

事件类型	描述
`loadstart`	媒体开始加载时发送。
`loadeddata`	媒体的第一帧已加载完成。
`loadedmetadata`	媒体的元数据已加载完成；所有属性现在都已包含尽可能多的有用信息。
`qualitychange`	播放质量已更改。
`canplay`	当有足够的数据可供媒体播放（至少播放几帧）时发送。这对应于 `HAVE_ENOUGH_DATA` `readyState`。
`canplaythrough`	当就绪状态变为 `CAN_PLAY_THROUGH` 时发送，表示假设下载速率至少保持在当前水平，整个媒体可以不间断地播放。注意：手动设置 `currentTime` 最终会在 Firefox 中触发 `canplaythrough` 事件。其他浏览器可能不会触发此事件。
`stalled`	当用户代理尝试获取媒体数据但数据意外未获取时发送。
`waiting`	当请求的操作（例如播放）因等待其他操作（例如搜索）完成而延迟时发送。
`emptied`	媒体已空；例如，如果媒体已加载（或部分加载），并且调用 `load()` 方法重新加载，则会发送此事件。
`cuechange`	当 `TextTrack` 更改了当前显示的提示时发送。
`error`	发生错误时发送。元素的 `error` 属性包含更多信息。

仅限 YouTube

事件类型	描述
`statechange`	播放器状态已更改。代码可通过 `event.detail.code` 获取。可能的值包括 `-1`：未启动，`0`：已结束，`1`：正在播放，`2`：已暂停，`3`：正在缓冲，`5`：视频已提示。更多信息，请参阅 YouTube 文档。

注意： 这些事件也会使 DOM 冒泡。事件目标将是容器元素。

部分事件细节借鉴自 MDN。

嵌入

YouTube 和 Vimeo 目前已支持，其功能与 HTML5 视频非常相似。所有类型都提供类似的事件和 API 方法。但是，如果您希望
直接访问 API，可以通过播放器对象的 embed 属性来实现，例如 player.embed。然后，您可以使用第三方 API 中的相关方法。更多关于各个 API 的信息，请访问：

注意：并非所有 API 方法都能 100% 正常工作。您的实际效果可能会有所不同。最好尽可能使用 Plyr API。

快捷键

默认情况下，播放器在获得焦点时会绑定以下键盘快捷键。如果您将 global 选项设置为 true，并且文档中只有一个播放器，那么除了需要输入的元素外，任何元素获得焦点时，这些快捷键都会生效。

按键	操作
`0` 到 `9`	分别从 0 到 90% 移动
`space`	切换播放
`K`	切换播放
←	使用 `seekTime` 选项向后移动
→	使用 `seekTime` 选项向前移动
↑	增加音量
↓	降低音量
`M`	切换静音
`F`	切换全屏
`C`	切换字幕
`L`	切换循环

预览缩略图

您可以像演示中一样，将鼠标悬停在滑块上或在主视频区域滑动时显示预览缩略图。此功能适用于所有视频类型，但使用 HTML5 最方便。您需要自行生成精灵图或图像。您可以使用 AWS 转码器之类的工具生成帧，然后将它们组合成精灵图。出于性能方面的考虑，建议使用精灵图——它们的下载速度更快，而且更容易压缩成较小的文件，从而加快加载速度。

您可以在此处和此处查看示例 VTT 文件，了解精灵图的制作方法。坐标以 xywh 哈希值的形式显示在 URL 中，顺序为 X 轴偏移、Y 轴偏移、宽度、高度（例如，240p-00001.jpg#xywh=1708,480,427,240 表示距离左侧 1708px，距离顶部 480px，整体尺寸为 427x240px。如果您想每帧包含图像，也可以这样做，但速度会更慢，导致体验下降。

全屏

Plyr 中的全屏功能在所有当前支持的浏览器中均受支持。

浏览器支持

Plyr 支持大多数_现代_浏览器的最后两个版本。

浏览器	支持
Safari	✓
移动版 Safari	✓¹
Firefox	✓
Chrome	✓
Opera	✓
Edge	✓
IE11	✓³
IE10	✓^2,3

iPhone 上的移动版 Safari 浏览器会强制使用原生播放器播放 <video>，除非设置了 playsinline 属性。音量控制也会被禁用，因为它们是设备级处理的。
使用原生播放器（不支持 <progress> 或 <input type="range">），但支持 API。不支持原生全屏播放，可以使用回退功能（参见 options）。
需要 Polyfill。见下文。

Polyfills

Plyr 使用 ES6，但并非所有浏览器都支持。这意味着某些功能需要 polyfill 才能使用，否则会遇到问题。我们选择不给大约 90% 支持这些功能的用户添加额外的 JS 代码，而是让您根据自己的需求自行编写 polyfill。

检查支持情况

您可以使用静态方法检查是否支持。例如：

js 复制代码

const supported = Plyr.supported('video', 'html5');

参数如下：

媒体类型 ('audio' | 'video')
提供程序 ('html5' | 'youtube' | 'vimeo')

通过编程禁用支持

enabled 选项可用于禁用某些用户代理。例如，如果您不想在智能手机上使用 Plyr，可以使用：

js 复制代码

{
enabled: !/Android|webOS|iPhone|iPad|iPod|BlackBerry/i.test(navigator.userAgent);
}

如果用户代理已禁用，但原生支持 <video> 和 <audio>，则将使用原生播放器。

插件和组件

一些优秀的开发者为 CMS 和 JavaScript 框架开发了插件和组件：

类型	维护者	链接
WordPress	Brandon Lavigne (@drrobotnik)	https://wordpress.org/plugins/plyr/
Angular	Simon Bobrov (@smnbbrv)	https://github.com/smnbbrv/ngx-plyr
React	Chintan Prajapati (@chintan9)	https://github.com/chintan9/plyr-react
视图	加布·邓恩 (@redxtech)	https://github.com/redxtech/vue-plyr
尼奥斯	乔恩·乌尔曼 (@jonnitto)	https://packagist.org/packages/jonnitto/plyr
卡比	多米尼克·普斯切尼奇尼 (@dpschen)	https://github.com/dpschen/kirby-plyrtag
REDAXO	FriendsOfRedaxo / skerbis (@skerbis)	https://github.com/FriendsOfREDAXO/plyr
svelte-plyr	Ben Woodward / benwoodward (@benwoodward)	https://github.com/benwoodward/svelte-plyr

问题

如果您发现 Plyr 有任何异常，请使用 GitHub 问题跟踪器告知我们。

作者

Plyr 由 @sam_potts / sampotts.me 开发，并得到了众多优秀
贡献者的帮助。

版权与许可

MIT 许可证

关于项目

Plyr 是一款简单、轻量、可访问且可定制的 HTML5、YouTube 和 Vimeo 媒体播放器，支持现代浏览器。

MIT

Javascript

29,355

3114

427

2015-02-14

2025-08-27

Plyr是一款简单、轻量且可定制的HTML5播放器

功能

演示

快速设置

HTML

HTML5 视频

HTML5 Audio

YouTube

Vimeo

JavaScript

CSS

SVG 精灵图

自托管

广告

高级

自定义 CSS

Sass

SVG

使用 iconUrl 选项

跨域 (CORS)

字幕

JavaScript

初始化

单个播放器

多个播放器

选项

API

对象

方法

Getters 和 Setters

.source 设置器

事件

标准媒体事件

仅限 HTML5

仅限 YouTube

嵌入

快捷键

预览缩略图

全屏

浏览器支持

Polyfills

检查支持情况

通过编程禁用支持

插件和组件

问题

作者

版权与许可

关于项目

增长趋势 - stars

使用 `iconUrl` 选项

`.source` 设置器