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

聊天室属性管理(KV)

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

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

功能局限

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

开通服务

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

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

设置聊天室 KV 监听器

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

调用 addEventListener

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 获取单个属性。

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 获取所有属性。

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 设置属性。

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 已经存在时,代表更新属性的值。使用强制设置可修改他人创建的属性值。

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 批量聊天室属性。

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 删除聊天室自定义属性。只可删除当前用户所创建的属性。

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 强制删除聊天室自定义属性。可删除他人所创建的属性。

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 批量删除聊天室属性。

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 个字符