房间管理

功能简介

ZIM SDK 提供多人房间聊天功能，支持用户向房间内发送文本消息或自定义消息，实现了多人在线交流、同步分享。

多人房间聊天功能可应用于小班课或者会议室等场景，房间成员数量上限请参考计费说明。

实现流程

用户可以通过以下两种方式，创建房间并进入房间。

方式一：创建房间、加入房间：用户 A 调用 createRoom 接口，传入 ZIMRoomInfo 信息，即可创建并加入房间。其他用户调用 joinRoom 接口，传入由 A 创建的房间 roomID，即可加入房间。
方式二：进入房间：用户 X 调用 enterRoom 接口，传入 ZIMRoomInfo 信息，如果 roomID 不存在，会自动创建一个房间然后进入。其他用户需要调用 enterRoom 接口，传入由 X 创建的房间 roomID，进入房间。

房间内的用户，可以通过 sendRoomMessage 接口，向房间内发送消息，详情请参考收发房间消息。

说明

如果 roomID 已存在：

调用 createRoom 接口，会返回相关错误码，详情请参考常见错误码。
调用 enterRoom 接口，会直接进入此房间内。

如果 roomID 不存在：

调用 createRoom 接口，可以直接创建、并加入到此房间内。
调用 enterRoom 接口，会直接创建一个房间、并进入到此房间内。

创建房间、加入房间

以下流程中，我们以客户端 A 创建并加入房间，客户端 B 加入房间为例。

1. 注册回调

所有进入房间的用户，都需注册 roomMemberJoined、 roomMemberLeft 和 roomStateChanged 回调，用于监听房间其他成员的变动和接收房间连接状态发生改变的事件通知。

Untitled

zim.on('roomMemberJoined', (zim, data) => {
    // to do something
});

Copied!

Untitled

zim.on('roomMemberLeft', (zim, data) => {
    // to do something
});

Copied!

Untitled

zim.on('roomStateChanged', (zim, data) => {
    // to do something
});

Copied!

2. 创建房间

客户端 A 登录后，创建一个房间，可以调用 createRoom 接口，传入 ZIMRoomInfo 信息，即可创建并加入房间。同时可以通过错误码 ZIMError 的参数值，判断是否创建成功。相关错误码请查看常见错误码。

创建成功后会收到 roomStateChanged 的通知回调， ZIMRoomState 为 Connected, ZIMRoomEvent 为 Success 。

注意

“roomID”、“roomName” 支持开发者自定义规则生成。建议开发者将 “roomID” 设置为一个有意义的值，可将其与自己的业务账号系统进行关联。
调用 createRoom 接口创建房间后，会直接加入房间，无需再调用 joinRoom 接口加入房间。

Untitled

var roomInfo = { roomID: '', roomName: '' };
zim.createRoom(roomInfo)
    .then(function ({ roomInfo }) {
        // 操作成功。
    })
    .catch(function (err) {
        // 操作失败。
    });

Copied!

3. 加入房间

客户端 B 加入房间，可以调用 joinRoom 接口，传入由 A 创建的房间 roomID，即可加入房间。同时可以根据错误码 ZIMError 的参数值，判断用户是否加入成功。相关错误码请查看常见错误码。

加入成功后会收到 roomStateChanged 的通知回调， ZIMRoomState 为 Connected , ZIMRoomEvent 为 Success 。

Untitled

var roomID = '';
zim.joinRoom(roomID)
    .then(function ({ roomInfo }) {
        // 操作成功。
    })
    .catch(function (err) {
        // 操作失败。
    });

Copied!

4. 房间成员变动通知

当房间有其他成员加入时，可以使用 on的回调接口 roomMemberJoined 方法，实现对其他房间成员加入的监听。

例如，当客户端 B 加入由 A 创建的房间时，A 将收到房间内成员变动的通知。

Untitled

// 当有新的房间成员加入房间时，用于接收事件通知的回调函数。它还会返回刚刚加入房间的用户信息。
zim.on('roomMemberJoined', function (zim, { roomID, memberList }) {
    console.log(roomID, memberList);
});

Copied!

进入房间

以下流程中，我们以客户端 X 创建并进入房间，客户端 Y 直接进入房间为例。

注册 roomMemberJoined、 roomMemberLeft 和 roomStateChanged 回调，详情请参考创建房间、加入房间 - 1. 注册回调。
客户端 X 登录后，调用 enterRoom 接口，传入 ZIMRoomInfo 信息，进入房间；如果传入的 roomID 不存在，将会自动创建一个房间并进入该房间。
客户端 Y 登录后，调用 enterRoom 接口，传入由 X 创建的房间 roomID，直接进入房间。
进入房间成功后会收到 roomStateChanged 的通知回调， ZIMRoomState 为 Connected , ZIMRoomEvent 为 Success。
房间内的用户，同样可以使用 on的的回调接口 roomMemberJoined 方法，实现对房间内成员加入的监听。

Untitled

var roomInfo = { roomID: '', roomName: '' };
zim.enterRoom(roomInfo)
    .then(function ({ roomInfo }) {
        // 操作成功。
    })
    .catch(function (err) {
        // 操作失败。
    });

// 当有新的房间成员加入房间时，接收事件通知的回调函数。它还返回刚刚加入房间的用户信息。
zim.on('roomMemberJoined', function (zim, { roomID, memberList }) {
    console.log(roomID, memberList);
});

Copied!

切换房间

如果用户想要从一个房间切换至另一个房间，可以调用 switchRoom 接口，传入原房间的 ID（fromRoomID）以及目标房间信息（toRoomInfo，含房间 ID 和房间名称），即可切换房间。

然而，可能因目标房间不存在而导致房间切换失败。如需避免这种失败，也可以在调用 switchRoom 接口时，传入 isCreateWhenRoomNotExisted 为 true（允许 ZIM 在房间不存在时创建新房间）和 config （用于配置新房间）。如此，当 ZIM 判断目标房间不存在时，就会根据 toRoomInfo 和 config（如有）创建新房间用于切换。

房间切换成功后，原房间内的其他用户可通过 on的的回调接口 roomMemberLeft ，得知有用户离开房间；目标房间内的其他用户可通过 on的的回调接口 roomMemberJoined ，得知有用户进入了房间。

完整流程请参考下图：
示例代码：

Untitled

const fromRoomID = 'fromRoomID';
const toRoomInfo = { roomID: 'toRoomID', roomName: 'toRoomName' };
const isCreateWhenRoomNotExisted = true;
// 创建房间的高级配置
const to_room_attr = {
    key1: 'value1', // 将此代码替换为实际的键值对
    key2: 'value2', // 另一个键值对
    // 可以添加更多的键值对
};

// 设置房间销毁延迟时间（以秒为单位）
const to_room_delay_destroy_time = 90; 

const config = {
    roomAttributes: to_room_attr,
    roomDestroyDelayTime: to_room_delay_destroy_time,
};

zim.switchRoom(fromRoomID, toRoomInfo, isCreateWhenRoomNotExisted, config)
    .then(function (res) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

Copied!

离开房间

用户如果想要离开房间，可以调用 leaveRoom 接口，传入房间的 roomID，即可退出此房间；房间内的其他用户可以通过 on的的回调接口 roomMemberLeft ，收到成员变动通知。

离开房间成功后会收到 roomStateChanged 的通知回调， ZIMRoomState 为 Disconnected ， ZIMRoomEvent 为 Success 。

离开房间后，将不能收到房间内的消息。

Untitled

var roomID = '';
zim.leaveRoom(roomID)
    .then(function ({ roomID }) {
        // 操作成功。
    })
    .catch(function (err) {
        // 操作失败。
    });

Copied!

Untitled

// 当现有房间成员离开房间时，用于接收事件通知的回调函数。它还返回刚刚离开房间的用户的信息。
zim.on('roomMemberLeft', function (zim, { roomID, memberList }) {
    console.log(roomID, memberList);
});

Copied!

说明

当所有成员离开房间后，房间将自动销毁。ZIM SDK 支持通过 config 设置房间延迟销毁，最大延迟为 3 小时。

退出所有房间

调用 leaveAllRoom 接口，即可立即离开当前加入的所有房间，并返回离开的房间列表。如果用户多端登录，则用户在一端调用此接口后，仅会退出在该端上加入的房间，在其他端加入的房间不受影响。

Untitled

var roomIDs = [];
zim.leaveAllRoom(roomIDs)
    .then(function ({ roomIDs }) {
        // 操作成功。
    })
    .catch(function (err) {
        // 操作失败。
    });

Copied!

房间内的其他用户可以通过 on的的回调接口 roomMemberLeft ，收到成员变动通知。

退出所有房间成功后，用户会根据所离开房间的数量，多次收到 roomStateChanged 的通知回调， ZIMRoomState 为 Disconnected ， ZIMRoomEvent 为 Success 。

离开房间后，将不能收到房间内的消息。

销毁房间

开发者可以在后台调用 ZIM 服务端接口进行销毁房间。房间被销毁后，用户通过 roomStateChanged 收到房间状态（ ZIMRoomState ）从 Connected 转变为 Disconnected 的事件通知。根据 ZIM SDK 版本不同，回调中描述导致房间连接状态发生变更的事件（ ZIMRoomEvent ）如下所示：

当 ZIM SDK 版本小于 2.13.0 时，事件为 KickedOut 。
当 ZIM SDK 版本为 2.13.0 及之后版本时，事件为 RoomNotExist 。

网络中断对房间生命周期的影响

ZIM 房间类似于在线聊天室、网络中断会导致房间进入重连状态并抛出 roomStateChanged 。详情请参考场景 4 : ZIM 房间断网。