播放器

安装

npm i @lin-media/player

初始化

import MediaPlayer from "@lin-media/player";

const player = new MediaPlayer({
  // 容器
  el: ".container",
  // 视频列表
  videoList: [
    {
      label: "标清",
      url: "http://127.0.0.1/demo.mp4"
    },
    {
      label: "高清",
      url: "http://127.0.0.1/demo.mp4",
      // 默认播放这个视频，否则默认为第一个
      default: true
    }
  ]
});

参数

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | -------------- | -------------------------------------------------- | -------------------- | -------------------- | ----------- | | el | 播放容器 | String，HTMLElement | — | — | | videoList | 视频播放列表，格式见下方 | Array | — | — | | speedList | 倍数列表，可选，格式见下方 | Array | — | — | | plugins | 注册局部插件，可选 | Array | — | — | | autoplay | 是否自动播放，可选 | Boolean | — | false | | muted | 是否静音，一般配合 autoplay 属性实现自动播放，可选 | Boolean | — | false | | customType | 自定义 esm，可选，，格式见下方 | Function | — | — | | live | 是否为直播，可选 | Boolean | — | false | | crossorigin | 是否开启跨域，可选 | Boolean | — | true | | preload | 视频预加载，可选 | String | none，metadata，auto | auto | | poster | 视频封面，可选 | String | — | — | | controls | 播放器控件是否显示，可选，详细见下方 | boolean，ControlsObj | false，ControlsObj | ControlsObj | | lang | 使用的语言 | String | zh，en | zh | | customLanguage | 自定义语言包 | Object | — | — |

videoList 格式

| 字段 | 说明 | 类型 | | ------- | ------------------------------------------ | ------- | | label | 清晰度文本 | String | | url | 播放地址 | String | | default | 是否默认播放，可选，false 时默认播放第一个 | Boolean |

speedList 格式

| 字段 | 说明 | 类型 | | ------- | ---------------------------------- | ------- | | label | 倍数文本 | String | | value | 倍数值，可选值 0-2 | Number | | default | 默认倍数，可选，false 时默认第一个 | Boolean |

customType 参数

| 字段 | 说明 | 类型 | | ------------ | ---------------- | ---------------- | | videoElement | video 标签 | HTMLVideoElement | | options | videoList 列表项 | Object |

controls 参数格式

注意：

当 controls 值为 false 时，所有控件将不会显示。当 controls 值为一个对象时（即ControlsObj），可根据下方的字段来选择那些控件需要显示，那些不需要显示，其中 true 为显示控件， false 为隐藏控件。所有控件默认显示

| 字段 | 说明 | 类型 | 默认值 | | ---------------- | ------------------ | ------- | ------ | | VideoPlayButton | 播放按钮控件 | Boolean | true | | VideoVolume | 音量控件 | Boolean | true | | VideoLive | 直播提示控件 | Boolean | true | | VideoSpeed | 倍速控件 | Boolean | true | | VideoFullscreen | 全屏控件 | Boolean | true | | VideoDefinition | 清晰度控件 | Boolean | true | | VideoProgress | 进度条控件 | Boolean | true | | VideoTip | 通知提示控件 | Boolean | true | | VideoTime | 时间控件 | Boolean | true | | VideoLoading | loading 控件 | Boolean | true | | VideoFloatButton | 悬浮播放按钮控件 | Boolean | true | | VideoMask | 视频遮罩层控件 | Boolean | true | | VideoControls | 视频下方控制条 | Boolean | true | | DomResizeObserver | 播放器DOM元素大小发生变化监听 | Boolean | true | | ShortcutKey | 快捷键功能控件 | Boolean | true | | VideoPlayer | 视频播放控件 | Boolean | true |

事件

• 自定义事件

| 事件名称 | 说明 | 回调参数 | | ----------------------- | ------------------------ | -------- | | destroy | 播放器销毁时触发 | — | | switch_definition_start | 清晰度切换前触发 | — | | switch_definition_end | 清晰度切换后触发 | — | | enter_browser_screen | 浏览器进入全屏时触发 | — | | exit_browser_screen | 浏览器退出全屏时触发 | — | | enter_web_screen | 网页进入全屏时触发 | — | | exit_web_screen | 网页退出全屏时触发 | — | | show_controls | 控制条显示时触发 | — | | hide_controls | 控制条隐藏时触发 | — | | resize | 播放器大小发生变化时触发 | — | | keyboard_right | 按下键盘 → 键时触发 | — | | keyboard_left | 按下键盘 ← 键时触发 | — | | keyboard_up | 按下键盘 ↑ 键时触发 | — | | keyboard_down | 按下键盘 ↓ 键时触发 | — | | keyboard_space | 按下键盘 空格 键时触发 | — | | picture_in_picture_window_resize | 画中画窗口发生变化时触发 | — |

• 原生 video 标签事件

| 事件名称 | 说明 | 回调参数 | | -------------- | ------------------------------------------------------- | -------- | | abort | 发生中断时触发 | event | | canplay | 视频能够播放，但可能因缓冲停止时触发 | event | | canplaythrough | 视频能够播放，并且无需因缓冲而停止，ie 上触发不了改事件 | event | | durationchange | 视频总时长发生变化时触发 | event | | emptied | 媒介资源元素突然为空时（网络错误、加载错误等）时触发 | event | | ended | 视频播放结束时触发 | event | | error | 视频加载发生错误时触发 | event | | loadeddata | 加载数据时触发 | event | | loadedmetadata | 媒介元素的持续时间以及其他媒介数据已加载时触发 | event | | loadstart | 开始加载数据时触发 | event | | pause | 视频暂停触发 | event | | play | 视频播放时触发 | event | | playing | 视频已经开始播放时触发 | event | | progress | 获取数据（缓冲数据）时触发 | event | | ratechange | 视频倍数发生变化时触发 | event | | seeked | 跳转到指定时间之后触发，一般是用户拖拽进度条时触发的 | event | | seeking | 正在跳转到指定的时间时触发 | event | | stalled | 取回媒介数据过程中（延迟）存在错误时触发 | event | | suspend | 浏览器已在取媒介数据但在取回整个媒介文件之前停止时触发 | event | | timeupdate | 播放位置发生变化时触发 | event | | volumechange | 视频音量发生变化时触发 | event | | waiting | 正在播放，但是因为缓冲而卡顿时触发 | event | | enterpictureinpicture | 进入画中画时触发 | event | | leavepictureinpicture | 退出画中画时触发 | event |

API

实例方法

• player.$on(eventName: string, handler: Function) : 事件监听

• player.$emit(eventName: string, ...data: any) : 触发事件

• player.$once(eventName: string, handler: Function) : 事件监听，只触发一次

• player.$off(eventName: string, handler?: Function) : 取消事件监听

• player.play() : 播放视频

• player.pause() : 暂停视频

• player.seek(time: number) : 跳转到指定时间

• player.setNotice(text: string, time?: number) : 显示通知

• player.switchDefinition(index: number) : 切换清晰度

• player.setSpeed(playbackRate: number) : 设置倍数

• player.setVolume(volume: number) : 设置音量

• player.toggle() : 切换播放状态

• player.requestFullscreen(type: 'web'|'browser') : 进入网页/浏览器全屏

• player.cancelFullscreen(type: 'web'|'browser') : 退出网页/浏览器全屏

• player.showControls() : 显示下方控制条

• player.hideControls() : 隐藏下方控制条

• player.toggleControls() : 切换下方控制条显示/隐藏状态

• player.destroy() : 销毁播放器

• player.requestPictureInPicture() : 进入画中画

• player.exitPictureInPicture() : 退出画中画

实例属性

• player.videoElement : 原生 video 标签

• player.paused : 视频是否处于暂停状态

• player.currentTime : 视频当前时间

• player.duration : 视频总时长

• player.volume : 当前音量

静态方法

• MediaPlayer.useLang(lang:Object) : 自定义语言包，会跟默认的语言包进行合并

MediaPlayer.useLang({
  Player: {
    live: "直播",
    goBack: "快退{time}秒",
    fastForward: "快进{time}秒",
    volume: "音量{volume}",
    switch: "已经切换至{quality}",
    invalidDefinition: "无效清晰度"
  }
  // 其他插件语言包
});

• MediaPlayer.setLang(lang:string) : 设置使用何种语言，zh/en，默认 zh

• MediaPlayer.use(ctor: Function) : 注册全局插件

静态属性

• MediaPlayer.PlayerEvents : 播放器自定义事件

• MediaPlayer.VideoEvents : video 标签事件

• MediaPlayer.globalConfig : 默认的全局配置项，播放器在初始化的时候，会将用户传入的配置项跟全局的配置项进行合并，形成一个新的配置项

插件

播放器内置了插件功能，可自己实现一些奇奇怪怪的功能，比如自定义进度条提示点，截图，弹幕等等。

插件分为全局插件和局部插件，使用全局插件时，每个播放器实例都会具备全局插件的功能。使用局部插件时，只有当前播放器实例才会存在局部插件的功能。

全局插件是通过MediaPlayer.use(ctor: Function)进行注册的

局部插件是通过 options 参数中的plugins字段进行注册的

每一个插件都需要是一个构造器函数（类），并且需要包含pluginName静态属性，这是为了外部可以通过player.$plugins[pluginName]访问到插件实例

构造器函数（类）会接受到三个参数：

• player：播放器实例，即new MediaPlayer()，你可以使用该实例提供的任意方法
• el：整个播放器的 dom 元素，当你需要获取某个元素时，请使用el.querySelector()，而不是document.querySelector()

插件代码示例：

Test 插件

import MediaPlayer from "@lin-media/player";

class Test {
  // 提供一个pluginName静态属性
  static pluginName = "Test";
  el = null;
  player = null;

  constructor(player,el) {
    // 保存接受到的两个参数
    this.el = el;
    this.player = player;
    // 往播放器实例中添加一个sleep方法
    Object.defineProperty(player,'sleep',{
      get(){
        console.log("sleep");
      }
    })
    // 开始实现其他的功能
    this.init();
  }
  // 往播放器上面追加一个悬浮按钮，点击的时候发射click自定义事件，并对播放状态进行切换
  init() {
    const div = document.createElement("div");
    div.innerHTML = "切换播放状态";
    div.addEventListener("click", () => {
      // 通过发布订阅模式，实现事件的监听和发射
      this.player.$emit("test-click");
      // 切换播放器的播放状态
      this.player.toggle();
    });
    // 添加到播放器中
    this.el.appendChild(div);
  }
}

使用插件：

import MediaPlayer from "@lin-media/player";

// 全局注册插件
MediaPlayer.use(Test);

const player = new MediaPlayer({
  // ...
  // 或者通过局部注册
  // plugins:[MediaPlayer]
});

// Test插件发射出来的事件
player.$on("test-click", () => {
  console.log("test-click");
});
// Test插件在原型上面挂载的方法
player.sleep();
// 访问Test插件的实例
player.$plugins.Test;