跳到主要内容

聊天室属性管理（KV）

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

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

功能局限​

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

开通服务​

使用聊天室属性（KV）接口需要使用聊天室属性自定义设置功能（该功能已默认开通）。

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

设置聊天室 KV 监听器​

调用 addEventListener 方法，设置聊天室 KV 监听器。

提示
  • 事件监听器应全局注册，且仅注册一次，避免重复接收事件通知。
  • 事件回调数据类型为 IChatroomListenerData

示例代码​

JavaScript
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 方法，获取单个属性。

接口​

JavaScript
RongIMLib.getChatRoomEntry(chatRoomId, key)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
keystring是聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符

示例代码​

JavaScript
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)
})

获取所有属性​

调用 getAllChatRoomEntries 方法，获取所有属性。

接口​

JavaScript
RongIMLib.getAllChatRoomEntries(chatRoomId)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID

示例代码​

JavaScript
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 方法，设置属性。

接口​

JavaScript
RongIMLib.setChatRoomEntry(chatRoomId, entry)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
entryIChatroomEntry是设置聊天室属性配置参数

示例代码​

JavaScript
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)
})

强制设置单个属性​

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

接口​

JavaScript
RongIMLib.forceSetChatRoomEntry(chatRoomId, entry)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
entryIChatroomEntry是设置聊天室属性配置参数

示例代码​

JavaScript
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)
})

批量设置属性​

调用 setChatRoomEntries 方法，批量聊天室属性。

接口​

JavaScript
RongIMLib.setChatRoomEntries(chatRoomId, options)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
optionsIChatroomEntries是设置聊天室属性配置参数
提示

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

示例代码​

JavaScript
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)
})

删除单个属性​

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

接口​

JavaScript
RongIMLib.removeChatRoomEntry(chatRoomId, entry)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
entryIRemoveChatroomEntry是聊天室属性

示例代码​

JavaScript
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)
})

强制删除​

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

接口​

JavaScript
RongIMLib.forceRemoveChatRoomEntry(chatRoomId, entry)

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
entryIRemoveChatroomEntry是删除聊天室属性配置参数

示例代码​

JavaScript
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)
})

批量删除​

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

接口​

JavaScript
RongIMLib.removeChatRoomEntries(chatRoomId, options);

参数说明​

参数类型必填说明
chatRoomIdstring是聊天室 ID
optionsobject是删除聊天室属性配置参数
  • options 参数说明
参数类型必填说明
entriesstring[]是聊天室属性名称集合,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
notificationExtrastring否通知自定义字段

示例代码​

JavaScript
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)
})
最后于 更新