房间属性管理

功能简介

ZIM SDK 的房间属性功能，提供了可在指定房间中，设置自定义属性的能力。

通常可以应用在语音直播、聊天室等的属性同步、语聊房的麦位管理、以及狼人杀等卡牌类游戏中，记录用户的角色和牌局状态等场景中。

实现流程

开发者需要在调用 createRoom 接口时，设置房间属性参数，创建并加入房间。

注意

每个房间中，最多允许设置 20 个属性，以 Key-Value 的方式进行存储。Key的长度上限为 16 字节，Value的长度上限为 1024 字节，所有属性的总长度不得超过 5120 字节。开发者如果需要提高属性上限，请联系 ZEGO 技术支持。
房间销毁后，设置的自定义属性也会同时销毁。

示例代码

// roomID 最大 128 字节的字符串。仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。
// roomName 最大 64 字节的字符串，无特殊字符限制。
var roomInfo = { roomID: '', roomName: '' };
var config = { 
    roomAttributes: { key1: 'value1', key2: 'value2' }
};

zim.createRoom(roomInfo, config)
    .then(function ({ roomInfo }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

Copied!

设置房间属性

每个房间中，设置的属性以 Key-Value 的形式存储。

当 Key 不存在时，设置房间属性表示增加属性。
当 key 已经存在时，设置房间属性表示更新已有属性的取值。

示例代码

var roomID = '';
var roomAttributes = { key1: 'value1', key2: 'value2' };
var config = { 
    isForce: false,
    isUpdateOwner: false,
    isDeleteAfterOwnerLeft: false
};

zim.setRoomAttributes(roomAttributes, roomID, config)
    .then(function ({ roomID, errorKeys }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 设置 roomAttributesUpdated 回调
zim.on('roomAttributesUpdated', function (zim, { roomID, infos }) {
    console.log(''roomAttributesUpdated'', roomID, infos);
});

Copied!

删除房间属性

通常开发者只能删除自己拥有的属性，也可以设置 “config” 中的 “isForce” 参数取值，删除他人创建的属性。

示例代码

var roomID = '';
var keys = ['key1'];
var config = { 
    isForce: false
};

zim.deleteRoomAttributes(keys, roomID, config)
    .then(function ({ roomID, errorKeys }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 设置 roomAttributesUpdated 回调
zim.on('roomAttributesUpdated', function (zim, { roomID, infos }) {
    console.log(''roomAttributesUpdated'', roomID, infos);
});

Copied!

获取房间属性

注意

登录房间时，房间最新属性将通过 roomAttributesUpdated 回调返回，无需调用 queryRoomAllAttributes 。

示例代码

var roomID = '';
zim.queryRoomAllAttributes(roomID)
    .then(function ({ roomID, roomAttributes }) {
        // 查询成功
    })
    .catch(function (err) {
        // 查询失败
    });

Copied!

房间属性组合操作

组合操作可以使用 beginRoomAttributesBatchOperation 和 endRoomAttributesBatchOperation 方法将同一房间中，多个不同操作合并为一个原子操作进行执行，通常用于连续操作时不想被其他用户操作插入执行的情况。

示例代码

var roomID = '';
var config = { 
    isForce: false,
    isUpdateOwner: false,
    isDeleteAfterOwnerLeft: false
};

// 开始 批量操作
zim.beginRoomAttributesBatchOperation(roomID, config);

// 批量操作时，使用 `Promise.then` 获取操作结果。请不要使用 `async-await` 等待操作结果。
var roomAttributes = { key1: 'value1', key2: 'value2' };
zim.setRoomAttributes(roomAttributes, roomID, config)
   .then(function ({ roomID, errorKeys }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 批量操作时，使用 `Promise.then` 获取操作结果。请不要使用 `async-await` 等待操作结果。
var keys = ['key1'];
zim.deleteRoomAttributes(keys, roomID, config)
   .then(function ({ roomID, errorKeys }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 结束 批量操作
zim.endRoomAttributesBatchOperation(roomID)
    .then(function ({ roomID }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 设置 roomAttributesBatchUpdated 回调
zim.on('roomAttributesBatchUpdated', function (zim, { roomID, infos }) {
    console.log(''roomAttributesBatchUpdated'', roomID, infos);
});

Copied!