tencent cloud

短剧

PDF
聚焦模式
字号
最后更新时间: 2026-02-10 19:36:26

createPlayletPage

该 API 使用方法为 wx.createPlayletPage()
功能说明:初始化播放器,返回播放器对应实例 PlayletPlugin
返回值:PlayletPlugin。

PlayletPlugin

PlayletPlugin 播放器实例,可通过 wx.createPlayletPage() 创建。

.onPageLoad(Function func)

该 API 使用方法为 PlayletPlugin.onPageLoad(Function func)
功能说明:onPageLoad 就是短剧页面的 onLoad 事件,监听短剧页面加载完成事件。
参数及说明:
function func短剧页面加载执行的操作。
回调函数参数:Object res。
属性
类型
说明
playerId
string
播放器 Id
示例代码
playletPlugin.onPageLoad((res) => {
console.log('页面加载完成,播放器ID:', res.playerId);
});

.onPageDestroy(Function func)

该 API 使用方法是 PlayletPlugin.onPageDestroy (Function func)
功能说明:监听短剧页面销毁事件。
参数及说明:
function func短剧页面销毁执行的操作。
回调函数参数:Object res。
属性
类型
说明
playerId
string
播放器 Id
示例代码
playletPlugin.onPageDestory((res) => {
console.log('页面销毁完成,播放器ID:', res.playerId);
});

.getPluginVersion()

该 API 使用方法为 PlayletPlugin.getPluginVersion()
功能说明:获取插件版本信息。
返回值:String 版本信息。

playletPlugin.PlayletManager

功能说明:PlayletManager 是一个类,播放器管理类,用于控制短剧播放的核心功能,可通过 playletPlugin.PlayletManager.getPageManager(playerId) 获取其实例,大部分的接口都在该实例对象上提供,例如 getInfosetPlaylets 等。
参数及说明:number playerId:播放器 ID。
返回值:PlayletManager 播放器管理实例。
示例代码
plugin.onPageLoad((info) => {
const playletManager = plugin.PlayletManager.getPageManager(info.playerId);
console.log('manager',manager);
})
在很多接口中,都可以获取到 playerId,例如 onPageLoad 事件等,然后通过 playerId 可以获取到 PlayletManager 实例。PlayletManager 实例的更多接口介绍如下:

PlayletManager.setPlaylets (Object object)

功能说明:初始化剧集状态。
参数及说明:Object object。
字段名
类型
必填
默认值
说明
id
string
-
剧id
serialNo
number
-
剧集id
title
string
-
剧名
imgUrl
string
''
剧封面图
introduction
string
''
短剧简介
tags
list
[]
短剧标签
playRate
number
1
播放速度
extParam
string
{}
扩展参数
clarity
list
 [
{ clarity: 240 * 426, title: "360P" },
{ clarity: 480 * 852, title: "480P" },
{ clarity: 720 * 1280, title: "720P" },
{ clarity: 1080 * 1920, title: "1080P" }
]
清晰度
defaultClarity
object
{ clarity: 480 * 852, title: "480P" }
默认清晰度
initial-time
number
起始播放时间
data
list
-
剧集状态列表
data 字段定义如下:
字段名
类型
必填
默认值
说明
status
number
 -
播放状态 0:免费;1:已解锁 ;2 :未解锁
videoUrl
string
''
播放地址,付费剧集非必传
coverImg
string
-
封面照片,不设置的时候展示 imgUrl
license-url
string
'' 
播放许可证地址 
Certificate-url
string
''
证书地址
provision-url
string
''
设备预置地址
示例代码
PlayletManager.setPlaylets({
id:"sid", // 剧ID
serialNo:1 // 剧集 ID 从1开始
title:"名字",
imgUrl:"图片地址",
introduction:"短剧简介",
tags: ["友情", "魔幻"],
playRate: 1
extParam:"{{xxx}}"
clarity:[{"360p": 240 * 426},{"480p":480 * 852},"720p":720 * 1280,"1080p":1080 * 1920] // HLS 下才生效
defalutClarity: {"720p":720 * 1280 }// 默认清晰度
'initial-time': 0,
data: [{
license-url:"",
certificate-url:"",
provision-url:"",
status: 0,
videoUrl: "播放URL" // 非免费剧集非必传
coverImg:"封面照片" // 非必传
}]
})

PlayletManager.setLockMenu( Object object )

功能说明:设置剧集解锁时的弹窗,当播放到待解锁的剧集时,弹出该解锁弹窗。
参数及说明:Object object。
字段名
类型
必填
默认值
说明
List
Array<FreeItem>
-
剧集解锁弹窗,最多支持四项
FreeItem字段如下:
字段名
类型
必填
默认值
说明
Title
string
-
解锁操作名
Callback
function
-
具体解锁操作
示例代码

PlayletManager.setLockMenu([
{
title: "看广告解锁",
callback: (data) => {
if (!data.serialNo) {
return;
}
PlayletManager.setCanPlay(data.serailNo, 1)
}
},
{
title: "单集购买",
callback: (data) => {
if (!data.serialNo) {
return;
}
PlayletManager.setCanPlay(data.serailNo, 1)
}
}
])
注意:
PlayletManager.setLockMenu()只是设置解锁弹窗的按钮,并不会控制解锁页面的显示和隐藏,需设置setCanPlay才能真正控制解锁页面的显示和隐藏。

PlayletManager.hideLockMenu()

该 API 的使用方法是 PlayletManager.hideLockMenu()。
功能说明:隐藏锁定菜单。

PlayletManager.setCanPlay(object object)

功能说明:设置剧集解锁状态。
参数及说明: Object object。
字段名
类型
必填
默认值
说明
SerialNo
number
-
剧集 id
Status
number
-
播放状态
VideoUrl
string
-
播放地址
示例代码

const unlockData = [{
serialNo: 6, //集数
status: 1,
videoUrl: videoUrl // 播放地址
}];
PlayletManager.setCanPlay(unlockData);


PlayletManager.onCheckIsCanPlay(Function func)

功能说明:播放到需要解锁的剧集触发此事件。
参数及说明:
function func监听剧集是否可以播放的事件。
示例代码

manager.onCheckIsCanPlay((data) => {
let episodes = [];
if (data.episodes) {
episodes = data.episodes;
}

// 批量检查并设置状态
const results = episodes.map(ep => {
const serialNo = ep.serialNo;
let status;

if (parseInt(serialNo) <= 3) {
// 假设前3集免费
status = 0;
} else {
status = 2;
}
return { serialNo: serialNo, status: status };
});
manager.setCanPlay(results);
});


PlayletManager.onBack(Function func)

功能说明:播放器内左上角返回点击事件。
参数及说明:
function func点击返回的监听函数。
注意:
点击短剧播放界面左上角的返回按钮会触发 PlayletManager.onBack(),返回之后会销毁播放器。

PlayletManager.play()

功能说明:播放剧集。

PlayletManager.onPlay(Function func)

功能说明:监听短剧视频播放事件。
参数及说明:
function func播放短剧事件的监听函数。

PlayletManager.pause()

功能说明:暂停视频。

PlayletManager.onPause(Function func)

功能说明:监听短剧视频暂停事件。
参数及说明:
function func暂停短剧播放事件的监听函数。

PlayletManager.onError(Function func)

功能说明:监听播放失败事件。
参数及说明:
function func播放短剧失败的监听函数。
回调函数参数:
属性
类型
说明
eventId
number
播放错误事件类型

PlayletManager.destroy()

功能说明:销毁短剧播放器。

PlayletManager.getInfo()

功能说明:获取当前剧集信息,返回 Object 字段定义如下。
属性
类型
说明
serialNo
number
剧集 id
playerId
string
播放器 id
exParam
string
分享扩展参数
duration
string
当前剧集的总时长
playtime
string
当前播放到的时间

PlayletManager.onCustomEvent(Function func)

功能说明:接收原生播放器状态的事件,包括用户切换剧集,切换播放速度等。
参数及说明:
Function func监听用户操作原生播放器的函数。
回调函数参数:
属性
类型
说明
EventType
string

'CHANGE_SERIAL':切换剧集, 例如 { slideType: 1 }。slideType 为1表示播放结束(不区分是否完播)自动切换,2表示手势滑动切换,3表示从选集弹窗切换。
'CHANGE_SPEED':切换播放速度 ,例如{ source: 1, speedType: 1.5 },返回 source(目前固定为1),speedType 为当前播放速度。
'CHANGE_CLARITY':切换播放清晰度 ,返回当前播放清晰度 clarity。
示例代码
manager.onCustomEvent((data) => {
if (data.eventType === 'CHANGE_CLARITY') {
console.log('用户切换清晰度:', data.clarity);
}
if (data.eventType === 'CHANGE_SERIAL') {
console.log('用户切换视频:', data.slideType);
}
if (data.eventType === 'CHANGE_SPEED') {
console.log('用户改变播放速度:', data.speedType, data.source);
}
});

PlayletManager.onDataReport (Function func)

功能说明:开发者可通过此方法注册回调函数获得数据上报相关的回调,其中 event 表示上报的点,event 是个枚举值,具体的取值如下。 每个上报事件,都会有一些公共的字段会带回给开发者。
字段名
描述
playerId
播放器 id
extParam
分享扩展参数
serialNo
当前剧集索引,从1开始计数
playTime
当前播放到的时间
duration
当前剧集的总时长
totalCount
当前剧集总集数
每个事件还有自己额外的一些字段,具体如下:
字段名
描述
额外字段说明
LOAD
进入播放器页面
-
SHOW
播放器页面 show
-
START_PLAY
开始播放
-
UNLOAD_OR_HIDE
离开页面或者退到后台
例如 { type: 1 }。type为1表示 Unload,为 2 表示 hide;
VIDEO_PLAY
play 事件
-
VIDEO_TIME_UPDATE
timeupdate 事件
参数参考 video 组件的 timeupdate 事件
VIDEO_END
播放视频结束
-

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈