Interface

2026-01-16


loadOptions	uploadOptions
ZegoCreateFileConfig	ZegoCreateWhiteboardConfig
ZegoCursorAttribute	ZegoEvent
ZegoSuperBoardCacheFileCallBack	ZegoSuperBoardCursorTitleStyle
ZegoSuperboardCustomH5Config	ZegoSuperBoardDynamicCacheModel
ZegoSuperBoardErrorData	ZegoSuperBoardInitConfig
ZegoSuperBoardStaticCacheModel	ZegoSuperBoardSubViewModel
ZegoSuperBoardUploadCallback	ZegoSuperBoardUploadH5FileCallback
ZegoSuperBoardUploadModel	ZegoWhiteboardScaleModel
~

ZegoCreateFileConfig

详情

接口参数构造类，用传入创建文件所需要的参数。

业务场景：在调用[createFileView]接口时需要传入。

属性

fileID

fileID: string

文件对应的ID

是否必填：必填

支持版本：2.0.0及以上

ZegoCreateWhiteboardConfig

详情

接口参数构造类，用传入创建白板所需要的参数。

业务场景：在调用 createWhiteboardView 接口是需要传入。

属性

name

name: string

创建白板时需要设置的白板名称。

是否必填：必填
取值范围：限制长度为 128 字节，支持中英文。

支持版本：2.0.0及以上

perPageWidth

perPageWidth: number

每页白板的宽度。

是否必填：必填
取值范围：大于 0 的正整数。

支持版本：v2.0.0。

perPageHeight

perPageHeight: number

每页白板的高度。

是否必填：必填
取值范围：大于0 的正整数。

支持版本：2.0.0及以上

pageCount

pageCount: number

总页数。

是否必填：必填。
取值范围：大于0。

支持版本：2.0.0及以上

ZegoCursorAttribute

详情描述：自定义光标可个性化属性。

属性

iconPath

iconPath: string | File

光标路径，可输入网络图片或者本地上传图标文件。

offsetX

offsetX: number

鼠标作用点 X 轴偏移

是否必填：是

示例：如要将鼠标作用点设置在图标的左上角，则 X 轴设置 0。

取值范围：0～32。
平台差异：该属性平台差异请参考 https://developer.mozilla.org/zh-CN/docs/Web/CSS/cursor#specifications。

offsetY

offsetY: number

鼠标作用点 Y 轴偏移

是否必填：是

示例：如要将鼠标作用点设置在图标的左上角，则 Y 轴设置 0。

取值范围：0～32。
平台差异：该属性平台差异请参考 https://developer.mozilla.org/zh-CN/docs/Web/CSS/cursor#specifications。

ZegoEvent

ZegoSuperBoard SDK 回调事件集合

属性

error

error: errorCallback

监听所有 error 错误

remoteSuperBoardSubViewAdded

remoteSuperBoardSubViewAdded: remoteSuperBoardSubViewAddedCallback

监听对端创建 subView ，返回对端创建的 subView 的 uniqueID

通知时机：创建成功 subView 后，已在同一房间内其他用户会在 [remoteSuperBoardSubViewAdded] 回调中收到相应通知。

remoteSuperBoardSubViewRemoved

remoteSuperBoardSubViewRemoved: remoteSuperBoardSubViewRemovedCallback

监听对端删除 subView ，返回对端删除的 subView 的 uniqueID。

通知时机：删除 subView 成功后，已在同一房间内其他用户会在 [remoteSuperBoardSubViewRemoved] 回调中收到相应通知。

remoteSuperBoardSubViewSwitched

remoteSuperBoardSubViewSwitched: remoteSuperBoardSubViewSwitchedCallback

监听对端切换 subView ，返回对端切换的 subView 的 uniqueID。

通知时机：切换 subView 成功后，已在同一房间内其他用户会在 [remoteSuperBoardSubViewSwitched] 回调中收到相应通知。

remoteSuperBoardAuthChanged

remoteSuperBoardAuthChanged: remoteSuperBoardAuthChangedCallback

监听白板权限变更，[缩放、滚动]权限对象

通知时机：权限变更发生，已在同一房间内用户会在 [remoteSuperBoardAuthChanged] 回调中收到相应通知。

remoteSuperBoardGraphicAuthChanged

remoteSuperBoardGraphicAuthChanged: remoteSuperBoardGraphicAuthChangedCallback

监听图元权限变更，[创建、擦除、移动、编辑、清空]权限对象

通知时机：权限变更发生，已在同一房间内用户会在 [remoteSuperBoardGraphicAuthChanged] 回调中收到相应通知。

superBoardSubViewScaleChanged

superBoardSubViewScaleChanged: superBoardSubViewScaleChangedCallback

监听缩放 subView ，返回缩放的 subView 的 uniqueID 和缩放系数。

通知时机：缩放 subView 成功后，在同一房间全部用户会在 [superBoardSubViewScaleChanged] 回调中收到相应通知。

superBoardSubViewScrollChanged

superBoardSubViewScrollChanged: superBoardSubViewScrollChangedCallback

监听滚动/翻页 subView ，返回滚动/翻页的 subView 的 uniqueID ，页码，动态 PPT 类型的文件的步数

通知时机：滚动/翻页 subView 成功后，在同一房间全部用户会在 [superBoardSubViewScrollChanged] 回调中收到相应通知。

cacheFile

cacheFile: cacheFileCallback

调用 cacheFile 接口后,缓存文件过程的状态会通过此回调出来。

业务场景：需要缓存文件到本地。

回调时机：调用cacheFile接口之后。

uploadFile

uploadFile: uploadFileCallback

监听文件等上传，返回文件上传状态，错误码，seq，上传进度，文件ID 信息

通知时机：上传文件成功后，在同一房间全部用户会在 [uploadFile] 回调中收到相应通知。

uploadH5File

uploadH5File: uploadH5FileCallback

监听 H5 文件上传，返回文件上传状态，错误码，seq，上传进度，文件ID 信息

通知时机：上传文件成功后，在同一房间全部用户会在 [uploadH5File] 回调中收到相应通知。

superBoardSubViewMediaPermission

superBoardSubViewMediaPermission: superBoardSubViewMediaPermissionCallback

监听被动端由于浏览器限制导致音视频无法播放时触发的回调，一般结合 playMedia 使用，将回调返回的信息传入 playMedia。

方法

errorCallback

errorCallback(error: ZegoSuperBoardErrorData): void

监听所有 error 错误

名称	类型	描述
error	ZegoSuperBoardErrorData	错误信息

remoteSuperBoardAuthChangedCallback

remoteSuperBoardAuthChangedCallback(data: Record<string, number>): void

返回白板权限变更对象

名称	类型	描述
data	Record<string, number>	返回白板权限变更对象注意事项：{ scale:0, scroll:1 }

remoteSuperBoardGraphicAuthChangedCallback

remoteSuperBoardGraphicAuthChangedCallback(data: Record<string, number>): void

返回图元权限变更对象

名称	类型	描述
data	Record<string, number>	返回图元权限变更变更对象注意事项：{ create:1, delete:1, move:1, update:1, clear:0 }

remoteSuperBoardSubViewAddedCallback

remoteSuperBoardSubViewAddedCallback(uniqueID: string): void

监听对端创建 subView ，返回对端创建的 subView 的 uniqueID

名称	类型	描述
uniqueID	string	对端创建的 subView 的 uniqueID

remoteSuperBoardSubViewRemovedCallback

remoteSuperBoardSubViewRemovedCallback(uniqueID: string): void

返回对端删除的 subView 的 uniqueID

名称	类型	描述
uniqueID	string	对端删除的 subView 的 uniqueID

remoteSuperBoardSubViewSwitchedCallback

remoteSuperBoardSubViewSwitchedCallback(uniqueID: string): void

返回对端切换的 subView 的 uniqueID

名称	类型	描述
uniqueID	string	对端切换的 subView 的 uniqueID

superBoardSubViewScaleChangedCallback

superBoardSubViewScaleChangedCallback(uniqueID: string, scale: number): void

监听缩放的 subView ，返回 subView 的 uniqueID 和缩放系数

名称	类型	描述
uniqueID	string	缩放的 subView 的 uniqueID
scale	number	缩放的 subView 的缩放系数

superBoardSubViewScrollChangedCallback

superBoardSubViewScrollChangedCallback(uniqueID: string, page: number, step: number): void

监听滚动/翻页的 subView ，返回 subView 的 uniqueID 和页码

名称	类型	描述
uniqueID	string	subView 的 uniqueID
page	number	subView 的页码
step	number	动态 PPT 类型的文件的步数

ZegoSuperBoardCacheFileCallBack

预加载静态文件进度回调

注意事项：仅缓存文件类型为静态文件时才有效

属性

data

data: ZegoSuperBoardStaticCacheModel

预加载静态文件回调返回的参数

ZegoSuperBoardCursorTitleStyle

光标自定义文本信息

详情

设置光标自定义文本信息

业务场景：需要显示光标自定义文本时可用

属性

title

title: string

光标自定义文字内容

是否必填：否
默认值：“”
建议值：用户登录名字展示
取值范围：15个字符以内

bold

bold: boolean

光标自定义文本是否加粗

是否必填：否
默认值：false

italic

italic: boolean

光标自定义文本是否斜体

是否必填：否
默认值：false

size

size: number

光标自定义文本字体大小

是否必填：否
默认值：16
取值范围：12-20

color

color: number

光标自定义文本字体颜色

是否必填：否
默认值：白色

backgroundColor

backgroundColor: number

光标自定义文本字体背景颜色

是否必填：否

position

position: ZegoSuperBoardCursorTitlePosition

自定义文本相对于光标的位置

是否必填：否

ZegoSuperBoardDynamicCacheModel

关于动态文件调用 cacheFile 方法返回的相关参数

注意事项：该返回字段即将废弃

属性

totalFileNum

totalFileNum: number

该文件总资源数

failedFileNum

failedFileNum: number

该文件预请求失败资源数

ZegoSuperBoardErrorData

错误回调

属性

code

code: ZegoSuperBoardError

错误码

msg

msg: string

错误信息

ZegoSuperBoardInitConfig

详情

接口参数构造类，用构造初始化SDK所需要的参数。

业务场景：调用初始化SDK接口 initWithConfig 时需要传入。

属性

appID

appID: number

ZEGO 为开发者签发的应用 ID，请从 ZEGO 管理控制台申请。

是否必填：必填
取值范围：0 - 4294967295。

token

~ token: string

登录验证 token，是通过在即构控制台注册项目获得密钥，加上指定算法获得。测试阶段可以通过 ZEGO 提供的接口获取，正式环境一定要用户自己实现。

parentDomID

parentDomID: string

展示 subView 的目标视图父容器 ID

是否必填：是

注意事项：在添加 subView 到视图中前必须确认父容器定位方式为相对定位且物理尺寸不为 0

userID

userID: string

用户ID，请勿在此字段填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

appSign

appSign: string

取值范围：'0' ~ '9', 'a' ~ 'z'。例："9dc9a25bh2f2137446897071c8c033fa33b91c3dd2a85e0c000ae82c0dad3"。2.3.0及以上版本 appSign 允许传空或者不传。如果传空或者不传，可以传token进行初始化。token的生成方式请参考使用 Token 鉴权。

dataFolder

dataFolder: string

数据目录

cacheFolder

cacheFolder: string

缓存目录

logFolder

logFolder: string

日志目录

ZegoSuperBoardStaticCacheModel

关于静态文件调用 cachel 方法产生的回调返回的相关参数

注意事项：该回调仅在预加载文件类型为静态文件时才返回

属性

seq

seq: number

缓存文件对应的 seq，如调用取消缓存 cancelCache 时需要

state

state: CacheState

文件当前缓存状态

totalFileNum

totalFileNum: number

该文件总资源数

failedFileNum

failedFileNum: number

该文件预请求失败资源数

loadedFileNum

loadedFileNum: number

该文件预请求成功资源数

ZegoSuperBoardSubViewModel

详情

数据模型类，里面包含了创建的ZegoSuperBoardSubView的名称、创建时间、包含的文件ID、文件类型以及ZegoSuperBoardSubView 对象的唯一标识。

业务场景：用户获取对应ZegoSuperBoardSubView对象的ID，名称和文件信息。

属性

name

name: string

SuperBoardSubView 对应的名称

createTime

createTime: number

白板创建时间 Unix 时间戳(毫秒)

fileID

fileID: string

创建文件白板时使用的文件ID，此 ID 唯一

fileType

fileType: ZegoSuperBoardFileType

创建文件白板时使用的文件类型，详见ZegoSuperBoardFileType

uniqueID

uniqueID: string

SuperBoardSubview的ID，此ID唯一。

whiteboardIDList

whiteboardIDList: string[]

白板ID的列表

ZegoSuperBoardUploadCallback

上传的进度和结果的回调

属性

data

data: ZegoSuperBoardUploadModel

上传文件产生回调返回的参数

ZegoSuperBoardUploadH5FileCallback

上传 H5 文件产生的回调

属性

data

data: ZegoSuperBoardUploadModel

上传文件产生回调返回的参数

ZegoSuperBoardUploadModel

uploadFile 方法产生的回调返回的相关参数

属性

status

status: ZegoSuperBoardUploadFileState

文件上传、转码状态

uploadPercent

uploadPercent: number

上传进度

fileID

fileID: string

转换完成后才会有 fileID

fileHash

fileHash: string

文件内容 hash

taskID

taskID: string

文件转码任务ID

loaded

loaded: number

已经上传的数据长度，单位 Bytes，文件上传中存在

total

total: number

预期需要上传的数据总长度，单位 Bytes，文件上传中存在

ZegoSuperboardCustomH5Config

详情

自定义H5课件属性构造类，可以设置自定义课件的宽、高、页数以及缩略图信息。

业务场景：在上传自定义H5课件接口中需要传入。

属性

width

width: number

是否必填：必填
取值范围：大于0

支持版本：2.0.0及以上

height

height: number

是否必填：必填
取值范围：大于0

支持版本：2.0.0及以上

pageCount

pageCount: number

是否必填：必填
取值范围：大于0

支持版本：2.0.0及以上

thumbnailList

thumbnailList: string[]

支持版本：2.0.0及以上

forceReload

forceReload: boolean

设置是否强制刷新

业务场景：在在部分 iOS 移动设备上渲染文件异常时，执行该 API 进行重新加载文件的操作。
是否必填：是。

reloadType

reloadType: reloadType

该配置，可以针对释放 canvas 的范围进行配置

是否必填：是。

ZegoWhiteboardScaleModel

缩放信息

属性

scaleFactor

scaleFactor: number

当前的缩放系数

scaleOffsetX

scaleOffsetX: number

缩放后产生的 X 方向的偏移

scaleOffsetY

scaleOffsetY: number

缩放后产生的 Y 方向的偏移

loadOptions

加载文件配置

详情

该配置，可以对加载文件时进行一些配置，例如触发动态 PPT 的加载回调时机

注意事项：注意每个配置生效条件，可能某些配置项只针对某类型文件生效。

属性

PPTReady

PPTReady: boolean

设置加载动态文件回调方法触发时机。通常情况下从文件服务器获得加载文件的信息后马上触发回调。

业务场景：获取加载动态 PPT 文件准备就绪状态。
是否必填：否。
默认值：false，默认从文件服务器获得文件信息后立即触发。

注意事项：该参数仅对动态 PPT 文件生效。

uploadOptions

上传文件配置项

详情

针对该上传的文件，进行转码配置

属性

renderImgType

renderImgType: RenderImgType

针对静态文件类型生效，可配置不同参数进行转码为对应的图片格式类型

~

重载配置项

详情

该配置，可以对重新加载 subview 时进行一些配置，例如是否触发强制刷新

支持版本：2.7.1及以后

属性

forceReload

forceReload: boolean

设置是否强制刷新

业务场景：在在部分 iOS 移动设备上渲染文件异常时，执行该 API 进行重新加载文件的操作。
是否必填：是。

reloadType

reloadType: reloadType

该配置，可以针对释放 canvas 的范围进行配置

是否必填：是。