a-barrage v0.0.1

A-Barrage

🎦 Live Demo

https://logcas.github.io/a-barrage/example/

🧐 如何使用

A-Barrage同时支持Canvas渲染和HTML+CSS的渲染模式，你可以根据实际情况采用不同的渲染引擎进行弹幕的渲染。其中，Canvas是非交互式渲染，也就是说，采用Canvas渲染的弹幕并不会有任何的交互操作，纯展示性质；HTML+CSS是交互式渲染，如果你的网站允许用户与弹幕之间进行一些交互（如点赞、回复等），那么可以采用HTML+CSS的渲染模式，它会结合浏览器的DOM事件进行响应。

A-Barrage默认使用的是Canvas渲染模式。

🎞 使用Canvas进行弹幕渲染

采用Canvas渲染，即意味着你需要在模板中提供一个<canvas>元素：

<canvas id="danmu"></canvas>

然后，实例化一个ABarrage对象，同时传入canvas元素：

new ABarrage(
  '#danmu',
  config
)

其中，config对象支持如下属性（全部都是可选的，如下值为默认值）：

config = {
  engine: 'canvas', // 渲染引擎 canvas 或 css3 可选
  zoom: 1, // 文字缩放比
  proxyObject: null, // 事件代理触发对象
  usePointerEvents: true, // 屏蔽弹幕画布的点击事件
  maxTrack: 4, // 最大轨道数
  fontSize: 20, // 文字大小，单位为px
  fontColor: '#fff', // 文字颜色
  duration: 10000, // 弹幕留存时间
  trackHeight: 20 * 1.5 // 轨道高度，默认为默认文字的1.5倍
}

⛱ 使用HTML+CSS进行弹幕渲染

采用HTML+CSS渲染，你需要做的是准备一个<div>元素就好：

<div id="container">
  <div id="danmu"></div>
  <video/>
</div>

然后，实例化一个ABarrage对象，同时传入div元素：

new ABarrage(
  '#danmu',
  config
)

其中，config对象支持如下属性（全部都是可选的，如下值为默认值）：

config = {
  engine: 'css3', // 渲染引擎 canvas 或 css3 可选
  zoom: 1, // 文字缩放比
  proxyObject: null, // 事件代理触发对象
  usePointerEvents: true, // 屏蔽弹幕画布的点击事件
  maxTrack: 4, // 最大轨道数
  fontSize: 20, // 文字大小，单位为px
  fontColor: '#fff', // 文字颜色
  duration: 10000, // 弹幕留存时间
  trackHeight: 20 * 1.5, // 轨道高度，默认为默认文字的1.5倍
  wrapper: document.querySelector('#container') // wrapper 用于弹幕交互的事件代理，如果需要交互，则必须传入
}

通用步骤

然后，可以通过add()方法添加弹幕：

// 添加滚动弹幕
instance.add(danmu, 'scroll')

// 添加固定在顶部的弹幕
instance.add(danmu, 'fixed-top')

// 添加固定在底部的弹幕
instance.add(danmu, 'fixed-bottom')

其中，第一个参数是一个RawBarrageObject对象，它的类型是这样的：

RawBarrageObject {
  text: string //  文本 
  color?: string // 颜色，可选
  size?: number // 字体大小，可选
}

第二个参数也是可选的，默认为scroll，即滚动弹幕。顶部弹幕和底部弹幕分别为：fixed-top、fixed-bottom。

📅 事件机制

首先，为了弹幕的正常显示，你必须拥有这样的层级：

------用户视觉-------
   👇  👇  👇  👇
--------弹幕--------
-------播放器-------

以上层级的HTML结构一般是这样的：

<div id="container">
  <video/>
  <canvas id="danmu"></canvas>
<div>

这样会造成一个问题，因为弹幕元素和播放器元素是兄弟元素结点，所以，当点击弹幕时，事件并无法传达到播放器上。

为了解决事件被阻挡的问题，这里主要使用了两种方法： 1. pointer-events:none 2. 事件代理

usePointerEvent

配置选项中的usePointerEvent默认为true，也就是默认状态下会为画布元素添加该CSS属性。这样的话画布元素就不会成为鼠标事件的target，那么鼠标事件就会从下一层的元素开始触发。

但是这个属性有兼容性问题，对于IE仅支持IE11+的浏览器，其余浏览器的最新版本基本已支持。

综上，所以有了事件代理机制。

事件代理

ABarrage类是继承自EventEmitter的，因此它也是一个事件中心，拥有$on、$once、$emit、$off等方法。

对于click、dblclick、mousedown、mousemove、mouseout、mouseover、mouseup这几个鼠标事件，当画布触发这些事件时，会调用$emit同步触发通过$on绑定的事件处理器。

除此之外，你也可以添加自定义事件。

🔎 API

add(barrage, type)

其中，barrage是一个RawBarrageObject对象，它的结构是这样的：

{
  text: string,
  color?: string,
  size?: number
}

type可选scroll、fixed-top、fixed-bottom，分别代表滚动弹幕、固定顶部弹幕、底部弹幕。默认为scroll。

start()

弹幕开始

stop()

弹幕暂停

resize(,width)

宽度会影响弹幕轨道的宽度，当canvas的宽度更改时，务必调用该方法更新轨道宽度。

clear()

清空弹幕

setOpacity(opacity = 1)

设置弹幕文字的不透明度，默认为1，即不透明。取值区间为[0,1]。

setFontSize(zoom = 1)

全局设置文字的缩放大小。需要注意的是，setFontSize并不会改变实话配置中的fontSize大小，而是通过设置config.zoom（缩放比率）的方式更改输出文字的大小。默认为1。

$on(eventName, handler)

绑定事件处理器。

$once(eventName, handler)

绑定事件处理器，但它只会执行一次。

$off(eventName, handler)

接触事件处理器，当handler不传时，会消除eventName事件的所有回调。

$emit(eventName, ...args)

触发事件处理器，从第二个参数开始可以传入回调函数的参数。

onBarrageHover(handler) ***仅作用于HTML+CSS渲染***

当鼠标定位到某个弹幕时触发，handler回调函数的参数分别为：弹幕实例、弹幕对应的DOM元素。

onBarrageBlur(handler) ***仅作用于HTML+CSS渲染***

当鼠标从某个弹幕移出时触发，handler回调函数的参数分别为：弹幕实例、弹幕对应的DOM元素。

onBarrageClick(handler) ***仅作用于HTML+CSS渲染***

当鼠标点击某个弹幕时触发，handler回调函数的参数分别为：弹幕实例、弹幕对应的DOM元素。

License

MIT