Plyr 播放器使用筆記：控制項、取值、事件、改樣式、外部平台影片

Plyr 播放器使用筆記：控制項、取值、事件、改樣式、外部平台影片
Plyr 播放器使用筆記：控制項、取值、事件、改樣式、外部平台影片

本篇要解決的問題

上一篇我們使用了 Video.js 這個播放器，這一篇來用另一個播放器套件：Plyr。會選這套是因為 August 覺得他們的預設介面比 Video.js 還要好看，而且官方文件也沒有落落長到這一輩子都讀不完的架勢，除了支援 HTML5 的 Video、Audio，還支援 Youtube、Vimeo，如果要快速使用一個影音播放器，August 比較推薦 Plyr 而不是 Video.js。

本篇筆記的部份是實務上目前常用的：控制項、取值、事件、改樣式、外部平台影片。

Plyr 的官方件就寫在 GitHub 上：https://github.com/sampotts/plyr#readme

本篇最後完成的 Demo 在這：https://letswritetw.github.io/letswrite-plyr-player/

建立影片播放器及控制項

最基本的使用，範例程式碼如下：

<!-- 引用 CSS -->
<link rel="stylesheet" href="https://cdn.plyr.io/3.7.2/plyr.css" />

<!-- 放置影音 -->
<video id="player" playsinline controls data-poster="poster 圖檔路徑">
  <source src="MP4 影片檔路徑" type="video/mp4" />
</video>

<!-- 引用 JS -->
<script src="https://cdn.plyr.io/3.7.2/plyr.js"></script>
<script>
  const player = new Plyr('#player');
</script>

對，就是這麼樸實無華的簡單，立馬就看到一個美美的播放器產生，以下 poster 圖檔跟影片都用官網的 Demo：

圖片來源：https://plyr.io/
圖片來源：https://plyr.io/

當然，它還有很多東西可以使用。

開啟所有控制項

Plyr 播放器預設就跟上面截圖一樣，有些像是快轉幾秒、倒退幾秒的按鈕是不會出現的，可以用 controls 這個參數選擇要開啟哪些控制項，以下是複製文件上的程式碼：

const player = new Plyr('#player', {
 controls: [
   'play-large', // The large play button in the center
   'restart', // Restart playback
   'rewind', // Rewind by the seek time (default 10 seconds)
   'play', // Play/pause playback
   'fast-forward', // Fast forward by the seek time (default 10 seconds)
   'progress', // The progress bar and scrubber for playback and buffering
   'current-time', // The current time of playback
   'duration', // The full duration of the media
   'mute', // Toggle mute
   'volume', // Volume control
   'captions', // Toggle captions
   'settings', // Settings menu
   'pip', // Picture-in-picture (currently Safari only)
   'airplay', // Airplay (currently Safari only)
   'download', // Show a download button with a link to either the current source or a custom URL you specify in your options
   'fullscreen', // Toggle fullscreen
 ]
});

新增字幕檔

字幕檔的部份，HTML 如下：

<video id="player" playsinline controls data-poster="poster 圖檔路徑">
  <source src="MP4 影片檔路徑" type="video/mp4" />
  
  <!-- 加入字幕檔 -->
  <track kind="captions" label="中文字幕"
         src="dist/captions-zhTW.vtt" srclang="zh" default="default"/>
  <track kind="captions" label="English captions"
         src="dist/captions-en.vtt" srclang="en"/>
</video>

<track kind="captions"> 就是加入字幕檔的程式碼，如果加上 default 就是預設要顯示哪一個語系的字幕。

如果要判斷使用者目前的語系而顯示不同的字幕，就在 JS 上多加參數，如下：

const player = new Plyr('#player', {
  captions: { active: true, language: 'auto' }
});

新增多種畫質選擇

我們在看 Youtube 的時候，可以選擇要看的影片畫質，Plyr 也可以，方式就是針對不同的品質給不同的 source：

<video id="player" playsinline controls data-poster="poster 圖檔路徑">
  <source src="MP4 影片檔 1080p 的路徑" size="1080" type="video/mp4" />
  <source src="MP4 影片檔 720p 的路徑" size="720" type="video/mp4" />
  <source src="MP4 影片檔 480p 的路徑" size="480" type="video/mp4" />
</video>

使用者就會多了影片畫質的選項可以選擇：

可以選擇影片畫質
可以選擇影片畫質

提示 Tooltip

所有的按鈕預設是不會顯示說明的，基本上使用的 Icon 也是大家常見，但為了能夠顯示下一段的中文化，範例的頁面一樣有把 Tooltip 給打開。

const player = new Plyr('#player', {
  tooltips: { controls: true, seek: true }
});

tooltips.controls 是指控制項上的按鈕。

tooltips.seek 是指時間軸。

中文化介面

Plyr 跟 Video.js 一樣也可以設定操作介面為中文，不過 August 找了一下，沒找到像 Video.js 一樣有提供的中文 JSON 檔，這邊就參照 Video.js 自行翻譯了一個版本：

const player = new Plyr('#player', {
 i18n: {
   restart: '重播', rewind: '倒帶 {seektime} 秒',
   fastForward: '快轉 {seektime} 秒',
   play: '播放', pause: '暫停',
   seek: '尋找',
   played: '已播放',
   buffered: '緩衝',
   currentTime: '目前時間', duration: '總共時間',
   volume: '音量', mute: '靜音', unmute: '取消靜音',
   captions: '內嵌字幕',
   enableCaptions: '開啟內嵌字幕', disableCaptions: '關閉內嵌字幕',
   enterFullscreen: '全螢幕', exitFullscreen: '退出全螢幕',
   frameTitle: '{title} 播放器',
   settings: '設定',
   speed: '播放速率', normal: '一般',
   quality: '畫質',
   loop: '循還播放',
   start: '開始', end: '結束',
   all: '全部',
   reset: '重置',
   disabled: '關閉',
   advertisement: '廣告',
 }
});

時間軸加上段落標記

我們看 Youtube 時，有些影片會看見作者有在時間軸上自行標記一個說明，Plyr 也有提供這功能：

const player = new Plyr('#player', {
 markers: {
   enabled: true,
   points: [
     { time: 10, label: '段落標記 Demo1', },
     { time: 20, label: '段落標記 Demo2', },
     { time: 30, label: '段落標記之 <strong>可以用粗體字</strong>', },
   ]
 }
});

播放器上當使用者滑鼠移到標記的段落上就會看到像這樣：

使用段落標記

取值：影片總時長、當下秒數

Plyr 可以取到影片上的數值，本篇一樣只示範取影片總時長、當下秒數。

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

// 影片總時長（單位：秒）
const duration = player.duration; // => 39.76

// 當下秒數
let currentTime = player.currentTime; // => 7.902844

官方文件 上有說明共有哪些值可以取，甚至還可以更改，就請各位朋友自行參閱囉~。

監聽事件：播放、暫停

Plry 有許多事件可以監聽，讓數據分析的人員可以收到資料來分析使用者的觀看情形。

本篇一樣僅示範播放、暫停這二個常見事件。

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

// 播放事件
player.on('play', (event) => {
  // 影片播放時要做的事
});

// 暫停事件
player.on('pause', (event) => {
  // 影片暫停時要做的事
});

官方文件 上有所有可監聽事件的說明，一樣請各位朋友自行取閱。

修改樣式

Plry 預設色就是他們的藍色，但跟 Video.js 不同，沒有再提供其他樣式的 CSS 檔，但有把 CSS 的各種變數寫成說明文件，要改樣式就是直接修改 CSS 變數。

例如主要顏色如果要修改成我們的品牌色，這邊以 Let’s Write 本身的品牌藍為例子，有以下二種方式可以修改：

<!-- 修改頁面上所有 Plyr 播放器的主要顏色 -->
<style>
  :root {
    --plyr-color-main: #42A6F7;
  }
</style>

<!-- 只修改指定的 Plyr 播放器的主要顏色 -->
<style>
  .theme-cutstom {
    --plyr-color-main: #42A6F7;
  }
</style>
<div class="theme-cutstom">
  <video id="player" playsinline controls data-poster="poster 圖檔路徑">
    <source src="MP4 影片檔路徑" type="video/mp4" />
  </video>
</div>

除了主要色系，官方文件 上列了超多變數，想完整客製樣式的朋友請自行觀看。

外部平台影片：Youtube、Vimeo

Plry 可以直接嵌入 Youtube、Vimeo 這二家平台的影片，是不是好棒棒~

Youtube

引用的方式很簡單，如下：

<div class="plyr__video-embed" id="player-youtube">
  <iframe src="https://www.youtube.com/embed/YBePFPrlYgg"
          allowfullscreen allowtransparency allow="autoplay"></iframe>
</div>

<script>
  const playerYoutube = new Plyr('#player-youtube', {
    noCookie: false, rel: 0, showinfo: 0, iv_load_policy: 3, modestbranding: 1
  });
</script>

後面的 options 不一定要有，也可以直接寫：

const playerYoutube = new Plyr('#player-youtube');

options 的說明，文件上是說……

「請看 Youtube 的文件說明」XD~ 這邊就提供 Youtube 的說明連結啦：Supported parameters。

嵌入 Youtube 的影片後，操作介面會是 Plyr 的唷~ 不再是 Youtube 那個紅紅的樣式：

嵌入 Youtube 的影片也是用 Plyr 的樣式

為什麼 Demo 頁上會選擇這則 Youtube 影片呢？因為真的超好笑，Auguts 每次看每次都笑到流淚，推薦給寫程式寫到煩悶的各位~

Youtube 可以監聽原有的 statechange 事件，回傳的值就跟 Youtube iframe API 的相同：

playerYoutube.on('statechange', event => {
  console.log(event.detail.code); // => -1, 0, 1, 2, 3, 5
});

回傳的六個數字，代表影片的不同狀態，說明如下：

  • -1：unstarted 未啟動，初次載入
  • 0：ended 結束
  • 1：playing 播放中
  • 2：paused 暫停
  • 3：buffering 緩衝中
  • 5：video cued 準備好可以播放了

Vimeo

要嵌入 Viemo 的影片，方式跟嵌 Youtube 的一樣簡單：

<div class="plyr__video-embed" id="player-vimeo">
  <iframe src="https://player.vimeo.com/video/708244501"
          allowfullscreen allowtransparency allow="autoplay"></iframe>
</div>

<script>
  const playerVimeo = new Plyr('#player-vimeo', {
    byline: false, portrait: false, title: false, speed: true, transparent: false
  });
</script>

options 一樣可寫可不寫，至於說明……一樣是看 Vimeo 的文件：Embed Options。

範例原始碼

本篇範例的原始碼有放上 GitHub，取用前麻煩點個星星或分享本篇文章，一個小小動作就是對本站大大的鼓勵。

Demo：https://letswritetw.github.io/letswrite-plyr-player/

原始碼：https://github.com/letswritetw/letswrite-plyr-player

Summary
Plyr 播放器使用筆記：控制項、取值、事件、改樣式、外部平台影片
Article Name
Plyr 播放器使用筆記：控制項、取值、事件、改樣式、外部平台影片
Description
本篇大綱：本篇要解決的問題。建立影片播放器及控制項、開啟所有控制項、新增字幕檔、新增多種畫質選擇、提示 Tooltip、中文化介面、時間軸加上段落標記。取值：影片總時長、當下秒數。監聽事件：播放、暫停。修改樣式。外部平台影片：Youtube、Vimeo。
August
Let's Write
Let's Write
https://letswritetw.github.io/letswritetw/dist/img/logo_512.png
訂閱
通知
guest

0 Comments
最舊
最新
Inline Feedbacks
看所有留言

You may also like

© 2025 Let's Write. All Rights Reserved.