Android (Java)
本文结合部分 SDK API ,介绍如何快速接入白板功能。
如需查看完整 SDK API 列表,请点击左侧导航查看:
SDK API - Android (Java) - com.pano.rtc.api.RtcWhiteboard。
导入SDK
请 点此查看 如何导入Pano SDK。
如果产品中使用 PDF 相关的白板功能,还请注意以下内容。
- 如果项目需要混淆,请在 proguard-rules.pro 文件中配置以下内容防止混淆第三方组件:
-keep class com.shockwave.** {*;}
- 如果采用手工集成(通过 aar 包导入 SDK)的方式,请在 Module 的 build.gradle - dependencies 中添加:
implementation 'com.github.barteksc:android-pdf-viewer:3.2.0-beta.1'
获取白板
使用白板前,请先 初始化 RtcEngine
实例,再通过其 getWhiteboard
方法获取白板控制接口。
mWhiteboard = mRtcEngine.getWhiteboard();
注册通知
通过 RtcWhiteboard
实例的 setCallback
方法注册白板回调,用来接收白板事件通知。
mWhiteboard.setCallback(new RtcWhiteboard.Callback() {
@Override
public void onCreateDoc(Constants.QResult result, String fileId) {
// 创建白板文件通知
}
@Override
public void onContentUpdated() {
// 白板内容更新通知
}
@Override
public void onMessage(long userId, byte[] msg) {
// 收到白板消息的通知
}
...
})
完整的回调方法列表与介绍,请查看 RtcWhiteboard.Callback 接口。
加入频道
请 点此查看 如何加入频道。对于加入频道时的 RtcChannelConfig.serviceFlags
参数:
- 如果需要同时使用音视频和白板功能,请将其配置为:
kChannelServiceMedia | kChannelServiceWhiteboard
; - 如果仅使用白板功能,请将其配置为
kChannelServiceWhiteboard
。
打开白板
加入白板频道成功后,通过 RtcWhiteboard
实例的 open
方法打开白板。
第一位用户打开白板时,其他用户会收到
RtcEngineCallback
的onWhiteboardStart()
通知。
/* 需要在 xml 布局文件中添加一个 com.pano.rtc.api.PanoCoursePageView 组件用于显示白板内容,
PanoCoursePageView 外面必须包裹一层 Layout (建议使用 ConstraintLayout),例如:
<androidx.constraintlayout.widget.ConstraintLayout
android:id="@+id/wb_content_view"
...>
<com.pano.rtc.api.PanoCoursePageView
android:id="@+id/pano_course_page_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent"/>
</androidx.constraintlayout.widget.ConstraintLayout>
*/
PanoCoursePageView panoCoursePageView = view.findViewById(R.id.pano_course_page_view);
/* 如需在白板内播放音视频,1.6.4.1及之后的 SDK 版本默认使用 MediaPlayer
开发者可以通过 PanoCoursePageView 的 enableExoPlayer 方法启用 ExoPlayer
建议启用 ExoPlayer 以获得更好的性能(需要 AndroidX 支持)
* 如果通过 Gradle 自动集成,SDK 会自动添加 ExoPlayer
* 如果通过手工集成的方式导入 SDK 包,需要自行添加依赖:
`implementation 'com.google.android.exoplayer:exoplayer:2.13.3'`
*/
panoCoursePageView.enableExoPlayer(true);
// 不要连续调用 open 方法,如需重新打开,请先 close 再 open
mRtcWhiteboard.open(panoCoursePageView);
/* 对于1.6.4及之前的历史版本,需要先从 PanoCoursePageView 中获取 RtcWbView
PanoCoursePageView panoCoursePageView = view.findViewById(R.id.pano_course_page_view);
RtcWbView wbView = panoCoursePageView.getAttachRtcWbView(); // 获取 RtcWbView 对象
mRtcWhiteboard.open(wbView);
*/
工具条
SDK 内部已实现白板工具绘制和数据同步,但是由于不同的开发者有不同的 UI 设计,因此 SDK 不提供涉及 UI 交互的白板工具条。
请开发者自行设计白板工具条,来结合调用 SDK 接口以执行相应的白板操作。
全局属性
白板颜色
背景色
通过 RtcWhiteboard
实例的 setBackgroundColor
方法设置白板背景色。
mWhiteboard.setBackgroundColor(0xFF0000FF); // @ColorInt
// mWhiteboard.setBackgroundColor(0.75f, 0.75f, 0.75f, 1);
白板背景色仅在本地显示,不会同步给其他用户。因此每位用户的白板背景色可以不同。
前景色
通过 RtcWhiteboard
实例的 setForegroundColor
方法设置白板前景色。
前景色适用于文字、线条和边框的颜色。
mWhiteboard.setBackgroundColor(0xFF0000FF); // @ColorInt
// mWhiteboard.setForegroundColor(0.15f, 0.25f, 0.35f, 1);
填充色
通过 RtcWhiteboard
实例的 setFillColor
方法设置白板填充色。
填充色适用于封闭图形(如椭圆和矩形)的填充颜色。
mWhiteboard.setBackgroundColor(0xFF0000FF); // @ColorInt
// mWhiteboard.setFillColor(0.5f, 0.5f, 0.5f, 1);
适用于文字工具的全局属性
- 通过
RtcWhiteboard
实例的setFontSize
方法设置字体大小。
mWhiteboard.setFontSize(36);
- 通过
RtcWhiteboard
实例的setFontStyle
方法设置字体样式(粗体、斜体)。
mWhiteboard.setFontStyle(Constants.WBFontStyle.BoldItalic);
// 可选值:Normal, Bold, Italic, BoldItalic
适用于图形工具的全局属性
- 通过
RtcWhiteboard
实例的setLineWidth
方法设置线条和边框的宽度。
mWhiteboard.setLineWidth(10);
- 通过
RtcWhiteboard
实例的setFillType
方法设置封闭图形填充方式。
mWhiteboard.setFillType(Constants.WBFillType.Color);
// 可选值:None 不填充、Color 填充颜色
常用工具
设置工具类型
通过 RtcWhiteboard
实例的 setToolType
方法设置工具类型。
mWhiteboard.setToolType(Constants.WBToolType.None); // 空,画板不响应操作,但是可以操作动态课件中的内容
mWhiteboard.setToolType(Constants.WBToolType.Text); // 文本工具
mWhiteboard.setToolType(Constants.WBToolType.Path); // 画笔工具
mWhiteboard.setToolType(Constants.WBToolType.Laser); // 激光笔工具
mWhiteboard.setToolType(Constants.WBToolType.Line); // 直线工具
mWhiteboard.setToolType(Constants.WBToolType.Arrow); // 箭头工具
mWhiteboard.setToolType(Constants.WBToolType.Rect); // 矩形工具
mWhiteboard.setToolType(Constants.WBToolType.Ellipse); // 椭圆工具
// 使用图章工具前,请先添加图章、设置图章(切换不同图章时需重新设置图章)
mWhiteboard.setToolType(Constants.WBToolType.Stamp); // 图章工具
mWhiteboard.setToolType(Constants.WBToolType.Select); // 选择工具,可以触摸移动图形
// 从 1.6.6 版本开始,Eraser 工具更改为 Delete 工具
mWhiteboard.setToolType(Constants.WBToolType.Delete); // 删除工具,用于删除图形
// 刷子工具本质上是对图层区域做透明处理,所以开启刷子功能时,不要移动和缩放图形
// 刷子工具,可以结合 setLineWidth 方法设置其宽度
mWhiteboard.setToolType(Constants.WBToolType.Brush); // 刷子工具,用于擦除图形的局部
请在加入白板频道成功后再进行白板操作。
撤销与重做
通过 RtcWhiteboard
实例的 undo
方法撤消上一次操作,redo
方法重做上一次被撤销的操作。
mWhiteboard.undo();
- 只能对自己的操作记录进行撤销与重做。
- 另请关注通知:
onUndoStatusChanged
,onRedoStatusChanged
。
图片操作
设置背景图片缩放模式
通过 RtcWhiteboard
实例的 setBackgroundImageScalingMode
方法设置背景图片缩放模式。
// WBImageScalingMode 可选值:Fit/AutoFill/FillWidth/FillHeight/FitCenter
mWhiteboard.setBackgroundImageScalingMode(Constants.WBImageScalingMode.AutoFill);
设置背景图片
通过 RtcWhiteboard
实例的 setBackgroundImage(String imageUrl)
方法设置当前页的背景图片,setBackgroundImage(String imageUrl, int pageNo)
设置指定页的背景图片。
mWhiteboard.setBackgroundImage(imageUrl);
导入背景图片列表
通过 RtcWhiteboard
实例的 addBackgroundImages
方法导入背景图片列表到当前白板文档。
List<String> urls = new ArrayList<String>();
urls.add("...url1...");
urls.add("...url2...");
mWhiteboard.addBackgroundImages(urls);
上传图片
通过 RtcWhiteboard
实例的 addImageFile
方法上传图片(此方法上传的图片支持拖拽)。
String imageUrl = "https://domain/path/filename.jpg"; // 可为本地路径或远程 URL
mWhiteboard.addImageFile(imageUrl);
多媒体操作
Admin 用户操作音视频(包括动态课件中嵌入的音视频,以及通过下列方法上传到白板中的音视频)时,播放状态(播放、暂停、拖动进度条)会自动同步给其他用户。
上传音频
通过 RtcWhiteboard
实例的 addAudioFile
方法上传音频文件到当前页面。
String mediaUrl = "https://domain/path/filename.mp3"; // 可为本地路径或远程 URL
mWhiteboard.addAudioFile(mediaUrl);
上传视频
通过 RtcWhiteboard
实例的 addVideoFile
方法上传视频文件到当前页面。
String mediaUrl = "https://domain/path/filename.mp4"; // 可为本地路径或远程 URL
mWhiteboard.addVideoFile(mediaUrl);
设置用户角色
通过 RtcWhiteboard
实例的 setRoleType
方法设置自己的角色(这是异步操作,请注意监听 onRoleTypeChanged
通知)。
角色的区别:
定义 | 类型 | 权限 | 备注 |
---|---|---|---|
Admin | 管理员 | 可以使用工具,可以操作所有用户的内容 | 一个频道只能有一位管理员 |
Attendee | 普通用户 | 可以使用工具,只能操作自己的内容 | 默认角色 |
Viewer | 仅观看的用户 | 不能使用工具,只能缩放和移动 |
mWhiteboard.setRoleType(Constants.WBRoleType.Admin); // 设置自己为管理员
画板操作
缩放和移动
缩放
通过 RtcWhiteboard
实例的:
getCurrentScaleFactor
方法获取当前白板视图的缩放比例getCurrentMaxScaleFactor
方法获取当前白板视图的最大缩放比例getCurrentMinScaleFactor
方法获取当前白板视图的最小缩放比例setCurrentScaleFactor
方法设置缩放比例
System.out.println(mWhiteboard.getCurrentScaleFactor());
mWhiteboard.setCurrentScaleFactor(2.0f); // 取值范围 [0.1, 5.0]
重置当前页视角
通过 RtcWhiteboard
实例的 resetVision
方法重置当前页视角,将当前文档或动态课件一键居中,或者将默认白板恢复初始大小。
mWhiteboard.resetVision();
手势控制缩放和移动
通过 RtcWhiteboard
实例的 enableScaleMove
方法设置是否允许手势控制白板缩放和移动(不影响通过 setCurrentScaleFactor
方法控制缩放)。
mWhiteboard.enableScaleMove(true); // 默认值为 true (允许手势控制)
同步光标位置
通过 RtcWhiteboard
实例的 enableCursorPosSync
方法设置是否同步光标位置给其他用户,enableShowRemoteCursor
方法设置是否显示其他用户的光标位置。
mWhiteboard.enableCursorPosSync(true); // 同步光标位置给其他用户 (默认值false)
mWhiteboard.enableShowRemoteCursor(true); // 显示其他用户的光标位置 (默认值false)
UI 交互
通过 RtcWhiteboard
实例的 enableUIResponse
方法设置白板是否响应 UI 交互事件。
默认启用,如果传入 false
则白板不再响应任何 UI 交互,既不能移动和缩放,也不能使用任何工具。
mWhiteboard.enableUIResponse(false);
隐藏画板内容
通过 RtcWhiteboard
实例的 enableShowDraws
方法隐藏或显示白板图形(不影响背景图片和动态课件)。
mWhiteboard.enableShowDraws(false); // true: 显示(默认值),false: 隐藏
清除画板内容
白板的层级结构为:白板 -> 文档 -> 页面。
通过 RtcWhiteboard
实例的 clearDocContents
清除指定文档的内容(此方法需要管理员权限)。
mWhiteboard.clearDocContents("12345", Constants.WBClearType.All); // 管理员清除指定文档的所有内容
通过 RtcWhiteboard
实例的 clearContents
方法清除当前文档的画板内容(此方法需要管理员权限)。
mWhiteboard.clearContents(false, Constants.WBClearType.All); // 管理员清除当前文档所有页面的所有内容
通过 RtcWhiteboard
实例的 clearUserContents
方法清除当前文档中特定用户的画板内容。
所有用户都可以清除自己的内容,清除其他用户的内容需要管理员权限。
// 管理员清除当前文档中特定用户添加的图形
mWhiteboard.clearUserContents(10000, false, Constants.WBClearType.Draws);
关闭/离开白板
通过 RtcWhiteboard
实例的 close
方法关闭白板(仅关闭当前用户的白板 UI)。
mWhiteboard.close();
通过 RtcWhiteboard
实例的 leave
方法离开白板(关闭当前用户的白板 UI,并且断开白板服务)。
mWhiteboard.leave();
高级功能
请 点此查看 Android 白板的高级功能介绍。
SDK API 指南
更多白板 SDK 接口,请 点此查看 API 列表。
示例代码
为方便开发者了解丰富的接口使用方式,我们还提供示例代码,请体验参考: