统一页面控制

  • iOS

更新时间

适用于 Whiteboard iOS SDK 2.16.147。

多窗口模式通过同一套接口控制主白板和课件。先完成加入白板房间,并等待入房成功;业务发起翻页、缩放以及新增或移除主白板页面还需要可写权限。

目标与操作

目标target 输入支持操作
MainView 主白板mainView前后页、跳页、缩放;新增、移除页面使用独立 API;不支持动画步骤
Slide 动态 PPT该窗口的 appId前后页、跳页、前后动画步骤、缩放(先启用 Slide 的 enableScale)
Presentation 静态 PPT该窗口的 appId前后页、跳页、缩放;不支持动画步骤
DocsViewer 文档该窗口的 appId前后页、跳页;不支持 scalePage
表格内容超出当前宽度,可横向滚动查看更多列。

省略 target 时跟随当前焦点,没有焦点时使用 MainView。不能把 Slide 或 Presentation 类型名当作 appId。查询结果的 target 则是 mainView、Slide、Presentation、DocsViewer 之一,用于标识目标类型。

下表列出 dispatchDocsEvent 支持的命令;新增和移除页面使用下文的独立 API。

命令用途与参数
prevPage / nextPage前一页 / 后一页
prevStep / nextStep前一动画步骤 / 后一动画步骤
jumpToPagepage 为从 1 开始的整数,不能直接使用零基场景索引
scalePagescale 为相对适配倍率,1 表示适配大小;可选范围由 pageScaleRange 约束
表格内容超出当前宽度,可横向滚动查看更多列。

新增与移除主白板页面

以下公开 API 固定操作 MainView 主白板的场景页,不受当前焦点或 target 影响,也不用于增加或删除课件源文件中的页面。先完成多窗口入房并取得可写权限。dispatchDocsEvent 不接受 addPage、removePage 命令。

通过已入房的 WhiteRoom *room 调用。

操作WhiteRoom 公开 API(Objective-C selector)参数与结果
当前页之后新增空白页addPage / addPage:无参数形式或传入完成回调;默认插入到主白板当前页之后
指定位置新增页面addPageWithScene:afterCurrentScene: / addPageWithScene:afterCurrentScene:completionHandler:scene 可为 nil;afterCurrentScene = YES 插到当前页之后,NO 追加到末尾;带回调形式用 BOOL success 返回结果
移除当前页面removePage:传入完成回调,删除主白板当前页
移除指定页面removePage:completionHandler:第一个参数为从 0 开始的 NSUInteger 索引。success = YES 表示成功;仅剩一页、索引越界或调用异常时为 NO
表格内容超出当前宽度,可横向滚动查看更多列。

下面分别定义新增和删除按钮的处理逻辑:

Objective-C
void (^addMainViewPage)(void) = ^{
    [room addPageWithScene:nil afterCurrentScene:YES
         completionHandler:^(BOOL success) {
        if (!success) NSLog(@"新增页面失败");
    }];
};

void (^removeFirstMainViewPage)(void) = ^{
    [room removePage:0 completionHandler:^(BOOL success) {
        if (!success) NSLog(@"页面未删除,请检查页数与索引");
    }];
};
// 在对应按钮处理方法中调用 addMainViewPage() 或 removeFirstMainViewPage()。

新增页面后不会自动跳到新页,需要时再发送指定 target: "mainView" 的跳页命令。主白板至少保留一页;仅剩一页时不能删除。

索引区别: 删除 API 的 index 从 0 开始,index = 0 表示第一页;dispatchDocsEvent("jumpToPage", ...) 的 page 从 1 开始。传入待删除页索引前,请确认主白板的实际页数。

发送命令与主动查询

Objective-C
WhiteWindowDocsEventOptions *options = [WhiteWindowDocsEventOptions new];
options.target = appId;
options.page = @2;
[room dispatchDocsEvent:WhiteWindowDocsEventJumpToPage options:options
     completionHandler:^(WhiteDispatchDocsEventResult *result) {
    if (!result.accepted) NSLog(@"%@ %@", result.reason, result.message);
}];
WhiteWindowPageStateOptions *query = [WhiteWindowPageStateOptions new];
query.target = appId;
[room getPageState:query completionHandler:^(WhiteUnifiedPageState *state, NSError *error) {
    if (error) { NSLog(@"%@", error); return; }
    NSLog(@"page=%ld/%ld scale=%@", (long)state.page, (long)state.pageCount, state.scale);
}];

dispatchDocsEvent 的 accepted 只表示命令被接收;accepted=false 时读取 reason/message。Bridge 或宿主异常走 Promise 拒绝或原生错误回调。原因码包括 invalidEvent、invalidOptions、targetNotFound、targetNotSupported、eventNotSupported、notWritable、stateUnavailable、outOfRange、commandFailed。

getPageState 主动查询可观察的状态,不会触发翻页。返回 page/pageCount(从 1 开始)、target、可选 appId 与 scale。尚未完成初始化或状态确认时可能失败;可等待状态事件后再次查询,或设置有限重试次数与截止时间。

监听实际页码与缩放

Objective-C
// 在 joinRoom 时传入的 WhiteRoomCallbackDelegate 对象中实现:
- (void)onUnifiedPageStateChange:(WhiteUnifiedPageStateChange *)state {
    if ([state.status isEqualToString:@"failure"]) {
        NSLog(@"%@ %@", state.reason, state.message); return;
    }
    NSLog(@"type=%@ page=%ld scale=%@", state.changeType, (long)state.page, state.scale);
}

宿主保持 delegate 存活,离开房间后停止更新已销毁的页面。

观察事件的 status 为 pending/success;changeType: page 表示页变化,changeType: scale 表示缩放变化;旧兼容事件可能省略 changeType。异步执行失败时 status=failure,并包含 event、reason 和可选 message。不要从失败事件读取有效页码/倍率。

主动读取倍率使用 getPageState 返回的 scale;该值可能不存在,且它不是主白板相机的绝对 camera.scale。命令接收、焦点提交和页状态通知都不能代替课件全部资源或首帧完成信号。

与 WindowManager 示例的对应关系

WindowManager example 中 dispatchUnifiedDocsEvent 包装正式 dispatchDocsEvent,queryUnifiedPageState 包装正式 getPageState。scaleChangeEvent 是示例保存缩放通知的 UI 状态变量,来自 unifiedPageStateChange 中 changeType=scale 的消息。这三个示例名称均不是可从 SDK 导入的独立方法或事件。

需要统一主白板与课件的书写参考尺寸时,继续阅读统一笔记。