hyExt.stream.createWB
- 创建白板
- 引入版本 1.10.0
- 适用终端
- 虎牙直播助手-iOS：4.9.0
- 虎牙直播助手-安卓：4.9.0
- 虎牙直播PC客户端-主播侧：4.16.1.0
课前准备
本文将会展示创建白板sdk的基本使用，为了能够更好地理解本文，阅读前请确保充分理解了主播端白板中的相关概念。
下图展示了创建白板时的传参相对于小程序面板和视频区位置的关系。你可以在理解此图示的基础上，再结合在项目中调整不同传参值来观察每次创建的白板大小位置变化，从而更好的理解每个参数的实际意义。
其中：
type白板类型的取值范围为：
| 值 | 说明 |
|---|---|
"EXTRA" | 独立白板，白板与调用者（PC主播端）共用相同的代码，但有着完全分割开的数据，类似组件复用。具体请参考主播端白板 |
"NORMAL" | 普通白板，相当于是小程序面板在视频中的投影，白板和调用者（PC主播端）共用一套数据。 |
"EXE" | EXE白板，类似于普通白板，参考外部EXE能力的使用。 |
wbId：白板id，每次创建白板时小程序会自动设置一个wbId，同时开发者也需要手动设置下述的wbName标识。一个wbId只能有一个相对应的wbName，而同一个wbName可作为多次创建的不同白板wbId的标识。wbName：业务传入的白板标识，必传值。作为下述force参数相对推流出去的界面位置记录的标识，也作为hyExt.stream.updateWB（更新白板）、hyExt.stream.onWBLayoutChange （监听白板布局变化消息）两个sdk的必传参数值。force：忽略记忆参数，可选值。不传此参数或传参值为false时效果相同，重新创建白板时小程序会按照上一次相同wbName记录的相对推流出去的界面位置进行投影；传参值为true时，小程序会清除上一次相同
wbName记录的相对推流出去的界面位置，严格按照新设置的offsetX和offseY的相对推流出去的界面位置进行投影。param：初始化参数（独立白板专用），可选值。意义为其他业务需要的传参值。
注意：
完整的创建白板使用流程可能涉及多个sdk，包含：创建白板，获取初始化参数，监听发往白板的数据，发送数据给白板，删除白板等sdk。
若创建的是独立白板，因为独立白板数据和主播端数据是分开的，就需要根据hyExt.env.getInitialParam（获取初始参数）中的返回数据wb=1在白板中判断此时为独立白板环境。只有在独立白板环境下才能调用hyExt.stream.onExtraWhiteBoardMessage（监听发往白板的数据）和hyExt.stream.sendToExtraWhiteBoard （发送数据给白板）sdk，以及对页面进行条件渲染让白板渲染出和主播端完全不一样的效果。这些效果在普通白板和EXE白板环境下都无法正常实现。接口签名
declare namespace hyExt {
module stream {
/**
* 创建白板
* @param params 输入参数
*/
function createWB(params: CreateWBReq): Promise<WhiteBoardInfo>
}
/**
* 创建白板参数
*/
type CreateWBReq = {
/**
* 白板类型；取值说明:
* EXTRA 独立白板;
* EXE EXE白板;
* NORMAL 普通白板;
*/
type: "EXTRA" | "EXE" | "NORMAL"
/**
* 业务传入的白板标识
*/
wbName: string
/**
* 相对推流出去的界面左侧的偏移量（单位是像素）
*/
offsetX: number
/**
* 相对推流出去的界面顶部的偏移量（单位是像素）
*/
offsetY: number
/**
* 推流出去的界面里白板图层占的宽度（单位是像素）
*/
canvasWidth: number
/**
* 推流出去的界面里白板图层占的高度（单位是像素
*/
canvasHeight: number
/**
* 白板左侧偏移量（单位是像素
*/
x?: number
/**
* 白板顶部偏移量（单位是像素）
*/
y?: number
/**
* 白板区域宽度（单位是像素）
*/
width: number
/**
* 白板高度（单位是像素）
*/
height: number
/**
* 强制使用当前配置
*/
force?: boolean
/**
* 参数
*/
param?: Object
/**
* 是否合流
*/
combinable?: boolean
/**
* 是否可编辑
*/
editable?: boolean
}
/**
* 白板信息
*/
type WhiteBoardInfo = {
/**
* 白板ID
*/
wbId: string
}
}
示例代码
hyExt.stream
.createWB({
type: "EXTRA",
wbName: "wbName",
offsetX: 1,
offsetY: 1,
canvasWidth: 1,
canvasHeight: 1,
x: 0,
y: 0,
width: 1,
height: 1,
force: false,
param: {},
combinable: false,
editable: false,
})
.then((res) => {
const { wbId } = res
console.log("调用hyExt.stream.createWB成功", res)
})
.catch((err) => {
console.log("调用hyExt.stream.createWB失败", err)
})
相关链接
相关sdk
- hyExt.stream.deleteWB（删除白板）
- hyExt.stream.updateWB（更新白板）
- hyExt.stream.getStreamResolution（获取推流的分辨率）
- hyExt.stream.onWBLayoutChange（监听白板布局变化消息）
- hyExt.stream.onExtraWhiteBoardMessage（监听小程序独立白板消息）
- hyExt.stream.sendToExtraWhiteBoard（发送消息到小程序独立白板）
开发调试
下面是几种常见的小程序开发和调试解决问题方式，部份在虎牙直播PC客户端-主播侧中也有具体阐述，开发者可根据实际情况参考解决。
打开小程序的调试控制台
在进行本地开发时，小程序的调试控制台（开发者工具）默认是关闭的。开发者可以在小程序商城打开小程序后，用鼠标点击小程序面板的任意位置进行对焦，再使用键盘键入F12即可打开小程序的调试控制台，具体功能面板使用方式与常规网页开发无异。
白板创建成功
使用hyExt.stream.createWBsdk创建白板成功后，当前直播间主场景中会出现特定的白板标识，并且会在视频区进行投影对应的内容。
打开白板专属的调试控制台
白板和小程序面板的调试控制台（开发者工具）是互相分开的。白板创建成功并打开小程序的调试控制台后，用鼠标点击小程序调试控制台的任意位置进行对焦，再使用键盘键入Ctrl+F12即可打开白板专属的调试控制台。
重复创建白板问题 若创建白板成功后，再次修改了项目代码进行保存后，原来的创建的白板是不会主动销毁的。因此再次创建时可能会出现重复创建白板报错
addWhiteBoard faild,whiteBoard count is morethan 5 or wbName existed。开发者可以使用hyExt.stream.deleteWB（删除白板sdk）传入对应的wbId和wbName参数删除原先创建的白板 或 重新打开该小程序对整个小程序进行初始化。
生命周期
直播间信息
环境信息
弹幕
礼物
文本秩序审核
小程序消息
终端事件监听
KV存储
主播端白板
网络库
文件处理
外部EXE能力
浮窗
小程序付费功能
订阅
直播间分享事件
守护事件
贵族事件
高级用户进场事件
小程序入口控制
本地小程序控制
语音识别事件
手势识别事件
视觉识别事件
人体轮廓点检测事件
肢体骨骼点检测事件
人脸特征点检测事件
播放视频
直播间视频
后台相关