互动白板接口文档

最近更新时间:2019-07-31 11:12:10

常量型定义

严重错误码定义

错误码 具体值 说明
TEDU_BOARD_ERROR_INIT 1 初始化失败(Android 端不会发生)
TEDU_BOARD_ERROR_AUTH 2 服务鉴权失败,请先购买服务
TEDU_BOARD_ERROR_LOAD 3 白板加载失败
TEDU_BOARD_ERROR_TIM_INVALID 5 IMSDK 不可用

警告错误码定义

错误码 具体值 说明
TEDU_BOARD_WARNING_SYNC_DATA_PARSE_FAILED 1 接收到其他端数据后,解析错误
TEDU_BOARD_WARNING_TIM_SEND_MSG_FAILED 2 IMSDK 发送消息失败
TEDU_BOARD_WARNING_H5PPT_ALREADY_EXISTS 3 添加的 H5PPT 已存在时抛出该警告

白板工具定义

工具类型 具体值 说明
TEDU_BOARD_TOOL_TYPE_MOUSE 0 鼠标
TEDU_BOARD_TOOL_TYPE_PEN 1 画笔
TEDU_BOARD_TOOL_TYPE_ERASER 2 橡皮擦
TEDU_BOARD_TOOL_TYPE_LASER 3 激光笔
TEDU_BOARD_TOOL_TYPE_LINE 4 直线
TEDU_BOARD_TOOL_TYPE_OVAL 5 空心椭圆
TEDU_BOARD_TOOL_TYPE_RECT 6 空心矩形
TEDU_BOARD_TOOL_TYPE_OVAL_SOLID 7 实心椭圆
TEDU_BOARD_TOOL_TYPE_OVAL_SOLID 8 实心矩形
TEDU_BOARD_TOOL_TYPE_POINT_SELECT 9 点选工具
TEDU_BOARD_TOOL_TYPE_RECT_SELECT 10 选框工具
TEDU_BOARD_TOOL_TYPE_TEXT 11 文本工具
TEDU_BOARD_TOOL_TYPE_ZOOM_DRAG 12 缩放移动白板工具

图片填充对齐模式定义

填充类型 具体值 说明
TEDU_BOARD_IMAGE_FIT_MODE_CENTER 0 以宽度或者高度为基准居中对齐等比例放大
TEDU_BOARD_IMAGE_FIT_MODE_LEFT 4 以宽度或者高度为基准左对齐等比例放大
TEDU_BOARD_IMAGE_FIT_MODE_TOP 5 以宽度或者高度为基准顶对齐等比例放大
TEDU_BOARD_IMAGE_FIT_MODE_RIGHT 6 以宽度或者高度为基准右对齐等比例放大
TEDU_BOARD_IMAGE_FIT_MODE_BOTTOM 7 以宽度或者高度为基准底对齐等比例放大

图片加载的状态定义

当前状态 具体值 说明
TEDU_BOARD_IMAGE_STATUS_LOADING 1 正在加载中
TEDU_BOARD_IMAGE_STATUS_LOAD_DONE 2 加载完成
TEDU_BOARD_IMAGE_STATUS_LOAD_ABORT 3 图片加载中断
TEDU_BOARD_IMAGE_STATUS_LOAD_ERROR 4 加载错误

白板文本样式

当前状态 具体值 说明
TEDU_BOARD_TEXT_STYLE_NORMAL 0 常规样式
TEDU_BOARD_TEXT_STYLE_BOLD 1 粗体样式
TEDU_BOARD_TEXT_STYLE_ITALIC 2 斜体样式
TEDU_BOARD_TEXT_STYLE_BOLD_ITALIC 3 粗斜体样式

白板上传状态定义

当前状态 具体值 说明
TEDU_BOARD_UPLOAD_STATUS_SUCCEED 1 上传成功
TEDU_BOARD_UPLOAD_STATUS_FAILED 2 上传失败

H5 背景状态定义

当前状态 具体值 说明
TEDU_BOARD_BACKGROUND_H5_STATUS_LOADING 1 H5 背景正在加载
TEDU_BOARD_BACKGROUND_H5_STATUS_LOAD_FINISH 2 H5 背景加载完成

白板内容自适应模式(内容包括图片、文件、PPT 动画)

当前状态 具体值 说明
TEDU_BOARD_CONTENT_FIT_MODE_NONE 0 不使用内容自适应,默认模式,不自动调整白板宽高比,内容等比例缩放居中显示,内容宽高 <= 白板宽高
TEDU_BOARD_CONTENT_FIT_MODE_CENTER_INSIDE 1 自动调整白板宽高比与内容一致,内容铺满白板,白板等比例缩放居中显示,白板宽高 <= 容器宽高
TEDU_BOARD_CONTENT_FIT_MODE_CENTER_COVER 2 自动调整白板宽高比与内容一致,内容铺满白板,白板等比例缩放居中显示,白板宽高 >= 容器宽高

回调接口(TEduBoardCallback)

基本流程回调

错误回调函数

void onTEBError(int code, String msg);
参数值 类型 说明
code int 具体错误码
msg String 具体错误信息

警告回调函数

void onTEBWarning(int code, String msg);
参数值 类型 说明
code int 具体警告错误码
msg String 具体错误信息

白板初始化完成回调函数

void onTEBInit();

说明:

收到该回调后,表示白板已处于可正常工作状态。

白板历史数据同步完成回调函数

void onTEBHistroyDataSyncCompleted();

白板同步数据回调函数

void onTEBSyncData(String data);
参数值 类型 说明
data String 白板同步数据(JSON 格式字符串)

说明:

  1. 收到该回调时需要将回调数据通过信令通道发送给房间内其他人,接受者收到后调用 AddSyncData 接口将数据添加到白板以实现数据同步。
  2. 该回调用于多个白板间的数据同步,使用内置 IM 作为信令通道时,不会收到该回调。

白板可撤销状态改变回调函数

void onTEBUndoStatusChanged(boolean canUndo);
参数值 类型 说明
canUndo boolean 白板当前是否还能执行 Undo 操作

白板可重做状态改变回调函数

void onTEBRedoStatusChanged(boolean canRedo);
参数值 类型 说明
canRedo boolean 白板当前是否还能执行 Redo 操作

涂鸦相关回调

白板图片状态改变回调函数

void onTEBImageStatusChanged(String boardId, String url, int status);
参数值 类型 说明
boardId String 白板 ID
url String 白板图片 URL
status int 新的白板图片状态

设置白板背景图片回调函数

void onTEBSetBackgroundImage(String url);
参数值 类型 说明
url String 调用 SetBackgroundImage 时传入的 URL

说明:

只有本地调用 SetBackgroundImage 时会收到该回调, 收到该回调表示背景图片已经上传或下载成功,并且显示出来。

设置白板背景 H5 状态改变回调函数

void onTEBBackgroundH5StatusChanged(String boardId, String url, int status);
参数值 类型 说明
boardId String 白板 ID
url String 调用 SetBackgroundImage 时传入的 URL
status int 新的白板图片状态

白板页操作回调

增加白板页回调函数

void onTEBAddBoard(List boardIds, String fileId);
参数值 类型 说明
boardIds List 增加的白板页 ID 列表
fileId String 增加的白板页所属的文件 ID

删除白板页回调函数

void onTEBDeleteBoard(List boardIds, String fileId);
参数值 类型 说明
boardIds List 增加的白板页 ID 列表
fileId String 增加的白板页所属的文件 ID

跳转白板页回调函数

void onTEBGotoBoard(String boardId, String fileId);
参数值 类型 说明
boardId String 增加的白板页 ID
fileId String 增加的白板页所属的文件 ID

文件操作回调

增加文件回调函数

void onTEBAddFile(String fileId);
参数值 类型 说明
fileId String 增加的白板页所属的文件 ID

说明:

文件上传完成后才会触发该回调。

增加 H5 动画 PPT 文件回调函数

void onTEBAddH5PPTFile(String fileId);
参数值 类型 说明
fileId String 增加的白板页所属的文件 ID

说明:

文件上传完成后才会触发该回调。

删除文件回调函数

void onTEBDeleteFile(String fileId);
参数值 类型 说明
fileId String 删除的文件 ID

切换文件回调函数

void onTEBSwitchFile(String fileId);
参数值 类型 说明
fileId String 切换到的文件 ID

文件上传进度回调函数

void onTEBFileUploadProgress(String path, int currentBytes, int totalBytes, int uploadSpeed);
参数值 类型 说明
path String 正在上传的文件路径,编码格式为 UTF8
currentBytes int 当前已上传大小,单位 bytes
totalBytes int 文件总大小,单位 bytes
uploadSpeed int 文件上传速度,单位 bytes

文件上传状态回调函数

void onTEBFileUploadStatus(final String path, int status, String statusMsg);
参数值 类型 说明
path String 正在上传的文件路径,编码格式为 UTF8
status int 文件上传中的状态
statusMsg int 文件上传的状态消息

结构体定义

授权参数(TEduBoardAuthParam)

class TEduBoardAuthParam {  
    int sdkAppId;  
    String userId;  
    String userSig;  
}
成员 类型 说明
sdkAppId int SDK 的 AppId
userId String 用户的 ID
userSig String 用户的 Sig 值

颜色参数(TEduBoardColor)

class TEduBoardColor {  
    int red;  
    int green;  
    int blue;  
    int alpha;  
}
成员 类型 说明
red int 红色值
green int 绿色值
blue int 蓝色值
alpha int 透明度值

白板信息(TEduBoardInfo)

class TEduBoardInfo {  
  String boardId;
  String backgroundUrl;
  TEduBoardColor backgroundColor;
}
成员 类型 说明
boardId int 白板 ID
backgroundUrl int 背景图或者背景 H5 页面的 URL
backgroundColor int 白板背景色

文件信息(TEduBoardFileInfo)

static class TEduBoardFileInfo {  
  String fileId;               
  String title;               
  String downloadUrl;      
  int pageCount;        
  int pageIndex;       
  List<TEduBoardInfo> boardInfoList;   
}
成员 类型 说明
fileId String 文件 ID
title String 文件名
downloadUrl String 文件下载地址
pageCount int 文件页数
pageIndex int 文件当前显示的页数
boardInfoList List 白板信息列表

白板初始化信息(TEduBoardInitParam)

public static class TEduBoardInitParam {  
  String ratio = "16:9";    //默认白板宽高比(可传格式如“4:3”、“16:9”的字符串)  
  boolean drawEnable = true; //是否允许涂鸦  
  TEduBoardColor globalBackgroundColor = new TEduBoardColor(255, 255, 255, 255);  //全局背景色  
  int toolType = TEduBoardToolType.TEDU_BOARD_TOOL_TYPE_PEN; //白板工具  
  TEduBoardColor brushColor = new TEduBoardColor(255, 0, 0, 255);//画笔颜色  
  int brushThin = 100;  //画笔粗细  
  TEduBoardColor textColor = new TEduBoardColor(0, 0, 0, 255);  //文本颜色  
  int textSize = 320;  //文本粗细  
  int textStyle = TEduBoardTextStyle.TEDU_BOARD_TEXT_STYLE_NORMAL;  //文本样式  
  String textFamily = "sans-serif,serif,monospace"; //文本字体  
  boolean timSync = true;  //是否使用腾讯云 IMSDK 进行实时数据同步  
  int preloadDepth = 5;  //指定图片预加载深度,默认值为5(表示预加载当前页前后5页的图片  
  float smoothLevel = 0.1f; //用于指定笔迹平滑级别,默认值0.1,取值[0, 1]  
  boolean dataSyncEnable = true;  //用于指定是否启用数据同步  
  int contentFitMode = TEduBoardContentFitMode.TEDU_BOARD_CONTENT_FIT_MODE_NONE; //内容自适应模式  
};
参数 类型 默认值 说明
ratio String 16:9 白板尺寸/比例
字符串宽高比,例如设置4:3,白板 SDK 会以参数 ID 所在节点的宽高以4:3的方式来计算出白板的宽高
drawEnable Boolean true 是否可以涂鸦
textFamily String sans-serif,serif,monospace 文字输入功能的默认文字字体
textStyle Number 0 文字输入功能的默认文字样式
0:常规;1:粗体;2:斜体;3:粗斜体,默认值0
textSize Number 320 文字输入功能的字体,实际像素值取值(size * 白板的高度 / 10000)px
textColor String #000000 文字输入功能的颜色,支持 hex、rgba 格式,如 #ffffff,rgba(255, 255, 255, 0.3)
brushColor String #ff0000 涂鸦颜色,支持 hex、rgba 格式,如 #ffffff,rgba(255, 255, 255, 0.3)
brushThin Number 100 涂鸦粗细,实际像素值取值(brushThin * 白板的高度 / 10000)px,如果结果小于1px,则涂鸦的线条会半透明
toolType Number 1 涂鸦类型,默认画笔
1. 画笔
2. 橡皮擦
3. 激光笔
4. 直线
5. 空心椭圆
6. 空心矩形
7. 实心椭圆
8. 实心矩形
9. 点选工具
10. 框选工具
11. 文本工具
globalBackgroundColor String #ffffff 全局背景色,支持 hex、rgba 格式,如 #ffffff,rgba(255, 255, 255, 0.3)
boardContentFitMode Number 0 0不自动调整白板宽高比,文件等比例缩放居中显示,文件宽高 <= 白板宽高
1自动调整白板宽高比与文件一致,文件铺满白板,白板等比例缩放居中显示,白板宽高 <= 容器宽高
2自动调整白板宽高比与文件一致,文件铺满白板,白板等比例缩放居中显示,白板宽高 >= 容器宽高
dataSyncEnable Boolean true 是否数据同步
scale Number 100 支持[100,300],实际缩放比为 scale / 100
preloadDepth Number 5 预加载深度,预加载前后 preloadDepth 页白板
smoothLevel Number 0.1 平滑级别,取值0~1之间的浮点数,0表示不启用平滑

具体接口

基本流程接口

设置事件回调监听函数

void addCallback(TEduBoardCallback callback);
参数值 类型 说明
callback TEduBoardCallback 事件回调监听

说明:

  1. 建议在 Init 之前调用该方法以支持错误处理;
  2. 内部是弱引用持有 callback 对象。

删除事件回调监听函数

void removeCallback(TEduBoardCallback callback);
参数值 类型 说明
callback TEduBoardCallback 事件回调监听

初始化白板

void init(TEduBoardAuthParam authParam, int roomId, TEduBoardInitParam para);
参数值 类型 说明
authParam TEduBoardAuthParam 授权参数
roomId int 课堂 ID
para TEduBoardInitParam 白板默认参数,不需要修改直接填 null

说明:

  1. 使用腾讯云 IMSDK 进行实时数据同步时,会尝试反射调用腾讯云 IMSDK 作为信令通道进行实时数据收发(只实现消息收发,初始化和进房等操作需要用户自行实现);
  2. 目前仅支持 IMSDK 4.0以上版本。

获取白板渲染 View

View getBoardRenderView();
返回值类型 说明
View 白板显示的视图

说明:

  1. 在调用此接口获取 View 后,加入到视图树中后,在结束时需要 removeView;
  2. 收到 onBoardInit 回调之前调用该接口无效;
  3. view 类型在 Windows 下取 HWND、iOS 下取 UIView*、Android 下取 View、macOS 下取 NSView*、Linux 下取 GtkWidget。

添加白板同步数据

void addSyncData(String data);
参数值 类型 说明
data String 接收到的房间内其他人发送的同步数据

说明:

该接口用于多个白板间的数据同步,使用内置 IM 作为信令通道时,不需要调用该接口。

设置白板是否开启数据同步

void setDataSyncEnable(boolean enable);
参数值 类型 说明
enable boolean 是否开启

说明:

白板创建后默认开启数据同步,关闭数据同步,本地的所有白板操作不会同步到远端和服务器。

获取白板是否开启数据同步

boolean isDataSyncEnable();
返回值类型 说明
boolean 是否开启数据同步,YES 表示开启,NO 表示关闭

重置白板

void reset();

说明:

调用该接口后将会删除所有的白板页和文件。

涂鸦相关接口

设置白板是否允许涂鸦

void setDrawEnable(boolean enabled);
参数值 类型 说明
enable boolean 是否允许涂鸦

说明:

白板创建后默认为允许涂鸦状态。

获取白板是否允许涂鸦

boolean isDrawEnable();
返回值类型 说明
boolean 是否允许涂鸦

设置白板默认背景色

void setGlobalBackgroundColor(TEduBoardColor color);
参数值 类型 说明
color TEduBoardColor 要设置的默认背景色

说明:

白板创建后默认背景色为白色。

获取白板默认背景色

TEduBoardColor getGlobalBackgroundColor();
返回值类型 说明
TEduBoardColor 默认的背景色

设置当前白板页的背景色

void setBackgroundColor(TEduBoardColor color);
参数值 类型 说明
color TEduBoardColor 要设置的默认背景色

说明:

白板创建后当前背景色,默认背景色由 SetDefaultBackgroundColor 接口设定。

获取当前白板页的背景色

TEduBoardColor getBackgroundColor();
返回值类型 说明
TEduBoardColor 当前白板页的背景色

设置要使用的白板工具

void setToolType(int type);
参数值 类型 说明
type int 要设置的白板工具

获取正在使用的白板工具

int getToolType();
返回值类型 说明
int 正在使用的白板工具

设置画笔颜色

void setBrushColor(TEduBoardColor color);
参数值 类型 说明
color TEduBoardColor 要设置的画笔颜色

获取画笔颜色

TEduBoardColor getBrushColor();
返回值类型 说明
TEduBoardColor 画笔颜色

设置画笔粗细

void setBrushThin(int thin);
参数值 类型 说明
thin int 要设置的画笔粗细

说明:

画笔粗细用于所有涂鸦绘制,实际像素值取值(thin * 白板的高度 / 10000)px,如果结果小于1px,则涂鸦的线条会比较虚。

获取画笔粗细

int getBrushThin();
返回值类型 说明
int 画笔粗细

设置文本颜色

void setTextColor(TEduBoardColor color);
参数值 类型 说明
color TEduBoardColor 要设置的文本颜色

获取文本颜色

TEduBoardColor getTextColor();
返回值类型 说明
TEduBoardColor 文本颜色

设置文本大小

void setTextSize(int size);
参数值 类型 说明
size int 要设置的文本大小

说明:

实际像素值取值(thin * 白板的高度 / 10000)px。

获取文本大小

int getTextSize();
返回值类型 说明
int 文本大小

设置文本样式

void setTextStyle(int style);
参数值 类型 说明
style int 要设置的文本样式

获取文本样式

int getTextStyle();
返回值类型 说明
int 文本样式

设置文本字体

void setTextFamily(String family);
参数值 类型 说明
family String 文本字体

获取文本字体

String getTextFamily();
返回值类型 说明
String 文本字体

清空当前白板页涂鸦

void clear(boolean clearBackground);
参数值 类型 说明
clearBackground boolean 是否同时清空背景色以及背景图片

设置当前白板页的背景图片

void setBackgroundImage(String url, int mode);
参数值 类型 说明
url String 要设置的背景图片 URL
mode int 要使用的图片填充对齐模式

说明:

  1. 当 URL 是一个有效的本地文件地址时,该文件会被自动上传到 COS;
  2. 该接口与 SetBackgroundH5 接口互斥。

设置当前白板页的背景 H5 页面

void setBackgroundH5(String url);
参数值 类型 说明
url String 要设置的背景图片 URL

说明:

该接口与 SetBackgroundImage 接口互斥。

撤销当前白板页上一次动作

void undo();

重做当前白板页上一次撤销

void redo();

设置当前白板页宽高比

void setBoardRatio(String ratio);
参数值 类型 说明
ratio String 要设置的白板宽高比

说明:

格式如:“4:3”、“16:9”。

获取当前白板页宽高比

String getBoardRatio();
返回值类型 说明
String 白板宽高比

设置当前白板页缩放比例

void setBoardScale(int scale);
参数值 类型 说明
scale int 要设置的白板缩放比例

说明:

支持范围:[100,300],实际缩放比为:scale / 100。

获取当前白板页缩放比例

int getBoardScale();
返回值类型 说明
int 白板缩放比例

设置白板内容自适应模式

void setBoardContentFitMode(int mode);
参数值 类型 说明
mode int 要设置的白板内容自适应模式

说明:

设置自适应模式后会影响所有后续白板内容操作,受影响接口包括:AddFile 和 AddH5PPTFile。

获取白板内容自适应模式

int getBoardContentFitMode();
返回值类型 说明
int 获取白板内容自适应模式

白板操作接口

增加一页白板

String addBoard(String url);

返回值:白板的 ID。

参数值 类型 说明
url String 使用的背景图片 URL,为空字符串表示不指定背景图片, 白板页会被添加到当前文件

删除一页白板

String deleteBoard(String url);
参数值 类型 说明
url String 要删除的白板 ID,为空字符串表示删除当前页

说明:

  1. 允许删除任意文件的白板页;
  2. 默认白板页无法删除。

上一步

void prevStep();

说明:

  1. 每个 Step 对应 PPT 的一个动画效果;
  2. 若当前没有已展示的动画效果,则该接口调用会导致向前翻页。

下一步

void nextStep();

说明:

  1. 每个 Step 对应 PPT 的一个动画效果;
  2. 若当前没有已展示的动画效果,则该接口调用会导致向后翻页。

向前翻页

void prevBoard(boolean resetStep);
参数值 类型 说明
resetStep boolean 是否要重置动画步数,默认 false

说明:

若当前白板页为当前文件的第一页,则该接口调用无效。

下向后翻页

void nextStep(boolean resetStep);
参数值 类型 说明
resetStep boolean 是否要重置动画步数,默认 false

说明:

若当前白板页为当前文件的最后一页,则该接口调用无效。

跳转到指定白板页

void gotoBoard(String boardId, boolean resetStep);
参数值 类型 说明
boardId String 要跳转到的白板页 ID
resetStep boolean 是否要重置动画步数,默认 false

获取当前白板页 ID

String getCurrentBoard();
返回值类型 说明
String 当前白板页 ID

获取所有文件的白板列表

List<String> getBoardList();
返回值类型 说明
List 所有文件的白板列表

文件操作接口

增加文件

void addFile(String path);
参数值 类型 说明
path String 要增加的文件路径,编码格式为 UTF8

说明:

  1. 支持 PPT、PDF、Word 和 Excel;
  2. 当 path 指向一个有效的本地文件时,SDK 会先将文件上传到 COS 后再执行后续操作,此时会触发文件上传相关回调;
  3. 若 path 不是一个有效的本地文件路径,则会被当做 URL 处理,URL 必须指向腾讯云 COS 文件路径,否则接口调用无效;
  4. 文件添加完成后,将自动切换到该文件。

增加 H5 动画 PPT 文件

void addH5PPTFile(String url);
参数值 类型 说明
path String 要增加的 H5 动画 PPT 的 URL

说明:

  1. 调用该接口后,SDK 会在后台进行 H5 加载,期间用户可正常进行其它操作;
  2. 加载成功或失败后会触发相应回调;
  3. H5 加载成功后,将自动切换到该文件。

删除文件

void deleteFile(String fileId);
参数值 类型 说明
fileId String 要删除的文件 ID

说明:

  1. 文件 ID 为空字符串时表示当前文件;
  2. 默认文件无法删除。

切换文件

void switchFile(String fileId);
参数值 类型 说明
fileId String 要切换到的文件 ID

说明:

  1. 文件 ID 为必填项;
  2. 为空字符串将导致文件切换失败。

获取当前文件 ID

String getCurrentFile();
返回值类型 说明
String 当前文件 ID

获取白板中上传的所有文件信息列表

List<TEduBoardFileInfo> getFileInfoList();
返回值类型 说明
List 白板 ID 列表

获取指定文件 ID 的文件信息

TEduBoardFileInfo getFileInfo(String fileId);
参数值 类型 说明
fileId String 文件 ID
返回值类型 说明
TEduBoardFileInfo 文件信息

清空指定文件的所有白板涂鸦

void clearFileDraws(String fileId);
参数值 类型 说明
fileId String 文件 ID