# 播放器 JavaScript SDK

当前SDK支持播放视频、音频、Word/PDF文档、静态PPT、动画PPT 5种类型的资源播放。

# 安装

# `<script>`异步引入

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>气球云资源播放 Demo</title>
  <script type="text/javascript">
    (function (url) {
      window.QiQiuYun || (window.QiQiuYun = {});
      var firstScriptTag = document.getElementsByTagName('script')[0];
      var script = document.createElement('script');
      // url 中加入了 时间戳参数是为了确保能获取最新的SDK
      script.src = url + '?' + ~~(Date.now() / 1000 / 60);
      firstScriptTag.parentNode.insertBefore(script, firstScriptTag);
    })('//service-cdn.qiqiuyun.net/js-sdk-v2/sdk-v1.js');
  </script>
</head>
<body>
<!-- 用于初始化的DOM节点 -->
<div id="cloud-player"></div>
<script type="text/javascript">
  // 由于是异步载入script需要注册回调函数
  QiQiuYun.onPlayerSDKReady = function (SDK) {
    var player = new QiQiuYun.Player({
      id: 'cloud-player',  // 用于初始化的DOM节点ID
      resNo: '<resource no>', // 播放资源编号
      token: '<token>' // 播放令牌由后端SDK生成
    });
  }
</script>
</body>
</html>

# 使用`load-script`引入（适用于vue）

import load from 'load-script';

// url 中加入了 时间戳参数是为了确保能获取最新的SDK
load('//service-cdn.qiqiuyun.net/js-sdk-v2/sdk-v1.js?' + ~~(Date.now() / 1000 / 60), (err) => {
  if (err) {
    throw err;
  }
  new window.QiQiuYun.Player({
    id: 'cloud-player',  // 用于初始化的DOM节点ID
    resNo: '<resource no>', // 播放资源编号
    token: '<token>', // 播放令牌由后端SDK生成
  });
});

# 资源对应播放器

播放器类型	可播放资源	UseType(播放器中使用的type)
音频播放器	`音频`	`audio`
视频播放器	`视频`	`video`
图片播放器	`图片` `图片化文档/PPT`	`ppt-img`
文档播放器	`PDF` `Word` `Excel`	`doc`

# API

# Attributes

# 通用参数

适用于所有资源类型

参数	说明	类型	是否必须	默认值
id	页面中用于初始化播放器的DOM元素的ID	string	是	-
resNo	云资源唯一编号	string	是	-
token	云资源播放令牌	string	是	-
disableControlBar	隐藏控制条	boolean	否	false
user	观看资源的用户信息{id, name}	object	否	{}

# 视频播放器参数（video-player）

参数	说明	类型	是否必须	默认值
rememberLastPos	设置是否跳转至上次观看位置继续	boolean	否	-
initPos	设置资源播放的初始位置，单位`s`	number	否	undefined
autoplay	播放器初始化完成后是否自动播放 (根据《浏览器相关限制》 (opens new window)用户须手动触发)	boolean	否	false
poster	资源封面图片	string	否	undefined
watermark	水印{file, pos, width, height}	object	否	{}
fingerprint	指纹{html, duration, frequency}	object	否	{}
textTrack	字幕	Array<TextTrackItem>	否	undefined
playbackRates	倍速播放，每一项即为倍速参数	Array<Number \| Float>	否	undefined
controlBar	控制条参数	object	否	{}
hideControlBarTime	无动作延迟隐藏控制条，单位`ms` (设置为0表示永不隐藏)	number	否	2000
disableSeek	禁止跳转，可选值`forward` `backward` `none`	enum	否	none
disableHotkeys	禁用键盘热键控制	boolean	否	false
defaultPlaybackRate	默认倍速（仅能设置 playbackRates 参数中有的倍速）	number	否	1
translation	自定义语言（播放器默认根据浏览器语言自动调整）	object	否	{}
exam	弹题	object	否	{}

# 图片播放器参数（img-player）

同时也是ppt图片模式播放器

参数	说明	类型	是否必须	默认值
rememberLastPos	设置是否跳转至上次观看位置继续	boolean	否	-
initPos	设置资源播放的初始位置，单位`页`	number	否	undefined
pageLimit	播放页数限制（试看功能），单位`页` (设置0表示不限制)	number	否	0

# 文档播放器参数（doc-player）

参数	说明	类型	是否必须	默认值
rememberLastPos	设置是否跳转至上次观看位置继续	boolean	否	-
initPos	设置资源播放的初始位置，单位`页`	number	否	undefined
pageLimit	播放页数限制（试看功能），单位`页` (设置0表示不限制)	number	否	0

# PPT播放器参数（slide-player）

参数	说明	类型	是否必须	默认值
rememberLastPos	设置是否跳转至上次观看位置继续	boolean	否	-
initPos	设置资源播放的初始位置，单位`页`	number	否	undefined
pageLimit	播放页数限制（试看功能），单位`页` (设置0表示不限制)	number	否	0

# Events

可通过 player.on(String: eventName, Function: callback) 方法可监听事件。例如：

player.on('eventName', function(event) {
  console.log(event);
  // 通用数据信息
  /*{
    canPlayType: ['img', 'slide'],  // 当前资源可播放类型,按播放优先级从高至低排列
    playerType: 'img',                // 当前播放器类型
    metas: {                       // 当前play接口获取的信息
      args: {
        image: [],
        animation: {}
      }
    },
    resNo: 'resourseNo',          // 云资源唯一编号
  }*/
})

# 通用事件

事件名	说明	回调参数
resourceError	当获取资源异常时	error: 错误相关信息
ready	播放器实例化完成	event: 通用信息
end	播放到末尾时	event: 通用信息

# 视频播放器（video-player）

事件名	说明	回调参数
timeupdate	每个xx毫秒触发	event: {timestamp: 当前时间, duration: 总时长}
play	开始播放时触发	event: 通用信息
pause	暂停播放时触发	event: 通用信息
ratechange	当倍速改变时触发	event: {rate: 当前倍速}

# 图片播放器（img-player）

事件名	说明	回调参数
pagechanged	页面发生变化时触发	event: {page: 当前页码, total: 总页数}

# 文档播放器（doc-player）

事件名	说明	回调参数
pagechanged	页面发生变化时触发	event: {page: 当前页码, total: 总页数}

# PPT播放器（slide-player）

事件名	说明	回调参数
pagechanged	页面发生变化时触发	event: {page: 当前页码, total: 总页数}

# Methods

# 通用方法

方法名	说明	返回值
destory()	销毁播放器实例	-
requestFullscreen() `已废弃`	进入全屏	-

# 视频播放器(video-player)

方法名	说明	返回值
play()	开始播放，受到《非用户手动播放限制》 (opens new window)	-
pause()	暂停播放	-
getCurrentTime()	获取当前播放时间	当前播放时间，单位`ms`
setCurrentTime(time: number(单位: `ms`))	设置当前播放时间	当前播放时间，单位`ms`
setExam(exam: object)	设置弹题	-
openModal(options: object)	打开模态框	-
closeModal()	关闭模态框	-
setControlOptions(controlOptions: object)	调整控制条配置	-
setPlaybackRate(rate: number)	控制倍速	-
setNightMode()	夜间模式	-

# 图片播放器(img-player)

方法名	说明	返回值
prevPage()	上一页	-
nextPage()	下一页	-
setCurrentPage(page: number)	设置当前播放页码	-

# 文档播放器(doc-player)

方法名	说明	返回值
prevPage()	上一页	-
nextPage()	下一页	-
setCurrentPage(page: number)	设置当前播放页码	-

# PPT播放器(slide-player)

方法名	说明	返回值
prevPage()	上一页	-
nextPage()	下一页	-
setCurrentPage(page: number)	设置当前播放页码	-
prevStep()	播放上一个动画效果	-
nextStep()	播放下一个动画效果	-

#

# 代码演示

# 属性配置

# 禁止跳转(disableSeek)

const player = new QiQiuYun.Player({
  disableSeek: 'backwoard'
})

disableSeek枚举类型

类型	描述
forward	禁用前跳，即时间线增长方向跳跃
backward	禁用后跳，即时间线减小方向跳跃
none	取消禁用跳转

# 视频水印(watermark)

const player = new QiQiuYun.Player({
  watermark: {
    file: 'http://www.example.com/watermark.png',
    pos: 'top.right',
  }
})

参数	类型	描述
file	String	水印文件资源地址
pos	Enum	水印放置位置，默认值: `top.left`,可选: `top.left`, `top.right`, `bottom.right`, `bottom.left`, `center`
width	Number	水印容器宽度单位: px，水印会按照原比例在限制的宽高内最大比例显示(默认水印宽150像素)
height	Number	水印容器高度单位: px，同上

# 视频指纹(fingerprint)

const player = new QiQiuYun.Player({
  fingerprint: {
    html: '<div style="color: red;font-size: 26px;">你好</div>',
    duration: 1000,
    frequency: 1000,
  }
})

fingerprint相关参数

参数	类型	描述
html	String	HTML 片段字符串(支持Dom元素插入)
duration	Number	指纹显示持续时间，默认值: 2000(毫秒)
frequency	Number	指纹显示间隔时间，默认值: 3000(毫秒)

# 视频字幕(textTrack)

const player = new QiQiuYun.Player({
  textTrack: [{
    label: '字幕一',
    src: 'http://www.example.com/text-track1.vtt',
    default: true
  }, {
    label: '字幕二',
    src: 'http://www.example.com/text-track2.vtt'
  }]
})

TextTrackItem 相关参数

参数	类型	描述
label	string	字幕标签。（必传）
src	string	字幕文件地址。（必传）
default	boolean	是否设置为当前选中的字幕

# 倍速播放(playbackRates)

const player = new QiQiuYun.Player({
  playbackRates: [1, 1.25, 1.5]
})

# 控制条(controlBar)

const player = new QiQiuYun.Player({
  controlBar: {
    disableVolumeButton: true,
  },
})

controlBar相关参数

参数	类型	描述
disableVolumeButton	boolean	隐藏音量
disablePlaybackButton	boolean	隐藏回跳5秒按钮
disableResolutionSwitcher	boolean	隐藏清晰度切换按钮
disableProgressBar	boolean	禁用进度条拖动

# 自定义语言(translation)

const player = new QiQiuYun.Player({
    translation: {
	    // 浏览器语言环境 如： zh-CN (国内浏览器默认), en, zh-TW, uk等。
	    'zh-CN': {
	      'Play': '播放', // Play文案对应的自定义文案
	    },
	    'en': {
	      'Play': 'play', // Play文案对应的自定义文案
	    },
	  },
})

中文语言包下(zh-CN)的默认文案：

{
  "Play": "播放",
  "Pause": "暂停",
  "Current Time": "当前时间",
  "Duration Time": "时长",
  "Remaining Time": "剩余时间",
  "Stream Type": "媒体流类型",
  "LIVE": "直播",
  "Loaded": "加载完毕",
  "Progress": "进度",
  "Fullscreen": "全屏",
  "Non-Fullscreen": "退出全屏",
  "Mute": "静音",
  "Unmute": "取消静音",
  "Playback Rate": "播放码率",
  "Subtitles": "字幕",
  "subtitles off": "字幕关闭",
  "Captions": "内嵌字幕",
  "captions off": "关闭字幕",
  "Chapters": "节目段落",
  "You aborted the media playback": "视频播放被终止",
  "A network error caused the media download to fail part-way.": "网络错误导致视频下载中途失败。",
  "The media could not be loaded, either because the server or network failed or because the format is not supported.": "出了点小状况，您可以尝试联系客服...",
  "The media playback was aborted due to a corruption problem or because the media used features your browser did not support.": "由于视频文件损坏或是该视频使用了你的浏览器不支持的功能，播放终止。",
  "No compatible source was found for this media.": "无法找到此视频兼容的源。",
  "The media is encrypted and we do not have the keys to decrypt it.": "视频已加密，无法解密。",
  "SHD": "超清",
  "HD": "高清",
  "SD": "标清",
  "Auto": "自动"
}

# 视频弹题(exam)

const popupExam = {
  config: {
    mode: 'strict', // Enum('strict', 'middle', 'loose');弹题的模式：严格，中等，松散。
  },
  questions: [
    // 单选题
    {
      time: 5, // Int 此题目弹出的时间，单位秒
      type: 'choice', // Enum('choice', 'multiChoice', 'judge', 'completion', 'uncertainChoice'); 此题目的类型：单选，多选，判断，填空，不定项选择。
      question: '<p>中国的首都是那里？</p>', // 问题
      options: [  // 选项
        {key: 'A', val: '北京'},
        {key: 'B', val: '南京'},
        {key: 'C', val: '东京'},
        {key: 'D', val: '西京'}
      ],
      answer: ['A'], // 正确答案
      analysis: '解析', // 题目解析
      beforeAnswerTip: {
        type: 'warning',
        text: '温馨提示：每一道弹题答分都将计入该课程总分。'
      },
    },
    // 判断题
    {
      time: 20,
      type: 'judge',
      question: '中国的首都是北京',
      answer: ['T'],
      analysis: '！！！'
    },
    // 填空题
    // 一道填空题的配置。每个填空的答案可有多个，只要答对其中一个就算那个空回答正确。
    // 答案在题干中使用`[[]]`包裹，多个答案之间采用`|`分割。
    {
      time: 25,
      type: 'completion',
      question: '中国的首都是[[北京|Beijing]]',
      analysis: '中国的首都是北京'
    },
  ]
}
const player = new QiQiuYun.Player({
  exam: popupExam
})

# 方法相关演示

# 设置弹题(setExam)

const popupExam = {
  config: {
    mode: 'strict', // Enum('strict', 'middle', 'loose');弹题的模式：严格，中等，松散。
  },
  questions: [
    // 单选题
    {
      time: 5, // Int 此题目弹出的时间，单位秒
      type: 'choice', // Enum('choice', 'multiChoice', 'judge', 'completion', 'uncertainChoice'); 此题目的类型：单选，多选，判断，填空，不定项选择。
      question: '<p>中国的首都是那里？</p>', // 问题
      options: [  // 选项
        {key: 'A', val: '北京'},
        {key: 'B', val: '南京'},
        {key: 'C', val: '东京'},
        {key: 'D', val: '西京'}
      ],
      answer: ['A'], // 正确答案
      analysis: '解析', // 题目解析
      beforeAnswerTip: {
        type: 'warning',
        text: '温馨提示：每一道弹题答分都将计入该课程总分。'
      },
    },
    // 判断题
    {
      time: 20,
      type: 'judge',
      question: '中国的首都是北京',
      answer: ['T'],
      analysis: '！！！'
    },
    // 填空题
    // 一道填空题的配置。每个填空的答案可有多个，只要答对其中一个就算那个空回答正确。
    // 答案在题干中使用`[[]]`包裹，多个答案之间采用`|`分割。
    {
      time: 25,
      type: 'completion',
      question: '中国的首都是[[北京|Beijing]]',
      analysis: '中国的首都是北京'
    },
  ]
}
player.setExam(popupExam)

# 打开模态框 openModal(modalOptions)

player.openModal({
  content:'<div>text</div>',
  height: 236,
  width: 123,
  closable: true,
  timeout: 5000
})

modalOptions 相关参数

参数	类型	描述	默认值	默认值
content	string \| html	内容	否	''
height	number	高度，单位`px`	否	500px
width	number	宽度，单位`px`	否	300px
closeable	boolean	允许主动关闭（当false时timeout为5000）	否	true
timeout	number	自动关闭时间，单位`ms`（0表示不自动关闭）	否	0

# 播放控制配置项 setControlOptions(controlOptions)

// 设置水印倍率大小
player.setControlOptions({
  target: ['watermark'],
  map: {
    rate: 0.5
  }
});

// 设置禁用控制条
player.setControlOptions({
  target: ['controlBar', 'progressControl', 'seekBar'],
  map: {
    disableProgress: true
  }
});

← 播放播放器 Android SDK →