Skip to content

GitLab

画板组件文档 · Changes

Page history
Created 画板组件文档 (markdown) authored by liguanpei's avatar liguanpei
Hide whitespace changes
Inline Side-by-side
Showing with 714 additions and 0 deletions
画板组件文档.md 0 → 100644
View page @ af944192
[TOC]
# 1. 文档相关API整理
## 1.0 文件上传API
```js
/**
* 文件上传的API
* 用户只需要调用文件上传API， 传入要进行上传的文件对象。
* 具体配置如下:
*/
// 通过`input type = files` 标签， 来进行获取上传文件对象相关的数据。
<input type="file" name="file" id="fileUpload">
// 获取input标签dom, 绑定`change`事件， 来进行触发上传操作。下面示例用`jQuery`， 来获取dom, 绑定事件。
$('#fileUpload').on('change', function (e) {
e.stopPropagation();
// 通过`new`关键字， 来创建文件上传对象的实例。
var uploadObject = new DocumentUpload({
/**
* 配置必须的参数：
* @params: {Object} files 保存的是要进行上传文件对象的相关数据。
* @params: {Function} uploadCallbackBefore 上传文件之前的回调函数。
* @params: {Function} uploadCallbackSuccess 上传文件到服务器成功的回调函数
* @params: {Function} uploadCallbackFailed 上传文件到服务器失败的回调函数
* @return: {*}
*
* 具体示例如下：
*
*/
mode: 0, // 上传是否支持ppt动画， 0 不支持 1 一般动画 2 极速动画
files: $('#file-upload')[0].files[0], // 用Dom节点的files属性，来获取上传数据。
uploadCallbackBefore: handleUploadCallbackBefore,
uploadCallbackSuccess: handleUploadCallbackSuccess，
uploadCallbackFailed: handleUploadCallbackFailed,
})
})
```
上传对象实例所需要的参数说明:
表1.1：
| 参数名称 | 参数说明 | 参数类型 | 是否必须 |
| --------------------- | ------------------------------ | ------------ | -------- |
| mode | 是否支持动画（预计9月20日生效） | { Number } | 可选 |
| files | 上传文件对象的相关数据 | { Object } | 必须 |
| uploadCallbackBefore | 上传文件之前的回调函数 | { Function } | 必须 |
| uploadCallbackSuccess | 上传文件到服务器成功的回调函数 | { Function } | 必须 |
| uploadCallbackFailed | 上传文件到服务器失败的回调函数 | { Function } | 必须 |
特殊说明：
目前ppt动画支持情况：
默认不支持动画
更改房间动画权限后【ppt_support】，支持一般动画权限
[修改房间动画权限](https://doc.bokecc.com/class/developer/classapi/#toc_5)
开通极速权限后，支持极速权限[联系我们修改账号权限]
通过mode控制（预计9月20日生效）
mode： 0 不支持动画 1 一般动画 2 极速动画
上传过程中的各阶段的回调函数 (上传之前， 上传成功， 上传失败)，回调函数中接受的参数， 我们也作了处理， 如下所示：
```php
/**
* 上传文件之前回调函数， 用户可以自定义, 对照着表1.1的参数表。
* @name： handleUploadCallbackBefore
* @params: {string} time 回调函数接受的参数是，上传文件的时间戳。
* @type: {function}
* @return: {*}
*
*/
function handleUploadCallbackBefore (time) {
// time: 上传文件的时间戳
// 用户可以作为文件的标识， 也可以利用time, 上传文件之前的动画， 提示等。
..... 上传文件之前的业务处理
}
/**
* 上传文件成功的回调函数， 用户可以自定义, 对照着表1.1的参数表。
* @name： handleUploadCallbackSuccess
* @params: {string} data 上传成功后，服务器返回的数据。
* @params: {string} time 上传文件的时间戳
* @type: {function}
* @return: {*}
*
*/
function handleUploadCallbackSuccess (data, time) {
// data: 上传成功的回调数据. time: 上传文件的时间戳
...... 上传文件成功的业务处理
}
/**
* 上传文件失败的回调函数， 用户可以自定义, 对照着表1.1的参数表。
* @name： handleUploadCallbackFailed
* @params: {string} data 上传失败后，服务器返回的数据。
* @params: {string} time 上传文件的时间戳
* @type: {function}
* @return: {*}
*
*/
function handleUploadCallbackFailed (data, time) {
// data: 上传失败的回调数据. time: 上传文件的时间戳
...... 上传文件失败的业务处理
}
```
### 1.01 上传文件格式支持
文档格式， 我们的API， 支持主流的文档格式， 我们有稳定的转码功能， 更能兼容不同文档的格式。
API支持的文档格式， 如表所示：
| 文档格式 | 是否支持 | 备注 |
| -------- | -------- | ---- |
| .doc | 是 | |
| .docx | 是 | |
| .ppt | 是 | |
| .pptx | 是 | |
| .pdf | 是 | |
| .jpg | 是 | |
如果上传文件格式，超出表中的格式范围，我们提示处理， 再选择上传格式支持的文档， 就可以了。
### 1.02 获取直播间所有关联的文档API (包含房间内直接上传和服务端关联到该房间的文档)
上传文档成功后， 存储在服务器， 我们可以通过API， 来获取当前直播间的所有上传成功的文档 和admin管理后台关联到该房间的文档。API用法如下：
```php
/**
* 接口对象：rtc
* 获取直播间所有文档API： getInstructionAllDocument
* @type: {function}
* @params: {Object} obj
* @return: {*}
*
*/
/**
* API的传入参数obj对象的配置如下：
* @params: {funcition} getInstructionAllDocumentSuccess 获取关联机构文档库所有文档成功的回调函数
* @params: {function} getInstructionAllDocumentFailed 获取关联机构所有文档失败的回调函数
* @return: {*}
*
*
* 具体示例如下：
*/
/** userSelfGetInstructionAllDocumentSuccess , userSelfGetInstructionAllDocumentFailed， 用户可以自定义函数 **/
rtc.getInstructionAllDocument ({
getInstructionAllDocumentSuccess: userSelfGetInstructionAllDocumentSuccess,
getInstructionAllDocumentFailed: userSelfGetInstructionAllDocumentFailed
});
// 获取所有关联文档库成功的回调函数， 用户可以自定义， 示例用 `userSelfGetInstructionAllDocumentSuccess`来演示。
function userSelfGetInstructionAllDocumentSuccess (data) {
// data: 是服务器成功回调返回的文档列表数据， 用户可以用来渲染。
..... 获取关联机构文档库所有文档成功业务处理
}
// 获取关联文档库所有文失败的回调函数， 用户可以自定义， 示例用 `userSelfGetInstructionAllDocumentFailed`来演示。
function userSelfGetInstructionAllDocumentFailed (data) {
// data: 服务器失败返回的数据， 用户可以用来提示等业务处理。
..... 获取关联机构文档库所有文档失败业务处理
}
```
### 1.03 获取直播间单个文档API
获取直播间的单个文档， 为了满足业务需求， 我们封装了API， 具体的API如下：
```js
/**
* 接口对象：rtc
* 获取直播间单个文档API： getSingleDocument
* @type: {function}
* @params: {Object} obj
* @return: {*}
*
*/
/**
* API的传入参数obj对象的配置如下：
* @params: {string} docId 文档id
* @params: {funcition} getSingleDocumentCallback 获取直播间单个文档成功的回调函数
*
* 具体示例如下：
*/
rtc.getSingleDocument ({
docId: docId,
getSingleDocumentCallback: userSelfGetSingleDocumentCallback,
});
// 获取直播间单个文档成功的回调函数， 用户可以自定义， 示例用 `userSelfGetSingleDocumentCallback`来演示。
function userSelfGetSingleDocumentCallback (data, docId) {
// data: 是服务器成功回调返回的文档数据， docId： 是当前的文档id
..... 获取直播间单个文档库成功业务处理
}
```
### 1.04 取消关联机构文档库文档API
取消关联机构文档库文档， 为了满足业务需求， 我们封装了API，（房间内删除机构文档库所关联文档时调用） 具体的API如下：
```php
/**
* 接口对象：rtc
* 获取直播间单个文档API： cancelDocument
* @type: {function}
* @params: {Object} obj
* @return: {*}
*
*/
/**
* API的传入参数obj对象的配置如下：
* @params: {string} docId 文档id
* @params: {funcition} cancelDocumentSuccess 取消关联机构文档库成功的回调函数
* @params: {function} cancelDocumentFailed 取消关联机构文档库失败的回调函数
* @return: {*}
*
* 具体示例如下：
*/
rtc.cancelDocument ({
docId: 'xxxxxxxx',
cancelDocumentSuccess: userSelfCancelDocumentSuccess,
cancelDocumentFailed： userSelfCancelDocumentFailed
});
// 取消关联机构文档库成功的回调函数， 用户可以自定义， 示例用 `userSelfCancelDocumentSuccess`来演示。
function userSelfCancelDocumentSuccess (data， docId) {
// data: 是服务器成功回调返回的数据. docId: 是取消关联文档的id
..... 取消关联机构文档库成功业务处理
}
// 取消关联机构文档库失败的回调函数， 用户可以自定义， 示例用 `userSelfCancelDocumentFailed`来演示。
function userSelfCancelDocumentFailed (data， docId) {
// data: 服务器失败返回的数据， 用户可以用来提示等业务处理。docId: 是取消关联文档的id
..... 取消关联机构文档库失败业务处理
}
```
# 2画板sdk开发指南
##2.0 开发说明
1.画板sdk继承了音视频sdk，使用画板sdk必须初始化音视频sdk
2.开启直播后，学生端可以同步教师端画板数据
3.开启或结束直播，画板内容会清空
4.已经添加的多页白板在直播过程中会为用户保存，非直播状态刷新浏览器不会保存
##2.1快速开发指南
```js
1.引入css样式文件
<link href="draw.css" rel="stylesheet" />
2.页面指定元素为画板显示区域
<!--外部固定宽高盒子，可自定义id样式-->
<div id="out-box">
<!--画板显示区域，可自定义id，样式，宽高需自适应-->
<div id="draw-parent"></div>
</div>
3.引入画板sdk
<script src="//image.csslcloud.net/js/dpc.js"></script>
<!--引入jquery类库，画板sdk 部分功能需依赖jquery库-->
<script src="https://class.csslcloud.net/static/js/jquery/jquery.min.js"></script>
<!--引入画板sdk，目前线下引用-->
<script src="drawSdk.js"></script>
4.初始化sdk
rtc.on('login_success', function (data) {
// 登录成功
console.log(data,'login_success');
var canvasInitData = {
allowDraw: true, // 是否具有书写画笔权限（讲师权限） true / false
id: 'draw-parent',
pptDisplay: 0 // 文档展示方式。默认0，按窗口 1， 按宽度
};
// 如果直播已经开始，需将直播id传入sdk中，
if(data.live.status === 1){
canvasInitData.liveId = data.live.id;
}
// 初始化画板
rtc.canvasInit(canvasInitData);
});
```
## 2.1 画板api
### 2.11 初始化画板
登陆成功之后可初始化sdk
```js
/**
* 接口对象：rtc
* 初始化文档sdk： canvasInit
* @type: {function}
* @params: {Object} obj
*
*/
/**
* API的传入参数obj对象的配置如下：
* @params: {string} allowDraw 是否具有画笔权限
* @params: {string} id 画板显示区域自定义id
*
* 具体示例如下：
*/
rtc.canvasInit({
allowDraw: true, // 是否具有书写画笔权限（讲师权限） true / false
id: 'draw-parent', // 画板区域 id
pptDisplay: 0, // 文档展示方式。默认0，按窗口 1， 按宽度
liveId: 'xxxxx', // 可选项，直播未开始不需要传，直播已开始需要传入（多页白板需要）
});
```
### 2.12 变更画笔
教师端需改画笔类型、粗细、颜色、字体大小时需调用该事件，默认为划线、学生修改画笔权限（学生端自己调用）
```js
/**
* 接口对象：rtc
* 变更画笔： drawChange
* @type: {function}
* @params: {Object} obj
*
*/
/**
* API的传入参数obj对象的配置如下：
* @params: {string} action 变更操作
* @params: {string} value 值
*
* 具体示例如下：
*/
var drawData = {
action: 'type',
value: drawType
};
// 调用更改画笔接口
rtc.drawChange(drawData);
```
具体参数参照下表
| | action | value |
| -------- | -------- | ---- |
| 画笔类型 | 'type' | 见下表 |
| 颜色 | 'color' | 16进制rgb色值 |
| 粗细 | 'thickNess' | 1, 3, 5(目前支持3级) |
| 字体大小 | 'size' | 建议 15—60 整形数字 |
| 学生是否可标注文档 | 'useDraw' | true 可标注 false 不可标注 |
不同画笔类型代码
| 画笔类型 | 值 |
| -------- | -------- |
| 曲线 | 2 |
| 画方块 | 3 |
| 画圆 | 4 |
| 文字输入 | 5 |
| 删除上一笔 | 9 |
| 清屏 | 0 |
| 橡皮擦 | 10 |
| 直线 | 11 |
| 激光笔 | 12 |
| 荧光笔 | 13 |
### 2.12 变更文档
教师端需切换文档、上一页、下一页、跳页、放大、缩小、全屏、退出全屏、新增白板、删除白板
```js
/**
* 接口对象：rtc
* 变更画笔： docChange
* @type: {function}
* @params: {Object} obj
*
*/
/**
* API的传入参数obj对象的配置如下：
* @params: {string} action 变更操作
* @params: {string} data[可选] 具体数据
*
* 具体示例如下：
*/
var docData = {
action: 'next', //下一页
};
rtc.docChange(docData);
```
具体操作参照下表
| | action | data |
| -------- | -------- | ---- |
| 切换文档 | 'changeDoc' | 见下文|
| 上一页 | 'pre' | 无 |
| 下一页 | 'next' | 无 |
| 跳页 | 'skip' | 见下文 |
| 放大 | 'enlarge' | 无 |
| 缩小 | 'narrow' | 无|
| 全屏 | 'full' | 无|
| 退出全屏 | 'exitFull' | 无 |
| 新增白板 | 'addBoard' | 无 |
| 删除白板 | 'deleteBoard' | 见下文 |
```js
/**
* 切换文档数据
*/
// 白板数据
var docData = {
action: 'changeDoc',
data: {
name: 'WhiteBorad',
id: 'WhiteBorad'
}
};
//文档数据
var docData = {
action: 'changeDoc',
data: {
name: 'xxxxx', // 文档名字
id: 'xxxxxx', // 文档id
totalpage: n, // 文档共有几页
docFromRoomId: 'xxxxx', // roomid
mode: 0, // 0 无动画 1 一般动画 2 极速动画
useSDK：false // false 不支持动画 true 支持动画
}
};
// 特别说明：
docFromRoomId ：房间内上传接口，此参数传入房间的roomid，机构文档库关联文档，需将关联文档的roomid传入，获取机构文档库接口，会返回每个文档roomid
/**
* 跳页数据
*/
var docData = {
action: 'skip',
data:{
toPage: num // 跳至当前文档第几页
}
};
/**
* 删除白板数据
*/
var docData = {
action: 'deleteBoard',
data:{
page: num // 删除第几页白板
}
};
```
### 2.13 监听当前文档变更事件
此事件用于监听sdk内直播中获取历史记录、翻页或缩放后界面渲染通知
```js
/**
* 接口对象：rtc
* 变更画笔： flipMessage
* @type: {function}
*
*/
/**
*
* 具体示例如下：
*/
rtc.on('flipMessage', function(data){
if(data.action === 'changeDoc'){
// 切换至文档，收到data数据如下
{
action: 'changeDoc',
data:{
id: 'xxxxx', // 文档id
urlArr:[] // 文档每一页的缩略图地址
}
}
// 切换至白板，增加或删除白板，收到data数据如下
{
action: 'changeDoc',
data:{
id: 'xxxxx', // 白板id
totalPage: n // 共几页
}
}
}else if(data.action === 'flip'){
// 翻页时收到data如下
{
action: 'flip',
data: {
id: 'xxxx', // 当前文档id
name: 'xxxx', // 当前文档name
currentPage: n, // 正在展示第几页
totalPage: n // 该文档共有几页
}
}
}else if(data.action === 'scale'){
// 缩放文档时收到data如下：
{
action: 'scale',
data: {
percent: n // 文档当前比例：1 最小 2最大
}
}
}else if(data.action === 'history'){
// 刷新或刚进入房间时拉取历史记录时收到data如下：
{
action: 'history',
data:{
name: 'xxxx', // 当前文档name
id: 'xxxxx' // 当前文档id
}
}
}
});
```
# 3. 更新说明
## 3.1新增多页白板功能
### 3.1.1 功能描述
增加了新建或删除白板、白板翻页等功能
### 3.1.2 接口变动
1.初始化画板sdk
```
// 新增liveId 参数（直播过程中需传入liveId，直播过程中刷新会用到）
rtc.canvasInit({
allowDraw: true, // 是否具有书写画笔权限（讲师权限） true / false
id: 'draw-parent', // 画板区域 id
liveId: 'xxxxx', // 可选项，直播未开始不需要传，直播已开始需要传入（多页白板需要）
});
```
2.变更文档接口新增增加或删除白板功能
```
// 新增白板
var docData = {
action: 'addBoard', //新增白板
};
rtc.docChange(docData);
// 删除白板
var docData = {
action: 'deleteBoard',
data:{
page: num // 删除第几页
}
};
rtc.docChange(docData);
```
3.通知文档变更事件需区分白板和文档
```
rtc.on('flipMessage', function(data){
if(data.action === 'changeDoc'){
// 切换至文档，收到data数据如下
{
action: 'changeDoc',
data:{
id: 'xxxxx', // 文档id
urlArr:[] // 文档每一页的缩略图地址
}
}
// 切换至白板，增加或删除白板，收到data数据如下
{
action: 'changeDoc',
data:{
id: 'xxxx', // 白板id
totalPage: n // 共几页白板
}
}
}
});
```
## 3.2支持ppt动画播放
## 3.2.1 功能描述
支持ppt上传后转化为支持动画的文档，在翻页过程中展示动画
特殊说明：
1.目前ppt动画支持情况：
默认不支持动画
更改房间动画权限后【ppt_support】，支持一般动画权限
[修改房间动画权限](https://doc.bokecc.com/class/developer/classapi/#toc_5)
开通极速权限后，支持极速动画[联系我们修改账号权限]
2.通过mode控制（预计9月20日生效）
mode： 0 不支持动画 1 一般动画 2 极速动画
详细见（1.0 文件上传API）
## 3.3 支持两种文档展示模式
### 3.3.1 功能描述
支持窗口适配和宽度适配两种文档展示模式
### 3.3.2 使用方法
```
// 通过pptDisplay字段控制文档展示样式
rtc.canvasInit({
allowDraw: true, // 是否具有书写画笔权限（讲师权限） true / false
id: 'draw-parent', // 画板区域 id
pptDisplay: 0, // 文档展示方式。默认0，按窗口 1， 按宽度
liveId: 'xxxxx', // 可选项，直播未开始不需要传，直播已开始需要传入（多页白板需要）
});
```
## 3.4支持学生端画笔标注功能
### 3.4.1 功能描述
学生端可以通过调用方法控制自己是否可以标注画板
### 3.3.2 使用方法
```
rtc.drawChange({
action: 'useDraw',
value: true // true 可标注 false不可标注
});
详细使用见（2.12 变更画笔）
```
##3.5 调整部分文档api
情况说明：
之前获取文档需要两个接口，现在修改为1个，上传文档直接上传至账号的机构文档库下，删除文档调用取消关联文档即可
### 3.5.1获取当前文档api只保留一个
获取直播间所有关联的文档API (包含房间内直接上传和服务端关联到该房间的文档)（见1.02）
展示时，需判断文档状态（见demo）
### 3.5.2 本版本弃用删除文档接口， 只保留取消关联文档接口
房间内文档只能取消关联不能删除（见1.04取消关联机构文档库文档API）
###3.5.3 获取单个文档使用场景
上传文档成功后，需要循环查询该文档转码情况（见demo）
## 3.6 切换文档增加参数
切换文档时，新增以下参数，从文档列表中获取该参数
mode: 0, // 0 无动画 1 一般动画 2 极速动画
useSDK：false // false 不支持动画 true 支持动画
详见（2.12 变更画笔）
\ No newline at end of file