快速开始

介绍#

NPlayer 是由 Typescript 加 Sass 编写，无任何第三方运行时依赖，兼容 IE11，支持移动端、支持 SSR、支持直播。高度可定制，所有图标、主题色等都可以替换，并且提供了内置组件方便二次开发。你可以自定义任意多个断点，不仅仅是兼容移动端，只要愿意，你可以非常轻松的兼容手机竖屏、手机横屏、平板等设备。它还拥有插件系统，弹幕功能就是使用插件形式提供，使用时按需引入即可。该播放器还可以接入任何流媒体，如 hls、dash 和 flv 等。

NPlayer

安装#

npm i -S nplayer

详细内容请查看安装章节。

开始使用#

import Player from 'nplayer'

const player = new Player({
  src: 'https://v-cdn.zjol.com.cn/280443.mp4'
})

// player.mount('#app')
player.mount(document.body)

首先我们导入 Player，然后创建一个播放器实例，并传入视频的地址，然后调用 mount 方法将它挂载到 body 元素中。

import Player from 'nplayer'

const video = document.createElement('video')
video.src = 'https://v-cdn.zjol.com.cn/280443.mp4'
const player = new Player({ video, videoProps: { autoplay: 'true' } })

player.mount(document.body)

还可以通过 video 参数，自己提供 video 元素，而不是让 NPlayer 自己创建。

videoProps 给 video 元素设置属性。

mount 方法可以将播放器挂载到指定 DOM 元素中，它接收一个参数，可以是一个字符串或一个 DOM 元素。当是字符串时，将会自动查找相应的 DOM 元素。

Video Source#

除了设置 video 元素的 src 参数，还可以添加 Source DOM 元素。

new Player({ video, videoSources: [{ src: 'video.webm', type: 'video/webm' }] })

相当于下面代码。

<video class="nplayer_video" preload="auto" playsinline="true">
  <source src="video.webm" type="video/webm">
</video>

其中 crossorigin、preload 和 playsinline 是默认的 videoProps。

一个 Source 参数签名如下。

interface VideoSource {
  media?: string;
  sizes?: string;
  src?: string;
  srcset?: string;
  type?: string;
}

获取 DOM 元素#

import Player from 'nplayer'

const player = new Player()
player.mount(document.body)

console.log(player.container) // document.body
console.log(player.el) // DIV Element
console.log(player.video) // VIDEO Element

你可以通过 container 获取到播放器容器元素，也就是 mount 方法参数对应的 DOM 元素，video 属性可以获取到播放器使用的 video 元素， el 可以获取播放器的 DOM 元素。

info

NPlayer 中很多对象都有 el 属性，它表示组件对应的 DOM 元素。

属性和方法#

Player 上有很多方式访问到自己。

import Player from 'nplayer'

const player =  new Player()
console.log(player.Player === Player) // true
console.log(Player.Player === Player) // true

Player 有 Player 静态属性可以访问到自己。并且 Player 的实例的原型上也有 Player 属性可以访问自身。Player 上有很多静态属性，如果你只访问得到 Player 实例时，你也可以通过 Player 属性访问这些静态属性。

const Plugin = {
  apply(player) {
    console.log(player.Player.components) 
    console.log(player.Player.EVENT)
    console.log(player.EVENT)
    // ...
  }
}

自定义插件中只能访问到 Player 实例，这时你就可以通过 Player 属性访问静态属性。

Player 实例上有很多属性和方法，比如 player.fullscreen 是 Fullscreen 对象，通过它你可以手动进入和退出全屏，player.playing 属性来判断当前时候在播放等等。

更多请查看 API。

事件#

player 有下面 5 个事件相关的方法。

方法	描述
on(evt: string, fn: Function)	监听事件
once(event: string, fn: Function)	监听事件，但是只调用一次回调函数
emit(evt: string, ...args: any[])	触发事件
off(evt: string, fn?: Function)	解除事件监听
removeAllListeners(evt?: string)	移除所有事件监听

你可以使用这些方法监听内置事件或触发自定义事件。

NPlayer 事件名是大驼峰形式的字符串。

import Player, { EVENT } form 'nplayer'

const player = new Player()

console.log(EVENT.CONTROL_SHOW)
console.log(Player.EVENT.CONTROL_SHOW)
console.log(player.EVENT.CONTROL_SHOW)
console.log('ControlShow')

上面打印都是相同的字符串。

更多请查看事件。

播放器尺寸变化#

默认情况下当浏览器尺寸变化或者播放器容器尺寸变化时，播放器及其内部组件会自动调节自身尺寸。

你可以通过 player 对象上的 rect 属性获取播放器的宽高和坐标（内部是使用 getBoundingClientRect API）。

import Player from 'player'

const player = new Player()
console.log(player.rect.width)
console.log(player.rect.height)
console.log(player.rect.x)
console.log(player.rect.y)

你可以监听 UpdateSize 事件来响应播放器尺寸变化。

caution

NPlayer 监听自身尺寸变化使用了 ResizeObserver api。如果你的目标浏览器不支持 ResizeObserver。当时播放器尺寸变化时，请手动触发 UpdateSize，player.emit('UpdateSize') 或者在 NPlayer 之前引入 ResizeObserver 的 polyfill。

销毁#

player 及其中组件都实现了 Disposable 接口，也就是拥有 dispose 方法，调用该方法将会销毁该对象。

const player = new Player()
player.mount(document.body)
setTimeout(() => player.dispose(), 3000)
// 3 秒后销毁 player

多层级#

NPlayer 由 6 个不同功能的层级组成，每个层级有自己的 z-index。

层级	z-indx	描述
video 视频元素	-	视频元素没有设置 z-index
control 控制条	10	视频底部控制条
poster 海报	20	视频海报
loading 加载中	30	视频加载时出现的加载中元素
contextmenu 右键菜单	40	NPlayer 右键菜单
toast 提示框	50	提示框

z-index 高的组件会覆盖低的组件。当要实现自己组件时可以参考上表中的 z-index，将它放入合适层级。如，弹幕插件默认层级 z-index 是 5，那它将出现在 control 下方，video 元素上方。

响应式布局#

NPlayer 一共有三个控制条，底部两个，顶部一个。

NPlayer control

为了看清 3 个控制条，这里再给每个控制条加了个背景色，默认是没有的。

new Player({
  controls: [
    ['play', 'volume', 'time', 'spacer', 'web-fullscreen', 'fullscreen'],
    ['progress'],
    ['spacer', 'settings']
  ]
}).mount(document.body)

这个布局是通过 controls 参数配置的。它是一个二维数组，下标 0 和 1 是下方的两个控制条，2 是顶部的控制条。

详情请查看控制条章节。

NPlayer 还提供了两套交互，触屏交互和键鼠交互，详情请查看响应式/多设备章节。

更新配置#

NPlayer 几乎所有部分都可以配置。

配置主题，请参考主题章节。
添加、移除控制条项目或改变顺序，请参考控制条章节。
添加、移除控制条设置项目或改变顺序，请参考设置菜单章节。
添加、移除右键菜单项目或改变顺序，请参考右键章节。
更多请直接的点击侧边栏对应章节。

当你实例一个 player 对象后，想修改它的配置，可以使用 updateOptions(新的配置) 方法。

player.updateOptions({
  poster: 'new_url',
  thumbnail: {
    images: ['new_url']
  }
})

上面这个例子是使用它来更新海报和预览缩略图。

你还可以监听 UpdateOptions 事件来做出变更，如，在自定义插件中可以这样。

const Plugin = {
  apply(player) {
    player.on('UpdateOptions', () => this.update(player.opts))
  }
}

但并不是所有配置项都会做出对应修改，settings、contextMenus 和 controls 变化并不会做出对应修改。

如果你想更新控制条，可以使用 updateControlItems 方法。详情请查看控制条章节。

player.updateControlItems(['spacer', 'settings'], 2)

Toast#

如果你想给弹出一个提示时，可以使用 player.toast。

const player = new Player()
player.toast.show('提示~', 'left-top', 1000)

在播放器左上方弹出一个显示 1 秒的提示。Toast 详情请查看 API 部分文档。

内置组件#

Player 提供了一些内置组件来方便二次开发和统一交互。比如控制条项目的 Tooltip 组件，进度条 Slider 组件，Checkout 选择框组件等等。

请查看内置组件章节了解更多。

问题 & 新功能#

如果你遇到 BUG 或者是想要新功能，欢迎提交 issue。

介绍#

安装#

开始使用#

Video Source#

获取 DOM 元素#

info

属性和方法#

事件#

播放器尺寸变化#

caution

销毁#

多层级#

响应式布局#

更新配置#

Toast#

内置组件#

问题 & 新功能#

推荐文章#