跳到主要内容
版本：5.X

聊天室属性管理（KV）

聊天室属性（KV）管理接口用于在指定聊天室中设置自定义属性。

在语音直播聊天室场景中，可利用此功能记录聊天室中各麦位的属性；或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。

功能局限​

提示
  • 聊天室销毁后，聊天室中的自定义属性同时销毁。
  • 每个聊天室中，最多允许设置 100 个属性信息，以 Key-Value 的方式进行存储。
  • 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室，每秒钟操作 Key-Value 频率保持在 100 次及以下（一秒内单次操作 100 个 KV 等同于操作 100 次）。

开通服务​

使用聊天室属性（KV）接口要求开通聊天室属性自定义设置服务。您可以前往控制台的免费基础功能页面开启服务。

如果配置了服务端回调 URL，融云服务端会将应用下的聊天室属性变化（设置，删除，全部删除等操作）同步到指定的回调地址。详见服务端文档聊天室属性同步（KV）。

设置聊天室 KV 监听器​

调用示例： addEventListener(Events.CHATROOM, listener)

调用 addEventListener

js
const listener = (event) => {
  if (event.rejoinedRoom) {
    console.log('SDK 内部重连聊天室信息:', event.rejoinedRoom)
  }
  if (event.updatedEntries) {
    console.log('监听到的聊天室 KV 更新:', event.updatedEntries)
  }
  if (event.userChange) {
    console.log('加入退出的用户通知:', event.userChange)
  }
  if (event.chatroomDestroyed) {
    console.log('聊天室销毁:', event.chatroomDestroyed)
  }
}
RongIMLib.addEventListener(Events.CHATROOM, listener)

获取单个属性​

调用 getChatRoomEntry 获取单个属性。

js
const chatRoomId = "聊天室 ID";
const key = "name";

RongIMLib.getChatRoomEntry(chatRoomId, key).then(res => {
    // 获取聊天室单个属性成功
    if (res.code === 0) {
        console.log(res.code, res.data)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdstring聊天室 ID
keystring聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符

获取所有属性​

调用 getAllChatRoomEntries 获取所有属性。

js
const chatRoomId = "聊天室 ID";
RongIMLib.getAllChatRoomEntries(chatRoomId).then(res => {
    // 获取聊天室所有属性成功
    if (res.code === 0) {
        console.log(res.code, res.data)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

设置单个属性​

调用 setChatRoomEntry 设置属性。

js
const entry = {
    key: 'key',
    value: 'value',
    notificationExtra: 'extra',
    isAutoDelete: true,
    isSendNotification: false
}
RongIMLib.setChatRoomEntry(chatRoomId, entry).then(res => {
    // 设置聊天室单个属性成功
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valueString聊天室属性对应的值，最大长度 4096 个字符
isSendNotificationBoolean设置成功后是否发送通知消息
isAutoDeleteBoolean用户退出聊天室时是否清除此属性
notificationExtraStringRC:chrmKVNotiMsg 消息中携带的附加信息

强制设置单个属性​

强制设置单个聊天室属性。可用于修改他人创建的属性值。调用 forceSetChatRoomEntry 强制设置聊天室属性。以 key = value 的形式存储。当 key 不存在时，代表增加属性； 当 key 已经存在时，代表更新属性的值。使用强制设置可修改他人创建的属性值。

js
const entry = {
    key: 'key',
    value: 'value',
    notificationExtra: 'extra',
    isAutoDelete: true,
    isSendNotification: false
}
RongIMLib.forceSetChatRoomEntry(chatRoomId, entry).then(res => {
    // 强制设置聊天室单个属性成功
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称。Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valueString聊天室属性对应的值，最大长度 4096 个字符
isSendNotificationBoolean设置成功后是否发送通知消息
isAutoDeleteBoolean用户退出聊天室时是否清除此属性
notificationExtraStringRC:chrmKVNotiMsg 消息中携带的附加信息

批量设置属性​

提示

从 SDK 5.3.4 版本开始，该接口同时支持通过 isForce 属性强制设置多个属性值。强制设置可直接覆盖他人创建的属性值。

调用 setChatRoomEntries 批量聊天室属性。

js
const entries = [{key: '',value: ''}]
const options = {
    entries,
    isAutoDelete:true, // 用户退出聊天室时是否清除此属性
    isForce: true // 是否强制覆盖
}
RongIMLib.setChatRoomEntries(chatRoomId, options).then(res => {
    // 设置聊天室属性成功
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdString聊天室 ID
options.entriesArray聊天室属性键值对集合, Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符，聊天室属性对应的值，最大长度 4096 个字符
options.isAutoDeleteBoolean用户退出聊天室时是否清除此属性
options.isForceBoolean是否强制覆盖（该属性要求 SDK 版本 ≧ 5.3.4）

删除单个属性​

调用 removeChatRoomEntry 删除聊天室自定义属性。只可删除当前用户所创建的属性。

js
const chatRoomId = '聊天室ID'
const entry = {
    key: key,
    notificationExtra: extra,
    isSendNotification: isSendNotification
}
RongIMLib.removeChatRoomEntry(chatRoomId, entry).then(res => {
    // 删除聊天室单个属性成功
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
isSendNotificationBoolean设置成功后是否发送通知消息
notificationExtraStringRC:chrmKVNotiMsg 消息中携带的附加信息

强制删除​

调用 forceRemoveChatRoomEntry 强制删除聊天室自定义属性。可删除他人所创建的属性。

js
const chatRoomId = '聊天室ID'
const entry = {
    key: key,
    notificationExtra: extra,
    isSendNotification: isSendNotification
}
RongIMLib.forceRemoveChatRoomEntry(chatRoomId, entry).then(res => {
    // 强制删除聊天室属性成功
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
isSendNotificationBoolean设置成功后是否发送通知消息
notificationExtraStringRC:chrmKVNotiMsg 消息中携带的附加信息

批量删除​

调用 removeChatRoomEntries 批量删除聊天室属性。

js
const chatRoomId = '聊天室ID'
RongIMLib.removeChatRoomEntries(chatRoomId, {
    entries: ['']
}).then(res => {
    // 删除聊天室属性成功
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})
参数类型说明
chatRoomIdString聊天室 ID
options.entriesArray聊天室属性名称集合,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
最后于 更新