tencent cloud

腾讯云超级应用服务

短剧

Download
聚焦模式
字号
最后更新时间: 2026-07-28 15:57:43

createPlayletPage

该 API 使用方法为 wx.createPlayletPage()
功能说明:初始化播放器,返回播放器对应实例 PlayletPlugin
返回值:PlayletPlugin。
const plugin = wx.createPlayletPage({
fail: (res) => {
console.error('【createPlayletPage】创建失败:', res.errMsg);
}
});
注意:
受小程序页面栈上限(10 层)限制,业务页面 + 已打开的短剧页面总数需 ≤ 10。当打开剧集导致页面总数超限时,wx.createPlayletPage()fail 回调会收到错误:createPlayletPage:fail page stack is full, please navigate back first

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.onPageDestroy((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', playletManager);
})
在很多接口中,都可以获取到 playerId,例如 onPageLoad 事件等,然后通过 playerId 可以获取到 PlayletManager 实例。PlayletManager 实例的更多接口介绍如下:

PlayletManager.setPlaylets (Object object)

功能说明:初始化剧集状态。
参数及说明:Object object。
字段名
类型
必填
默认值
说明
id
String
-
短剧 id
serialNo
Number
-
剧集 id
title
String
-
剧名
imgUrl
String
''
剧封面图
introduction
String
''
短剧简介
tags
Array
[]
短剧标签
playRate
Number
1
播放速度
extParam
String
{}
扩展参数
clarity
Array
 [
{ 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
Array
-
剧集状态列表
interaction
Object
-
短剧级互动数据(含收藏 / 转发),详见下表
interaction(短剧级互动数据):
字段名
类型
必填
默认值
说明
interaction.favorite.enabled
Boolean
-
是否显示收藏按钮,默认 false
interaction.favorite.isFavorited
Boolean
-
当前是否已收藏
interaction.favorite.count
String
-
收藏数文案,业务侧自行 format(如 "1.2w")
interaction.share.enabled
Boolean
-
是否显示转发按钮
interaction.share.count
String
-
短剧级的转发总数(字符串)
interaction.share.title
String
-
分享卡片标题
interaction.share.path
String
-
分享跳转路径
interaction.share.imageUrl
String
-
自定义分享图,支持本地 / 代码包 / 网络图片
data(剧集数组,每一项对应每一集):
字段名
类型
必填
默认值
说明
status
Number
 -
播放状态。0:免费;1:已解锁;2:未解锁
videoUrl
String
''
播放地址,付费剧集非必传
coverImg
String
-
封面照片,不设置的时候展示 imgUrl
license-url
String
'' 
播放许可证地址 
Certificate-url
String
''
证书地址
provision-url
String
''
设备预置地址
interaction
Object
-
剧集级互动数据(含点赞),详见下表
data[].interaction(剧集级互动数据):
字段名
类型
必填
默认值
说明
data[].interaction.like.enabled
Boolean
-
是否显示点赞按钮
data[].interaction.like.isLiked
Boolean
-
该集点赞初始态
data[].interaction.like.count
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 下才生效
defaultClarity: {"720p": 720 * 1280}, // 默认清晰度
'initial-time': 0,
interaction: { // 短剧级互动数据(收藏 / 转发)
favorite: { enabled: true, isFavorited: false, count: "1.2w" },
share: { enabled: true, count: "567", title: "分享标题", path: "pages/xxx/xxx?id=1", imageUrl: "" }
},
data: [{
license-url:"",
certificate-url:"",
provision-url:"",
status: 0,
videoUrl: "播放URL", // 非免费剧集非必传
coverImg:"封面照片", // 非必传
interaction: { // 剧集级互动数据(点赞)
like: { enabled: true, isLiked: false, count: "2.2w" }
},
}]
})

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.serialNo, 1)
}
},
{
title: "单集购买",
callback: (data) => {
if (!data.serialNo) {
return;
}
PlayletManager.setCanPlay(data.serialNo, 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: 'default_video_url', // 播放地址
}];
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, 10) <= 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
播放视频结束
-

PlayletManager.setInteractionState (Object object)

该 API 使用方法为 PlayletManager.setInteractionState({...})
功能说明:业务侧自行处理点赞/收藏/转发的业务逻辑后,调用此 API 同步 UI 状态。
调用示例:
manager.setInteractionState({
serialNo: 1, // 集编号:type=like 必填;type=favorite/share 非必填
type: 'like', // 互动类型:'like' | 'favorite' | 'share'
isActive: true, // 是否选中(type=share 时可不填)
count: "1.2w" // 数量文案,字符串,业务侧自行 format
})
参数说明:
字段
类型
必填
说明
serialNo
Number
仅 like 必填
集编号
type
String
'like' / 'favorite' / 'share'
isActive
Boolean
share 可不填
是否选中
count
String
数字文案

PlayletManager.onLikeClick(Function func)

该 API 使用方法为 PlayletManager.onLikeClick(func)
功能说明:监听用户点击点赞按钮的事件。业务侧拿到回调后,自行处理点赞逻辑(落库/打点),再用 setInteractionState 把最新状态推回组件。
调用示例:
manager.onLikeClick((args) => {
// args.playerId 当前播放器 id
// args.id 剧 id
// args.serialNo 集编号
// args.currentState 点击前的状态(false 表示原来未点赞)
// args.extParam setPlaylets 时透传的 extParam
})

PlayletManager.onFavoriteClick(Function func)

该 API 使用方法为 PlayletManager.onFavoriteClick(func)
功能说明:监听用户点击收藏按钮的事件。收藏是短剧级动作(非剧集级),回调里没有 serialNo。
调用示例:
manager.onFavoriteClick((args) => {
// args.playerId
// args.id
// args.currentState 点击前的收藏状态
// args.extParam
})

PlayletManager.onShareClick(Function func)

该 API 使用方法为 PlayletManager.onShareClick(func)
功能说明:监听用户点击转发按钮的事件。
调用示例:
manager.onShareClick((args) => {
// args.playerId
// args.id
// args.serialNo
// args.extParam
})

PlayletManager.setActivityInfo (Object object)

该 API 使用方法为 PlayletManager.setActivityInfo({logo})
功能说明:在播放页指定位置展示一个 logo 入口,常用于活动跳转、运营位露出。
调用示例:
manager.setActivityInfo({
logo: 'https://miniprogram.tcsas-superapp.com/xxx/xxx.png'
})
参数说明:
字段
类型
必填
说明
logo
String
运营位 logo 图片 URL(建议正方形 PNG,尺寸 24 × 24)

PlayletManager.onSetActivityInfo(Function func)

该 API 使用方法为 PlayletManager.onSetActivityInfo(func)
功能说明:监听用户点击运营位 logo 时触发,业务侧可在此打开活动弹层 / 跳转 / 开启自定义区域。
调用示例:
manager.onSetActivityInfo((args) => {
// 用户点击运营位 logo 时触发
})

PlayletManager.updateOpenArea (Object object)

该 API 使用方法为 PlayletManager.updateOpenArea({...})
功能说明:在播放器左侧塞入一块自定义组件区域,做活动卡片、签到、广告位等。
调用示例:
manager.updateOpenArea({
showLeft: true, // 是否展示左侧自定义区域
playerId: '<可选>', // 指定播放器 id
serialNo: 1, // 当前集编号
ext: JSON.stringify({ dramaId: 1 }) // 透传给自定义组件的额外数据(字符串)
})
参数说明:
字段
类型
必填
说明
showLeft
Boolean
true 展示,false 收起
playerId
String
多播放器场景下指定具体实例
serialNo
Number
当前集编号,会作为 prop 传给组件
ext
String
自定义透传数据,建议 JSON.stringify 后传入
返回值:Boolean — true / false 表示是否调用成功。

自定义组件接入说明

业务侧需在小程序内提供一个标准 Component,由插件挂载到自定义区域。组件接收以下 props:
字段
类型
来源
ext
String
updateOpenArea({ ext }) 透传
playerId
String
当前播放器 id
serialNo
Number
当前集编号
并支持通过 triggerEvent('close') 通知插件关闭自定义区域。
注意:
自定义组件必须使用 cover-view / cover-image 等原生组件作为容器,否则会被视频层覆盖、无法正常显示与点击。常规 view / image 标签在播放器层之上会被遮挡。
自定义组件最小示例 - JS(pages/components/open-area-left/open-area-left.js)
Component({
properties: {
ext: { type: String, value: '' },
playerId: { type: String, value: '' },
serialNo: { type: Number, value: 0 }
},
methods: {
onJoinTap() {
// 业务逻辑:跳转活动页 / 打开弹层等
},
onCloseTap() {
this.triggerEvent('close'); // 通知插件关闭自定义区域
}
}
});
自定义组件最小示例 - WXML(pages/components/open-area-left/open-area-left.wxml)
<cover-view style="display: flex; flex-direction: column; align-items: center; justify-content: center; width: 100%; height: 100%;">

<!-- 活动 Banner 图 -->
<cover-image
src="https://miniprogram.tcsas-superapp.com/hackthon/upload_1755932019262.jpg"
style="width: 500rpx; height: 500rpx; border-radius: 16rpx;"
/>

<!-- 活动标题 -->
<cover-view style="margin-top: 30rpx; font-size: 36rpx; font-weight: bold; color: #fff;">
限时福利活动
</cover-view>

<!-- 活动描述 -->
<cover-view style="margin-top: 16rpx; font-size: 26rpx; color: rgba(255,255,255,0.8); text-align: center;">
观看广告免费解锁全部剧集
</cover-view>

<!-- 按钮区域 -->
<cover-view style="display: flex; flex-direction: row; margin-top: 40rpx; width: 100%; justify-content: center;">
<cover-view
style="width: 200rpx; height: 100rpx; line-height: 80rpx; font-size: 28rpx; background: #FF6B6B; color: #fff; border-radius: 36rpx; text-align: center; margin-right: 20rpx;"
bindtap="onJoinTap"
>立即参与</cover-view>
<cover-view
style="width: 200rpx; height: 100rpx; line-height: 80rpx; font-size: 28rpx; background: rgba(255,255,255,0.3); color: #fff; border-radius: 36rpx; text-align: center;"
bindtap="onCloseTap"
>关闭</cover-view>
</cover-view>

</cover-view>

PlayletManager.setRecommend (Array list)

该 API 使用方法为 PlayletManager.setRecommend([...])
功能说明:设置播放器内的推荐位列表,用户可在播放过程中点击切换至其它剧集。
调用示例:
manager.setRecommend([
{ id: 'drama_2', name: 'Palace Drama: Harem Legend', imgUrl: 'https://example.com/cover.jpg' },
{ id: 'drama_3', name: 'Mystery: Escape Room', imgUrl: 'https://example.com/cover.jpg' }
])
参数说明:
字段
类型
必填
说明
id
String
推荐项唯一标识,回调时原样回传
name
String
推荐剧名
imgUrl
String
推荐封面图 URL

PlayletManager.onRecommendItemClick(Function func)

该 API 使用方法为 PlayletManager.onRecommendItemClick(func)
功能说明:监听用户点击推荐项。业务侧可根据 id 切换或新开播放器。
调用示例:
manager.onRecommendItemClick((args) => {
// args.id — 用户点击的推荐项 id(与 setRecommend 中传入的 id 一致)
})


帮助和支持

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

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

文档反馈