保利威文档中心

帮助中心

属性和接口说明

更新时间:2026-01-19 14:30:07

播放器属性

名称 类型 默认值 说明 兼容性:pc 兼容性:mobile
wrap String / HTMLElement / 载入播放器的 DOM 元素,支持传入元素或元素选择器 (仅在第一个元素载入)。
vid String / 云点播平台的视频唯一id。
width Number / String 100% 播放器的宽度,支持像素值和百分比两种方式,如200或100%。
height Number / String / 播放器的高度,支持像素值、百分比和自适应三种方式,如100、40%。
当值为auto或者为空时,会根据视频比例自动计算高度(仅在PC端生效)。
autoplay Boolean / 是否自动播放。
注:目前大多数浏览器都会限制自动播放,该参数可能无效。
loop Boolean false 是否开启循环播放。
forceH5 Boolean / 使用多终端代码时,是否默认使用H5播放器。
注:浏览器不支持H5的情况下还是会使用Flash。
flash Boolean false 是否默认使用Flash播放器。
hideSwitchPlayer Boolean false 是否隐藏H5和Flash播放器的切换按钮。
playsafe String/Function / 播放加密视频所需的授权凭证。如何使用详见:播放加密视频
Function使用:
playsafe: function(vid, next) {
$.ajax({
url: 'token接口',
type: "POST",
data: obj,
}).done(function(res) {
next(res.data.token);
});
},
playsafeUrl String / 获取播放加密视频凭证的接口URL。
与playsafe参数二选一。
disposable Boolean false 生成playsafe token 时若传入了disposable参数那么token是一次有效的,再切换清晰度时会导致播放失败,所以当请求token是传入了该参数可以在调用播放器时设置当前参数为true。
注:需使用playsafe<Function>或者playsafeUrl
sign String / 移动端播放加密视频所需的签名。如何使用详见:播放加密视频
ts Number / 移动播放加密视频需传入的时间戳。
viewerInfo Object / 自定义观众信息。设置后,播放器上报的观看行为日志中会附带观众信息。详见:观众信息设置与统计
video_align String / 播放器内视频画面的对齐方式,默认是居中显示,但可通过该参数来控制。取值:{top,bottom,left,right},分别对应顶部对齐,底部对齐,左对齐和右对齐。
loading_bg_img String / 视频首图的URL。
cover_display String scaleToFill 封面图的显示方式:scaleToFill 铺满,scaleAspectFit 等比自适应,scaleAspectFill 等比铺满。
cover_opacity Number 70 封面图蒙层不透明度,取值范围:[0,100]。
showHd Boolean true 是否显示清晰度选择按钮。
show_rate Number / 允许选择的最高清晰度,取值:{1,2}。值为1时,只显示流畅,值为2时,可选流畅和高清。
showAuto Boolean true 是否显示清晰度选择中的”自动“选项。
df Number - 视频播放默认的清晰度,取值:{0,1,2,3},分别对应自动、流畅、高清、超清。
speed Boolean/Array true 当speed参数值为boolean类型时,代表是否显示倍速切换的按钮。当参数值为数组时,则代表倍速切换的可选速率。可设置速率数量不限制。建议取值范围是(0,3]。PC端默认值为:[2, 1.5, 1.2, 0.5],移动端默认值为:[1, 1.5, 2]。
showLine Boolean true 是否显示线路选择按钮。
volume Number 0.75 默认音量大小,取值范围:(0,1),播放器会记录上一次播放的音量。
allowFullscreen Boolean true 是否允许全屏播放。为false时会隐藏全屏按钮(全屏的API依然可用)。
注:移动端v1不支持 。
fullscreenProxy Boolean false 是否使用全屏代理,为true时点击全屏不会调用全屏的API,会触发window.onFullscreenProxy(vid, toFullscreen)事件,由开发者自行做全屏处理,适合在全屏状态下叠加用户自定义的元素的场景。
full_page_screen Boolean false 是否显示网页全屏按钮。需配置window.onFullPageScreen 事件回调做相应页面全屏处理。
pictureInPicture Boolean false 是否在控制栏显示画中画按钮。
注:仅在播放非加密视频时生效。
screenshot Boolean false 是否显示视频截图按钮。
skinLocation Number 1 播放器控制栏显示位置:0 不显示,1 视频区域内,2 视频区域外。
注:移动端v1使用ban_ui: true代替skinLocation: 0
hideRepeat Boolean false 是否隐藏播放结束后的重播按钮。
ban_seek String off 是否禁止拖拽进度条,取值:{on,off}。
注:Android系统下各厂商浏览器表现不一致,该参数可能不生效。
ban_seek_by_limit_time String off 是否禁止拖拽进度至视频未播放到的位置,取值:{on,off}。为on时只可在已播放过的进度范围内拖拽(向前拖拽)。
cacheLimitTime Boolean false 是否缓存最大已播放时长,搭配ban_seek_by_limit_time使用,设置后观看同一视频可拖动区域为历史最大观看时间。
注:移动端v1不支持 。
banSeekDeviation Number / 设置ban_seek参数后设置当前参数可限制最大seek时间,单位:秒。
ban_preview_video String off 是否禁止鼠标在进度条悬浮时显示预览画面的缩略图,取值{on,off},为on时鼠标在悬浮进度条时不显示预览缩略图
keyboardSeekTime Number 15000 键盘每按一次方向键,视频前进/后退的时间。单位:毫秒。
watchStartTime Number / 播放开始时间,表示视频从第几秒开始播放,参数值需小于视频时长。
watchEndTime Number / 播放结束时间,表示视频播放到第几秒结束,设置该值后,只能在开始时间至结束时间范围内进行进度条的拖拽。
参数值需大于watchStartTime且小于视频时长,如果参数值小于watchStartTime,则watchStartTime失效。
start Number / 截取视频的一部分作为一个独立的视频,如原视频时长60秒,设定start=20后,则视频显示为40秒,并且从原视频的第20秒开始播放。
通常配合end参数一起使用(子视频功能)。
end Number / 截取视频的一部分作为一个独立的视频,如原视频时长60秒,设定start=20,end=50后,则视频显示为30秒,并且从原视频的第20秒开始播放,到原视频的50秒结束播放。
preview Boolean false 是否使用预览模式,到达预览时长后会停止播放,预览时长可在管理后台配置。
previewDuration Number / 预览时长,该参数为可选项,单位:秒,不传且开启preview前提下,默认读取后台配置的预览时长
注:
1、对于非加密视频,系统将按照本参数设置的时长进行预览显示
2、对于加密视频,实际预览时长将根据以下两者中较短的一个确定:实际视频编码长度和本参数设置的时长,建议: 设置值不要超过后台配置的预览时长,以避免异常或限制问题
history_video_duration Number 5 默认时长超过5分钟的视频会开启续播功能,可通过此参数修改,单位:分钟。视频前10秒和最后10秒的播放过程中不会记录续播时间点。
ban_history_time String off 是否禁用续播功能,取值:{on,off},on:禁用续播,off:开启续播。
historyTimeType String local 取值:"local" 或 "remote"。续播记录存储的方式,为local时存储在localStorage,为remote时则存储在polyv服务端。注:配置为remote时,后续的记录不会存储在本地,且两个记录都存在时,优先读远端的值。
preloadDataSize Number 15000 预加载的数据量,会根据实际视频时长和清晰度加载切片数量,取值范围:[500,60000],单位:KB。
注:仅在PC端对HLS视频(加密视频)有效。
preloadDurationLength Number / 视频预加载最大时长,单位:秒。
url String / 第三方的视频资源地址,不可与vid同时设置。
logo Object / 播放器Logo配置参数,详见:播放器Logo
teaser_show Number / 是否播放片头:0 不播放,1 播放。片头可在管理后台进行设置。
teaser_time Number / 片头显示时长。
teaser_url String / 片头URL,视频只支持mp4格式。
teaserSkip Boolean false 是否显示跳过片头的按钮。
注:由于视频层级问题,该参数在部分移动端浏览器下可能不生效。
tail_show Number / 是否播放片尾:0 不播放,1 播放。片尾可在管理后台进行设置。
tail_time Number / 片尾显示时长。
tail_url String / 片尾URL,视频只支持mp4格式。
tailSkip Boolean / 是否显示跳过片尾的按钮。
ban_ad Boolean false 是否禁止播放广告。
ban_ad_time Boolean false 是否隐藏广告倒计时。
adMatter Array / 广告配置参数,详见:广告设置
adSkip Boolean false 是否显示跳过广告的按钮。
rightMenu Array / 播放器右键菜单配置,例如:rightMenu: [{rightName: '右键菜单显示名称', rightUrl: '菜单点击跳转URL', callback: function(){console.log('hi')}},{rightName: '右键菜单二',rightUrl: '', callback: function(){console.log('hello')}}]
lang String zh_CN 播放器语言,支持中英文,取值:{zh_CN,en}。
priorityMode String video 默认使用视频模式还是音频模式,取值:{video,audio}。
注:只有额外转音频的视频才可以切换音视频模式。
videoMode Boolean true 参数值为false时,会启用音频模式。
注:仅在PC端生效,没有额外转音频的也会启用音频模式。
注:移动端v1不支持 。
audioMode Boolean true 是否启用音频模式(仅在源视频支持音频下生效)
is_interaction String on 是否在视频播放时弹出管理后台设置的问答题目。取值:{on,off}。详见:问答弹题功能
ban_record_interaction_right_answer String off 是否禁止播放器缓存问答提交记录,取值:{on,off}。设置为”on“时每次播放视频都需重新答题。
title_of_right_answer_explain String / 问答题目回答正确时的提示文案。
title_of_wrong_answer_explain String / 问答题目回答错误时的提示文案。
pptEnable Boolean false 是否启用课件三分屏播放模式。详见:课件三分屏播放
mainScreen String ppt 课件三分屏播放时的主屏,取值:{ppt,video}
subWidth Number 355 课件三分屏播放时副屏的默认宽度
subHeight Number 200 课件三分屏播放时副屏的默认高度
pptVisible Boolean true 课件三分屏初始化时是否需要显示ppt
srtBackground String / 字幕背景颜色,十六进制。如:'#333333'
srt_caption_txt_size Number 20 字幕字号,取值范围:[20,40],单位:px。
srt_caption_txt_height Number 20 字幕距离播放器底部的高度,单位:px。
srt_caption_base_width Number 1280 字幕字号会随播放器尺寸变化。该值为播放器的基准宽度。
srt_caption_base_height Number 720 字幕字号会随播放器尺寸变化。该值为播放器的基准高度。
showSrt Boolean true 是否开启字幕显示。
defaultSubtitle String - 默认字幕参数,需要与后台设置的字符串一致(字幕文件名称)。
useSingleSubtitleStyle Boolean true 单字幕样式是否响应后台设置
code String / 跑马灯自定义的code值,详见:授权播放和视频跑马灯
marqueeCheck Boolean / 为true时会检测跑马灯是否被篡改,并报016错误。
注:移动端v1不支持 。
ignoreIE Boolean false 是否在IE浏览器(包括360、QQ等浏览器的兼容模式)中禁用HTML5播放器。
player_id String / 播放器ID,设置后会使用对应播放器的设置。
注:该功能需额外开通才能生效。
preventKeyboardEvent Boolean false 是否屏蔽键盘事件,为true时屏蔽。
videoKeyframes Array / 自定义打点设置,设置后将采用该设置的打点信息,后台设置将会忽略,changeVid也可以传入 详见:videoKeyframes
ban_skin_progress Boolean false 是否隐藏播放器进度条。
pause_ad_showonce Bollean false 暂停广告是否只显示一次
webPageFullScreen boolean false 是否开启网页全屏
fullScreenOrientation string 'none' 网页全屏方向,portrait 竖屏, landscape 横屏, none 无效果
appId string / 子账号的appId,子账号的场景需要配置此参数,appId的获取和示例详见: 子账号访问控制管理
authPlayRequestType string 'jsonp' 指定跑马灯接口的请求方式,默认是jsonp的方式。可配置的值:'jsonp','ajax'。值为'ajax'时,使用 AJAX 方式进行请求,适合同域请求或已配置 CORS 的跨域请求。值为'jsonp'时,使用 JSONP 方式进行请求,适合跨域场景。
authPlayRequestHeader Object / 用于指定跑马灯接口请求的附加 HTTP 头信息。可以用于传递认证信息或自定义头。注意: 仅在 authPlayRequestType 设置为 'ajax' 时有效
gesture Object / enableDoubleClick: false/true 是否开启双击事件。如gesture: {enableDoubleClick: false} 关闭双击事件

自定义打点设置

const videoKeyframes = [{
    // 打点出现时间
    keytime: 80,
    // 打点提示内容
    keycontent: 'test111',
    // 打点跳转按钮文案,可选
    btnDesc: 'text',
    // 打点跳转按钮跳转链接,可选
    btnHref: 'https://www.example.com/' 
}]

播放器接口

API需要在播放器初始化完成之后调用,比如:

player.on('s2j_onPlayerInitOver',function(e) {
    player.j2s_seekVideo(100);
 });  

接口列表

名称 参数及类型 返回值及类型 说明 兼容性:pc 兼容性:mobile
j2s_pauseVideo / / 暂停播放。
j2s_resumeVideo / / 恢复播放当前视频。
j2s_stopVideo / / 停止播放当前视频,并显示结束画面。
j2s_seekVideo (Number) / 跳转到某个时刻播放,参数单位为:秒。
j2s_getDuration / Number 获取视频总时长,返回值单位为:秒。
j2s_getCurrentTime / Number 获取视频当前的播放时刻,返回值单位为:
移动端:秒(整数)
PC端:秒(带有小数点,需要自行使用parseInt()进行转换)
getMaxCurrentTime / Number 获取视频播放过的最大时刻,返回值单位为:秒。需要搭配 ban_seek_by_limit_time使用
注:移动端v1不支持 。
j2s_realPlayVideoTime / Number 获取当前视频已播放的时长,不包含广告、片头、暂停、片尾等时间。
j2s_getFlowCount / Number 获取当前视频播放消耗的流量,单位:字节。仅Flash播放器支持。
j2s_setVolume (Number) / 设置视频播放音量,取值范围(0,1)。
j2s_realPlayStatus / Object 获取实时播放状态,返回的json格式字符串包含以下字段:
pid 每次播放行为生成的唯一ID,后台的观看日志也包含该字段
vid 视频ID
playduration 当前播放时长
timestamp 当前时间戳
sign 签名,计算方式请咨询技术支持。
changeVid (Object) / 切换到下一个视频,详见:视频切换
switchBitrate (Number) / 切换清晰度,参数取值{0,1,2,3},分别对应自动、流畅、高清、超清。
getCurrentLevel / (Number) 返回当前清晰度,返回值如上
toggleFullscreen / / 全屏/退出全屏切换
toggleFullPageScreen (String) / 切换网页全屏,前置需要增加webPageFullScreen和fullScreenOrientation参数
网页全屏方向,portrait 竖屏, landscape 横屏,如不传参则使用初始化的方向参数
注:移动端v1不支持 。
changeRepeat (Boolean) / 当参数值为true时,视频结束播放后隐藏重播按钮。
switchMain (String) / 课件三分屏播放时,切换PPT或视频至主屏。取值:{ppt,player}。
setMode (String) / 切换音视频模式,取值:{video,audio}。
注:只有额外转音频的视频才可以切换音视频模式。
getCurrentMode / String 返回当前播放模式,video 视频模式,audio 音频模式。
toFlash / / 切换至Flash播放器,只有PC端H5播放器才可调用该方法。
toHTML5 / / 切换至H5播放器,只有Flash播放器才可调用该方法。
on (String,Funciton) / 绑定监听事件
destroy / / 销毁播放器实例
getScreenshotData(type, encoderOptions); type(可选):用于设置图片格式,默认为 image/png。类型: 'image/png' | 'image/webp' | 'image/jpeg'
encoderOptions(可选):在指定图片格式为 image/jpegimage/webp 的情况下,可以从 0 到 1 的区间内选择图片的质量。如果超出取值范围,将会使用默认值 0.92。其他参数会被忽略。
若接口调用无异常时,返回包含 data URI 的字符串;若接口调用异常,则返回一个对象,对象包含一个属性 error,属性值为异常的 message,类型为 string,对象格式如:{ "error": "xxx" } 获取当前视频画面的截图数据,需设置播放器参数allowGetScreenshotData为true
getVideoInfo / Object 获取视频基本信息,返回对象包含视频分辨率等信息。目前仅支持获取视频分辨率。建议在事件s2j_onPlayerInitOver触发后调用该接口。
changeRate (Number) / 切换倍数,可选值为[2, 1.5, 1.2, 0.5]
getCurrentRate / Number 返回当前播放的倍数

播放器事件

名称 说明 兼容性:pc 兼容性:mobile
s2j_onPlayerInitOver 播放器初始化完毕时触发。播放器提供的方法需要在此事件发生后才可以调用。参数返回vid
s2j_onReadyPlay 在已加载足够的数据能够开始播放视频时触发,参数返回vid
s2j_onPlayStart 视频初次播放时触发,参数返回vid。
s2j_onVideoPlay 视频初次播放或由暂停恢复播放时触发,参数返回vid。
s2j_onVideoPause 视频暂停时触发,参数返回vid。
s2j_onVideoSeek 视频拖拽进度时触发,参数返回开始、结束seek的时间点以及vid。
s2j_onPlayOver 当前视频播放完毕时触发,参数返回vid。
s2j_volumeChange 播放音频发生变化时触发,参数返回vid、变化后的音量。
s2j_onFullScreen 播放器进入全屏时触发,参数返回vid。
注:移动端仅在网页全屏下生效。
s2j_onNormalScreen 播放器退出全屏时触发,参数返回vid。
注:移动端仅在网页全屏下生效。
s2j_onPlayerError 播放出现错误时触发,参数返回vid。
HTML5Load Flash切换至H5播放器时触发。
flashLoad PC端H5播放器切换至Flash播放器时触发。
serverError 发生业务逻辑错误时触发,比如授权验证失败、域名黑白名单验证不通过等错误。参数返回事件名称和错误代码。
onChangeMode 音视频模式切换时触发,参数返回vid,切换后模式以及切换前模式。
onFullscreenProxy 当设置fullscreenProxy参数为true时,点击全屏按钮不会调用全屏api,会触发 window.onFullscreenProxy(vid, toFullscreen) 事件,调用者自行做全屏处理,适合在全屏状态下叠加用户自定义的元素。
onFullPageScreen 当设置full_page_screen为true时,点击网页全屏按钮会触发window.onFullPageScreen(vid, currentStatus) 事件,调用者自行做网页全屏处理。
window.onFullPageScreen = function (vid, currentStatus) {})
adSkip 返回跳过的广告类型,跟设置的广告类型一致。
广告跳过时触发,可用于区分是否为业务上的VIP用户,可否真正跳过广告。
teaserSkip 点击跳过片头时触发。
onTimeupdate 视频播放以及seek时触发,实时返回当前播放进度(单位:秒,带有小数点)
toggleClickPlay 用户通过UI主动播放/暂停时触发,返回值Boolean,表示是否暂停中

注:由于一些历史原因,Web三端播放器(Flash、PC H5和移动端H5)的事件返回参数尚未对齐,上表中以PC H5播放器为准。

通过播放器实例的on方法订阅:

function fn(params) {
    console.log('播放器数据初始化完毕:',params);
}
player.on('s2j_onPlayerInitOver', fn);

通过播放器实例的off方法取消订阅:

player.off('s2j_onPlayerInitOver', fn);
联系客服,在线咨询