屬性與介面說明
更新時間：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。 |
自訂打點設定
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,Function) | / | 綁定監聽事件 | ✔ | ✔ |
| destroy | / | / | 銷毀播放器實例 | ✔ | ✔ |
| getScreenshotData(type, encoderOptions); | type（可選）：用於設定圖片格式，預設為 image/png。類型: 'image/png' | 'image/webp' | 'image/jpeg'encoderOptions（可選）：在指定圖片格式為 image/jpeg 或 image/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);
