跳到主要内容

聊天室属性管理（KV）

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

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

功能局限​

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

开通服务​

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

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

添加聊天室 KV​

方法​

TypeScript

addChatRoomEntry(
  targetId: string, 
  key: string, 
  value: string, 
  deleteWhenLeft: boolean, 
  overwrite: boolean, 
  callback: IRCIMIWAddChatRoomEntryCallback
): Promise<number>;

参数说明​

参数名参数类型描述
targetIdstring聊天室会话 ID
keystring聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valuestring聊天室属性对应的值，最大长度 4096 个字符
deleteWhenLeftboolean用户掉线或退出时，是否自动删除该 Key、Value 值
overwriteboolean如果当前 key 存在，是否进行覆盖
callbackIRCIMIWAddChatRoomEntryCallback接口调用结果回调。

返回值​

返回值描述
number当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例​

TypeScript

const callback = {
    onChatRoomEntryAdded: (code: number) => {
        //...
    },
};
let code = await engine.addChatRoomEntry(targetId, key, value, deleteWhenLeft, overwrite, callback);

添加多个聊天室 KV​

方法​

TypeScript

addChatRoomEntries(
  targetId: string, 
  entries: Map<string, string>, 
  deleteWhenLeft: boolean, 
  overwrite: boolean, 
  callback: IRCIMIWAddChatRoomEntriesCallback
): Promise<number>;

参数说明​

参数名参数类型描述
targetIdstring聊天室会话 ID
entriesMap<string, string>聊天室属性
deleteWhenLeftboolean用户掉线或退出时，是否自动删除该 Key、Value 值
overwriteboolean是否强制覆盖
callbackIRCIMIWAddChatRoomEntriesCallback接口调用结果回调。

返回值​

返回值描述
number当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例​

TypeScript

const callback = {
    onChatRoomEntriesAdded: (code: number, errors: Map<string, number>) => {
        //...
    },
};
let code = await engine.addChatRoomEntries(targetId, entries, deleteWhenLeft, overwrite, callback);

加载聊天室 KV​

方法​

TypeScript

getChatRoomEntry(
  targetId: string, 
  key: string, 
  callback: IRCIMIWGetChatRoomEntryCallback
): Promise<number>;

参数说明​

参数名参数类型描述
targetIdstring聊天室会话 ID
keystring聊天室属性键值
callbackIRCIMIWGetChatRoomEntryCallback接口调用结果回调。

返回值​

返回值描述
number当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例​

TypeScript

const callback = {
    onSuccess: (t: Map<string, string>) => {
        //...
    },
    onError: (code: number) => {
        //...
    },
};
let code = await engine.getChatRoomEntry(targetId, key, callback);

加载某个聊天室所有 KV​

方法​

TypeScript

getChatRoomAllEntries(
  targetId: string, 
  callback: IRCIMIWGetChatRoomAllEntriesCallback
): Promise<number>;

参数说明​

参数名参数类型描述
targetIdstring聊天室会话 ID
callbackIRCIMIWGetChatRoomAllEntriesCallback接口调用结果回调。

返回值​

返回值描述
number当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例​

TypeScript

const callback = {
    onSuccess: (t: Map<string, string>) => {
        //...
    },
    onError: (code: number) => {
        //...
    },
};
let code = await engine.getChatRoomAllEntries(targetId, callback);

移除聊天室 KV​

方法​

TypeScript

removeChatRoomEntry(
  targetId: string, 
  key: string, 
  force: boolean, 
  callback: IRCIMIWRemoveChatRoomEntryCallback
): Promise<number>;

参数说明​

参数名参数类型描述
targetIdstring聊天室会话 ID
keystring聊天室属性键值
forceboolean是否强制删除
callbackIRCIMIWRemoveChatRoomEntryCallback接口调用结果回调。

返回值​

返回值描述
number当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

示例代码​

TypeScript

const callback = {
    onChatRoomEntryRemoved: (code: number) => {
        //...
    },
};
let code = await engine.removeChatRoomEntry(targetId, key, force, callback);

移除聊天室多个 KV​

方法​

TypeScript

removeChatRoomEntries(
  targetId: string, 
  keys: Array<string>, 
  force: boolean, 
  callback: IRCIMIWRemoveChatRoomEntriesCallback
): Promise<number>;

参数说明​

参数名参数类型描述
targetIdstring聊天室会话 ID
keysArray<string>聊天室属性
forceboolean是否强制覆盖
callbackIRCIMIWRemoveChatRoomEntriesCallback接口调用结果回调。

返回值​

返回值描述
number当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例​

TypeScript

const callback = {
    onChatRoomEntriesRemoved: (code: number) => {
        //...
    },
};
let code = await engine.removeChatRoomEntries(targetId, keys, force, callback);

聊天室时 KV 同步完成的回调​

刚加入聊天室时 KV 同步完成的回调

方法​

TypeScript
setOnChatRoomEntriesSyncedListener(listener?: (roomId: string) => void): void;

参数说明​

参数名参数类型描述
roomIdstring聊天室 ID

代码示例​

TypeScript

engine?.setOnChatRoomEntriesSyncedListener((roomId: string) => {
    //...
});

聊天室 KV 变化的回调​

如果刚进入聊天室时存在 KV，会通过此回调将所有 KV 返回，再次回调时为其他人设置或者修改 KV

方法​

TypeScript
setOnChatRoomEntriesChangedListener(listener?: (operationType: RCIMIWChatRoomEntriesOperationType, roomId: string, entries: Map<string, string>) => void): void;

参数说明​

参数名参数类型描述
operationTypeRCIMIWChatRoomEntriesOperationType操作的类型
roomIdstring聊天室 ID
entriesMap<string, string>发送变化的 KV

代码示例​

TypeScript

engine?.setOnChatRoomEntriesChangedListener(
    (operationType: RCIMIWChatRoomEntriesOperationType, roomId: string, entries: Map<string, string>) => {
        //...
    },
);

最后于 更新