西瓜播放器 HTML5 video video.js 播放器 HTML5播放器 mp4 hls hls.js flv flv.js dash dash.js 无缝切换

配置

播放器在实例化的时候提供配置选项,开发者可以根据自己的需求进行选择性地配置。 播放器容器和视频资源地址是生成播放器示例必须提供的内容。

注意

移动端使用西瓜播放器需要配置 白名单

必选配置

选择器

播放器实例化的时候需要明确DOM的占位,video将要输出到该DOM下,播放器的尺寸与占位DOM一致。

new Player({
  id:'mse'
})

播放器容器id也可以用容器的 DOM 实例来代替。

new Player({
  el:document.querySelector('#mse'),
})

视频源

播放器支持单个或多个视频源,建议使用多个源视频,这样当第一个视频出现问题的时候会自动启用第二个视频源,以此类推。

  1. 单个视频源
new Player({
  el:document.querySelector('#mse'),
  url: '//abc.com/**/*.mp4'
});
  1. 多个视频源
new Player({
  el:document.querySelector('#mse'),
  url: [{src:'/mp4/',type:"video/mp4"},{src:'/mp5/',type:'video/mp4'}]
});

注意

选择器和视频源是播放器必须提供的配置项,缺一不可。

可选配置

尺寸

开发者可以为播放器设置尺寸大小。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  width: 600,
  height: 337.5
});
  • 配置项:width, height
  • 默认值:600, 337.5

流式布局

设置为流式布局,可使播放器宽度跟随父元素的宽度大小变化,且高度按照配置项中的高度和宽度的比例来变化(播放器宽高未设置时按照内部默认值来计算)。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  fluid: true
});
  • 配置项:fluid
  • 默认值:false
  • 参考值:true | false

音量

开发者可以为播放器预设音量大小。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  volume: 0.6
});
  • 配置项:volume
  • 默认值:0.6
  • 参考值:0 ~ 1

自动播放

目前大多数浏览器厂商不建议播放器自动播放视频,开发者对此有特殊需求时可通过该配置项打开。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  autoplay: true
});
  • 配置项:autoplay
  • 默认值:false
  • 参考值:true | false

注意

根据浏览器规则,非静音状态下播放器的 autoplay 行为不一定会发生 参考。如果希望通过设置静音来保证 autoplay 确定发生,可在设置 autoplay: true 的同时配置 autoplayMuted : true

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  autoplay: true,
  autoplayMuted: true
});
  • 配置项:autoplayMuted
  • 默认值:false
  • 参考值:true | false

注意

在手机上 autoplay 部分机型无效。

初始化显示视频首帧

播放器默认不会初始化视频,如果需要在没有设置poster的情况下显示视频首帧,可通过设置videoInit配置项实现。

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  videoInit: true
});
  • 配置项:videoInit
  • 默认值:false
  • 参考值:true | false

封面图

封面图是当播放器初始化后在用户点击播放按钮前显示的图像。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  poster: '//abc.com/**/*.png'
});
  • 配置项:poster
  • 默认值:''
  • 参考值:'https://i.ytimg.com/vi/lK2ZbbQSHww/hqdefault.jpg'

倍速播放

播放器支持设置视频的当前播放速度。可通过defaultPlaybackRate设置初始速度。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  playbackRate: [0.5, 0.75, 1, 1.5, 2],
  defaultPlaybackRate: 1.5
});
  • 配置项:playbackRate
  • 默认值:''
  • 参考值:[0.5, 0.75, 1, 1.5, 2]

  • 配置项:defaultPlaybackRate
  • 默认值:''
  • 参考值:1.5

视频旋转

用户点击旋转按钮后,视频会旋转90度。同时播放器已将旋转方法API暴露出来方便开发者直接调用,详见 API

let player = new Player({
    el:document.querySelector('#mse'),
 	url: 'video_url',
    rotate: {   //视频旋转按钮配置项
        innerRotate: true, //只旋转内部video
        clockwise: false // 旋转方向是否为顺时针
    }
});
player.on('rotate',function(deg) {
    console.log(deg);// 旋转时会触发rotate事件,角度有四个值90,180,270,0
})
  • 默认值:{ innerRotate: false, clockwise: false }

注意

当innerRotate为false时,播放器的宽高需要与视频的分辨率一致。

预览

用户将鼠标指针移动到进度条某处时进度条上方会出现该时刻的视频预览图,服务端提供sprite图(由多张视频预览小图组成)作为预览图资源。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  thumbnail: {
      pic_num: 44,
      width: 160,
      height: 90,
      col: 10,
      row: 10,
      urls: ['./xgplayer-demo-thumbnail-1.jpg','./xgplayer-demo-thumbnail-2.jpg'],
  },
});
配置项含义
pic_num该视频资源所需预览小图数量
width预览小图宽度
height预览小图高度
colsprite图每列的预览小图数量
rowsprite图每行的预览小图数量
urlssprite图的源地址数组

下一集

视频跳转播放下一集,需提供视频资源列表。

let player = new Player({
    el: document.querySelector('#mse'),
    url: 'url0',
    playNext: {
        urlList: [
          'url1',
          'url2',
          'url3'
        ],
    }
});

视频下载

视频下载控件,点击后下载视频。

let player = new Player({
    download: true //设置download控件显示
});

  • 配置项:download
  • 默认值:false
  • 参考值:true | false

弹幕

用户观看视频时弹出的评论性字幕。与其它播放器弹幕效果不同的是,西瓜播放器通过算法设计实现了多条弹幕之间的不重叠和不碰撞,具体参考 前端算法之弹幕设计

注意

从 xgplayer@1.1.4-beta.45 版本开始支持以下弹幕使用方法。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  danmu: {
    comments: [  //弹幕数组
      {
        duration: 15000, //弹幕持续显示时间,毫秒(最低为5000毫秒)
        id: '1', //弹幕id,需唯一
        start: 3000, //弹幕出现时间,毫秒
        prior: true, //该条弹幕优先显示,默认false
        color: true, //该条弹幕为彩色弹幕,默认false
        txt: '长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕', //弹幕文字内容
        style: {  //弹幕自定义样式
          color: '#ff9500',
          fontSize: '20px',
          border: 'solid 1px #ff9500',
          borderRadius: '50px',
          padding: '5px 11px',
          backgroundColor: 'rgba(255, 255, 255, 0.1)'
        },
        mode: 'top' //显示模式,top顶部居中,bottom底部居中,scroll滚动,默认为scroll
        // el: DOM //直接传入一个自定义的DOM元素作为弹幕,使用该项的话会忽略所提供的txt和style
      }
    ],
    area: {  //弹幕显示区域
      start: 0, //区域顶部到播放器顶部所占播放器高度的比例
      end: 1 //区域底部到播放器顶部所占播放器高度的比例
    },
    closeDefaultBtn: true, //开启此项后不使用默认提供的弹幕开关,默认使用西瓜播放器提供的开关
    defaultOff: true //开启此项后弹幕不会初始化,默认初始化弹幕
  }
});
配置项含义
comments弹幕数组
area弹幕显示区域
closeDefaultBtn开启此项后不使用默认提供的弹幕开关,默认使用西瓜播放器提供的开关
defaultOff开启此项后弹幕不会初始化,默认初始化弹幕

弹幕控制相关API:

player.danmu.start() //弹幕初始化并播放(内部默认已调用)
player.danmu.pause() //弹幕暂停
player.danmu.play() //弹幕继续播放
player.danmu.stop() //弹幕停止并消失
player.danmu.sendComment({  //发送弹幕
    duration: 15000,
    id: 'id',
    start: 3000,
    txt: '弹幕内容',
    style: {
        color: '#ff9500',
        fontSize: '20px',
        border: 'solid 1px #ff9500',
        borderRadius: '50px',
        padding: '5px 11px',
        backgroundColor: 'rgba(255, 255, 255, 0.1)'
    }
})
player.danmu.setCommentDuration (id, duration) //按照id改变某一个弹幕的持续显示时间
player.danmu.setAllDuration (mode, duration) //改变所有已加入队列弹幕的持续显示时间
player.danmu.setCommentID (oldID, newID) //改变某一个弹幕的id
player.danmu.hide (mode) //屏蔽某一类弹幕(参数可选值 scroll | top | bottom | color)
player.danmu.show (mode) //显示某一类弹幕(参数可选值 scroll | top | bottom | color)

弹幕控制面板

将弹幕的屏蔽类型,不透明度,弹幕速度,字体大小等控制功能集成到控制面板,可对弹幕显示方式进行即时设置,提高西瓜播放器的用户体验度。

注意

该控制面板属于弹幕配置中的子配置,需要在弹幕配置中进行打开或关闭

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  danmu: {
    panel: true, //弹幕面板
    comments: [], //弹幕数组
    area: {  //弹幕显示区域
      start: 0, //区域顶部到播放器顶部所占播放器高度的比例
      end: 1 //区域底部到播放器顶部所占播放器高度的比例
    },
    closeDefaultBtn: true, //开启此项后不使用默认提供的弹幕开关,默认使用西瓜播放器提供的开关
    defaultOff: true //开启此项后弹幕不会初始化,默认初始化弹幕
  }
});
  • 配置项: panel
  • 默认值: false
  • 参考值: true | false

弹幕控制面板相关功能:

控制功能内容
屏蔽类型滚动弹幕 顶部弹幕 底部弹幕 彩色弹幕
显示区域弹幕显示区为播放器可视区顶部到底部, 0 1/4屏 1/2屏 3/4屏 全屏
不透明度控制显示弹幕的透明度
弹幕速度通过显示时长控制弹幕速度,慢[15000ms] 中[10000ms] 快[5000ms]
字体大小控制弹幕字体大小, 小[10px] 中[20px] 大[30px]

外挂字幕

播放器支持加载多条WebVTT格式的外挂字幕,并可在播放过程中切换或关闭、打开字幕。外挂字幕格式可参考 WebVTT MDN

另外,可通过textTrackActive配置项修改外挂字幕控件的触发方式(hover或click)。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  textTrack: [
    {
      src: "./textTrack-1.vtt",
      kind: "subtitles",
      label: "字幕1",
      srclang: "zh",
      default: true
    },
    {
      src: "./textTrack-2.vtt",
      kind: "subtitles",
      label: "字幕2",
      srclang: "en",
      default: false
    }
  ],
  textTrackStyle: {
    "background-color": "#ff0",
    "color": "#000",
    "font-size": "26px",
  },
  textTrackActive: 'click'
});
  • 配置项:textTrack
  • 含义:多条字幕信息组成的数组
  • 默认值:[]
参数意义可选值
src字幕文件的URL,必需
kind字幕类型,可选参考
label字幕标签,必需
srclang字幕文本语言,可选zh, en...
default默认字幕true, false
  • 配置项:textTrackStyle
  • 含义:字幕相关CSS样式配置
  • 默认值:{}

  • 配置项:textTrackActive
  • 默认值:'hover'
  • 参考值:'hover' | 'click'

画中画

画中画功能支持用户在浏览网页其它内容时继续以小窗的形式观看视频,同时可以拖拽改变小窗在页面中的fix位置。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  pip: true
});
  • 配置项:pip
  • 默认值:false
  • 参考值:true | false

网页样式全屏

样式全屏功能不会隐藏当前浏览器的标签栏,导航栏,只是在当前页面内部全屏显示。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  cssFullscreen: true
});
  • 配置项:cssFullscreen
  • 默认值:false
  • 参考值:true | false

截图

截图功能支持用户对当前视频播放窗口进行即时截屏,截图尺寸即为当前视频播放窗口的尺寸,截图默认为 .png 格式

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  screenShot: true
})
  • 配置项:screenShot
  • 默认值:false
  • 参考值:true | false

预览本地视频

支持用户在线预览本地视频。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  preview: {
    uploadEl: uploadDom
  }
});
  • 配置项:uploadEl
  • 含义:Dom元素,用于放置上传视频文件的相关控件

进度条特殊点标记

支持在进度条上标出重要的位置。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  progressDot: [{time: 10}, {time: 22}, {time: 56}]
});
  • 配置项:progressDot
  • 含义:标记点所对应的播放时间

支持动态增加/删除标记

player.addProgressDot(time) //添加标记
player.removeProgressDot(time) //删除标记
player.removeAllProgressDot() //删除所有标记

键盘快捷键

可通过该配置项开启键盘快捷键:按 → 键快进10秒, 按 ← 键后退10秒,按 ↑ 键调高音量,按 ↓ 键调低音量,按 space 键切换播放/暂停状态。

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  keyShortcut: 'on'
});
  • 配置项:keyShortcut
  • 默认值:'on'
  • 参考值:'on' | 'off'

插件生效前执行

播放器使用自执行的插件机制,如需要在插件生效前执行某些方法,开发者可将相关方法写在execBeforePluginsCall配置项数组中

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  execBeforePluginsCall: [() => {
    console.log('Execute before plugins call')
  }]
});
  • 配置项:execBeforePluginsCall
  • 默认值:[]

其它交互配置

播放器默认有以下行为:

  1. video触发click事件后视频切换播放/暂停状态,可通过closeVideoClick关闭
  2. video触发dblclick事件后进入/退出全屏,可通过closeVideoDblclick关闭
  3. 移动端下默认video触发touchend事件后视频切换播放/暂停状态,可通过closeVideoTouch关闭
  4. 鼠标移出播放器范围时触发blur事件,可通过closePlayerBlur关闭;另外可通过leavePlayerTime配置项来实现延迟触发blur事件的效果
  5. 鼠标移出播放器控制条范围时触发focus事件,可通过closeControlsBlur关闭
  6. 播放器范围时移动鼠标时触发video focus,可通过closeFocusVideoFocus关闭
  7. 播放器触发play事件时触发video focus,可通过closePlayVideoFocus关闭

这些行为可通过相关配置项来关闭。

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  closeVideoClick: true,
  closeVideoDblclick: true,
  closeVideoTouch: true,
  closePlayerBlur: true,
  closeControlsBlur: true,
  closeFocusVideoFocus: true,
  closePlayVideoFocus: true
});

清晰度切换配置

清晰度插件配置虽然属于内置控件但是比较特殊,不采用传统的配置项而是采用事件驱动的方式。因为我们的清晰度设计更加抽象,不仅支持明确的视频地址列表,还要支持虚拟地址列表,所以采用事件驱动。

另外,可通过definitionActive配置项修改清晰度控件的触发方式(hover或click)。

示例

let player = new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  definitionActive: 'click'
});

player.emit('resourceReady', [{name: '高清', url: 'url1'}, {name: '超清', url: 'url2'}]);
  • 配置项:definitionActive
  • 默认值:'hover'
  • 参考值:'hover' | 'click'

注意

如果不想使用清晰度切换功能,不激活 resourceReady 事件就可以;如果视频地址列表只有一个地址,清晰度切换控件也会自动关闭。

关闭内置控件

xgplayer播放器对于原生video的基本功能进行了优化和封装,如果不想使用xgplayer内置控件,可以通过ignores配置项关闭,使用自己开发的相同功能插件进行替换。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  ignores: ['replay']
});
  • 配置项:ignores
  • 默认值:[]
  • 参考值: ['time', 'definition', 'error', 'fullscreen', 'i18n', 'loading', 'mobile', 'pc', 'play', 'poster', 'progress', 'replay', 'start', 'volume']
参数意义
time当前播放时间/视频时长
definition清晰度切换
error报错提示
fullscreen全屏切换
i18n多语种切换
loading加载提示
mobile手机交互
pc桌面视频交互
play控制条的播放、暂停按钮
poster封面图插件
progress视频进度条
replay重播交互与提示
start初始化播放按钮
volume音量控制

关闭控制条

播放器控制条由播放/暂停、定位、音量、全屏切换等元素组成,开发者可通过controls:false 将其全部关闭。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  controls: false
});
  • 配置项:controls
  • 默认值:true
  • 参考值 true | false

控制条选项配置

选择关闭部分控制条选项可以通过配置controlsList选项实现。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  controlsList: ['nodownload']
});
  • 配置项:controlsList
  • 默认值:['nodownload'],
  • 参考值:['nodownload','nofullscreen','noremoteplayback']

注意

只对原生video有效,对自定义UI请使用ignores选项

播放镜像

开启airplay选项可以将iOS设备上的视频传送到支持airplay的设备上进行播放,具体 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  airplay: false
});
  • 配置项:airplay
  • 默认值:''
  • 参考值:true | false

功能插件开关配置

通过播放器的配置可以实现插件动态开启和关闭,只要在功能插件读取该配置即可。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  pluginRule: ()=>{return true}
});
  • 配置项:pluginRule
  • 默认值:''
  • 参考值:function(){return true|false}

比如:xgplayer-mp4插件想做流量测试,一半用户开启功能,一半用户不开启,就可以通过如下代码实现:

new Player({
  pluginRule:function(){return Math.random()>0.5}
})

国际化

西瓜播放器的文本提示支持多语种显示,目前支持中文、英文、日文。如有更多语种需求请在github中提issue。

import Player from 'xgplayer';

let player=new Player({
  id:'mse',
  url: 'video_url',
  lang: 'en'
});
  • 配置项:lang
  • 默认值:'zh-cn'
  • 参考值:'zh-cn' | 'en' | 'jp'

白名单

手机上video表现各异,自定义UI会有意想不到的情况发生,为了安全起见,播放器在手机上会关掉自定义UI功能,开发者可以通过白名单的方式开启此项功能。whitelist是数组,数组的每项值可以是字符串、正则表达式、函数(箭头函数)均可,字符串和正则表达式都是对navigator.userAgent来判断,函数不限。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  whitelist: ['iPhone OS 9'],
  // whitelist: [(ua)=>{ return /iPhone OS 9/gi.test(ua); }],
  // whitelist: [/iPhone OS 9/gi]
});
  • 配置项:whitelist
  • 默认值:[]
  • 参考值:[字符串,正则,函数]

内联模式

该选项在手机观看时,开启ios和微信的内联模式,配置项:playsinline 知识 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  playsinline: false
});
  • 配置项:playsinline
  • 默认值:false
  • 参考值:true | false

手机调试

要使用该功能,请先在开发者电脑安装 weinre,命令: npm -g install weinre。调试手机的时候,debug选项配置好,然后在命令行开启服务,具体命令页面中会提示。关于weinre知识 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  debug: {
    host:'10.2.106.238',
    port:9090
  }
});
  • 配置项:debug
  • 默认值:{host:'127.0.0.1',port:9090}
  • 参考值:{host:${开发者电脑ip},port:9090}

微信同层播放

同层播放 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-type': 'h5'
});
  • 配置项:x5-video-player-type
  • 默认值:''
  • 参考值:'h5'

微信全屏播放

具体 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-fullscreen': false
});
  • 配置项:x5-video-player-fullscreen
  • 默认值:''
  • 参考值:true | false

微信横竖屏控制

具体 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-orientation': 'portraint'
});
  • 配置项:x5-video-orientation

  • 默认值:''

  • 参考值:'landscape' | 'portraint'

    • 'landscape' 横屏
    • 'portraint' 竖屏

自定义配置

如果自定义插件,想通过播放器初始化的时候传递配置参数进来,可以直接定义。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  customConfig:{
    //
  }
});

在插件内部通过player.config.customConfig拿到配置。其中 player 是插件定义函数都具备的当前播放器实例,customConfig是可以随便定义的,示例只是举例。