可實現B站 蒙版彈幕 效果的前端組件 —— Barrage UI

Barrage UI

Best and lightest barrage component for web UI.

適用於 web 端用戶界面和播放器的輕量級彈幕組件

用途

• 爲你的 視頻播放器、圖片瀏覽器 等元素掛載彈幕動畫
• 用於實現 B 站(bilibili.com) 風格的 蒙版彈幕 效果

安裝

yarn add barrage-ui

或

npm install --save barrage-ui

快速開始

import Barrage from 'barrage-ui';
import example from 'barrage-ui/example.json'; // 組件提供的示例數據

// 加載彈幕
const barrage = new Barrage({
  container: 'barrage', // 父級容器或ID
  data: example, // 彈幕數據
  config: {
    // 全局配置項
    duration: 20000, // 彈幕循環週期(單位：毫秒)
    fontFamily: 'Microsoft Yahei', // 彈幕默認字體
    defaultColor: '#fff', // 彈幕默認顏色
  },
});

// 新增一條彈幕
barrage.add({
  key: 'fctc651a9pm2j20bia8j', // 彈幕的惟一標識
  time: 1000, // 彈幕出現的時間(單位：毫秒)
  text: '這是新增的一條彈幕', // 彈幕文本內容
  fontSize: 26, // 該條彈幕的字號大小(單位：像素)，會覆蓋全局設置
  color: '#0ff', // 該條彈幕的顏色，會覆蓋全局設置
});

// 播放彈幕
barrage.play();

初始化參數

建立彈幕實例時，須要傳入的初始化參數以下：

參數	數據類型	默認值	說明
container	string/element	必傳，無默認值	彈幕的掛載點
data	array	[]	彈幕數據
config	object	詳見全局配置項	詳見全局配置項
mask	string/ImageData	string/ImageData	蒙版圖像，用於實現蒙版彈幕效果，詳見蒙版彈幕
beforeRender	function	(ctx, progress, animState) => {}	幀渲染前的回調，函數實參分別爲：<br/>ctx canvas 畫布的上下文<br/>progress 動畫的播放進度(毫秒)<br/>animState 動畫狀態: 'paused' 或 'playing'
afterRender	function	(ctx, progress, animState) => {}	幀渲染後的回調，函數實參分別爲：<br/>ctx canvas 畫布的上下文<br/>progress 動畫的播放進度(毫秒)<br/>animState 動畫狀態: 'paused' 或 'playing'
overlapOptimized	boolean	false	彈幕裝填時是否啓用佈局優化，以儘量避免使相鄰時間的彈幕重疊

其中，container 參數在初始化實例時必傳，其餘參數爲可選，數據類型及默認值如上表所示。

全局配置項

配置項及默認值

彈幕的全部全局配置項及默認值以下：

{
  duration: -1, // 彈幕動畫的循環週期，-1 表示不循環播放
  speed: 100, // 彈幕的運動速度
  fontSize: 24, // 文字大小，單位：像素
  fontFamily: 'Microsoft Yahei', // 字體，默認值：微軟雅黑
  textShadowBlur: 1.0, // 字體陰影擴散，有效值 >= 0
  opacity: 1.0, // 透明度，有效值 0-1
  defaultColor: '#fff', // 默認顏色，與 CSS 顏色屬性一致
}

更新配置項

若是你的彈幕實例已建立或者正在播放，能夠經過 .setConfig() 方法進行實時更新：

// 更新全局透明度
barrage.setConfig({ opacity: 0.5 });

彈幕數據

結構與內容

彈幕數據集爲一個對象數組。每一個數組元素對應一條彈幕記錄，其結構以下：

{
  key: 'fctc651a9pm2j20bia8j',
  createdAt: '2019-01-13T13:34:47.126Z',
  time: 1200,
  text: '我膨脹了',
  fontFamily: 'SimSun',
  fontSize: 32,
  color: 'yellow',
}

數據字段

• createdAt - 彈幕的建立時間 (必須)
• time - 彈幕的動畫時間 (必須)
• text - 彈幕文本內容 (必須)
• key - 數據的惟一標示 (推薦)
• fontFamily - 彈幕文本的字體 (可選)
• fontSize - 彈幕文本字號大小，單位：像素 (可選)
• color - 彈幕文本的顏色 (可選)

關於 key

當動畫過程當中須要更新數據集時，推薦設置此字段。

動態更新數據集時，爲了動畫的連續性，更新先後的數據集可能存在部分相同的數據。Barrage 組件內部會對更新先後的數據的 key 進行比較，只增量渲染那些新增的數據，而不改變已經存在的彈幕布局。

綜上所述，字段 key 的取值應該是穩定且惟一的。對於同一條彈幕而言，key 的值應該是不變的。

裝填彈幕

裝填彈幕有兩種方式：

方式一：初始化時傳入數據

const barrage = new Barrage({
  container: 'barrage',
  data: JSON_DATA, // JSON_DATA -> 你的彈幕數據
});

方式二：初始化後更新數據

const barrage = new Barrage({
  container: 'barrage',
});

barrage.setData(JSON_DATA); // JSON_DATA -> 你的彈幕數據

新增彈幕

若是你的彈幕實例已建立或者正在播放，能夠經過 .add() 方法新增一條記錄：

barrage.add({
  key: 'fctc651a9pm2j20bia8j',
  time: 1000,
  text: '這是新增的一條彈幕',
  fontSize: 24,
  color: '#0ff',
});

.add() 方法通常搭配 數據提交/請求 操做進行使用，以實現真實的線上應用。

適用場景： 實現多終端同步的實時彈幕

1. 某用戶在客戶端提交了一條彈幕到服務端
2. 服務端將數據存儲並分發給正在進行會話的客戶端
3. 客戶端收到數據後，使用 .add() 方法進行數據更新

動畫控制接口

barrage.play()

描述

用於播放動畫。若當前爲暫停狀態，則從當前進度繼續播放

用例

barrage.play();

barrage.pause()

描述

用於暫停動畫

用例

barrage.pause();

barrage.replay()

描述

用於從新開始播放動畫

用例

barrage.replay();

barrage.goto(progress)

描述

用於跳轉播放進度。此方法在動畫播放和暫停的狀態下均有效

參數

progress - 待跳轉的進度。值爲一個毫秒數，表示跳轉到動畫的第幾毫秒

用例

barrage.goto(15000); // 跳轉到第 15 秒

動畫狀態屬性

barrage.progress

含義

當前動畫的播放進度

類型

描述播放進度的一個毫秒數

barrage.animState

含義

當前動畫的播放狀態

類型

描述播放狀態的一個字符串：

• 'ready' - 已就緒。即：barrage 實例已建立，但從未播放
• 'paused' - 已暫停
• 'playing' - 播放中

其餘接口&屬性

barrage.setMask(mask)

描述

用於設置蒙版圖像。蒙版圖像的概念見下文 蒙版彈幕

參數

mask - 蒙版圖像的 url 或 ImageData

用例

barrage.setMask('mask.png'); // 經過圖片 url 設置蒙版圖像

barrage.setMask(imageData); // 直接設置 ImageData 類型的數據

barrage.clearMask()

描述

用於清空當前的蒙版圖像。清空後若再也不從新設置蒙版圖像，則動畫將再也不具備蒙版效果

用例

barrage.clearMask();

barrage.canvas

含義

渲染彈幕的 canvas 畫布

barrage.ctx

含義

畫布的上下文，至關於 barrage.canvas.getContext('2d')

蒙版彈幕

Barrage 組件提供了實現 蒙版彈幕 效果的可能。基於本組件實現的 demo 效果以下：

什麼是「蒙版彈幕」

蒙版彈幕 是由知名彈幕視頻網站 bilibili 於 2018 年中推出的一種彈幕渲染效果，能夠有效減小彈幕文字對視頻主體信息的干擾。

詳細資料可參考 bilibili 的相關文章：

彈幕陽光計劃第十彈 蒙版據說過嗎，彈幕黑科技瞭解一下？

不擋臉，放肆看！B 站黑科技蒙版彈幕揭祕

實現原理

若是你熟悉最著名的圖像處理軟件——Adobe Photoshop，那麼你應該對 「蒙版」 的概念不陌生，「蒙版彈幕」 的實現原理與此相似，即：將圖像的一部分 「隱藏」。

Barrage 組件的初始化參數中的 mask 一項即用於處理蒙版效果。對於上文截圖中的效果，其使用的蒙版圖像效果以下：

彈幕渲染時，會將蒙版圖像中 「鏤空」 的部分（圖像 RGBA 通道中 Alpha 通道爲 0 的像素）去除，從而達到 「蒙版彈幕」 的效果。

簡單蒙版彈幕的實現

爲 barrage 實例設置蒙版圖像(mask)便可實現蒙版彈幕效果。

• 可經過初始化參數 mask 傳入蒙版圖像:

import Barrage from 'barrage-ui';
import example from 'barrage-ui/example.json';

const barrage = new Barrage({
  container: 'barrage',
  data: example,
  mask: 'mask.png', // 傳入蒙版圖像的 url
});

• 也能夠在彈幕初始化後，經過 .setMask() 方法進行實時更新：

import Barrage from 'barrage-ui';
import example from 'barrage-ui/example.json';

const barrage = new Barrage({
  container: 'barrage',
  data: example,
});

// 設置蒙版圖像
barrage.setMask('mask.png'); // 傳入蒙版圖像的 url

注意

mask 參數和 .setMask() 方法的參數類型一致，可接收圖像的 url 或 ImageData

實時渲染

上文的示例僅可以實現一幀蒙版圖像的渲染(只設置了一次 mask 而沒有實時更新它)，要實現實時的蒙版效果(如：與視頻實時同步的蒙版效果)，須要對彈幕動畫的每一幀進行處理。

使用組件提供的 beforeRender 鉤子函數，能夠輕易的實現：

import Barrage from 'barrage-ui';
import example from 'barrage-ui/example.json';

const barrage = new Barrage({
  container: 'barrage',
  data: example,
  beforeRender: (ctx, progress) => {
    const imageData = getMask(progress); // 用於獲取當前進度對應蒙版的方法
    barrage.setMask(imageData);
  },
});

固然，beforeRender 鉤子也能夠在彈幕初始化以後掛載：

import Barrage from 'barrage-ui';
import example from 'barrage-ui/example.json';

const barrage = new Barrage({
  container: 'barrage',
  data: example,
});

barrage.beforeRender = (ctx, progress) => {
  const imageData = getMask(progress); // 用於獲取當前進度對應蒙版的方法
  barrage.setMask(imageData);
};