聊天室队列管理 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

聊天室队列管理

更新时间： 2024/12/05 17:15:18

网易云信 IM 支持聊天室队列服务，包括初始化队列、添加\更新队列元素、清空队列等操作。

聊天室队列，其本质是一个键值对的存储，可以用于存储麦位管理等逻辑。

本文内容适用的开发平台或框架如下表所示：

Android	iOS	macOS/Windows	Web/uni-app/小程序	Node.js/Electron	HarmonyOS	Flutter
✔️️️️	✔️️️️	✔️️️️	✔️️️️	✔️️️️	✔️	-

技术原理

使用聊天室队列服务需要权限，其权限通过 queueLevelMode 来控制。若为 ANY，则所有聊天室成员都可以操作队列；若为 MANAGER，则只有聊天室创建者和管理员才能操作队列。

您可以通过 updateChatroomInfo 方法修改 queueLevelMode 权限模式，具体请参考修改聊天室信息。

前提条件

在使用聊天室队列服务中的 API 前，需要先调用 getChatroomQueueService 方法获取聊天室队列服务类。

聊天室队列相关事件监听

在进行聊天室队列相关操作前，您可以先注册监听聊天室队列相关事件。监听后，在进行聊天室队列管理操作后，会收到对应的通知。

相关回调：

onChatroomQueueOffered：聊天室新增队列元素回调。在聊天室队列中新增元素成功后，SDK 会返回该回调。
onChatroomQueuePolled：聊天室取出（移除）队列元素回调。在聊天室队列中取出（移除）元素会触发该回调。
onChatroomQueueDropped：聊天室清空队列元素回调。聊天室队列中的元素被清空会触发该回调。
onChatroomQueuePartCleared：聊天室清理部分队列元素回调。聊天室队列中的部分元素被清理时会触发该回调。
onChatroomQueueBatchUpdated：聊天室批量更新队列元素回调。当聊天室队列中的元素被批量更新时会触发该回调。
onChatroomQueueBatchOffered：聊天室批量添加队列元素回调。当聊天室队列中批量添加元素时会触发该回调。

Android/iOS/macOS/Windows

调用 addQueueListener 注册聊天室队列相关监听器，监听队列变更、清除等事件。

示例代码如下：

Android

JavaV2NIMChatroomQueueListener queueListener = new V2NIMChatroomQueueListener() {
    @Override
    public void onChatroomQueueOffered(V2NIMChatroomQueueElement element) {
        //新增队列元素
    }

    @Override
    public void onChatroomQueuePolled(V2NIMChatroomQueueElement element) {
        //删除队列元素
    }

    @Override
    public void onChatroomQueueDropped() {
        //队列被清空
    }   

    @Override
    public void onChatroomQueuePartCleared(List<V2NIMChatroomQueueElement> elements) {
        //部分队列元素被清除
    }

    @Override
    public void onChatroomQueueBatchUpdated(List<V2NIMChatroomQueueElement> elements) {
        //批量更新队列元素
    }

    @Override
    public void onChatroomQueueBatchOffered(List<V2NIMChatroomQueueElement> elements) {
        //批量新增队列元素
    }
};
//设置队列服务监听可以在进入聊天室之前就设置
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
chatroomQueueService.addQueueListener(queueListener);

iOS

Objective-C@interface MyQueueListener : NSObject<V2NIMChatroomQueueListener>
@end
@implementation MyQueueListener

- (void)onChatroomQueueOffered:(V2NIMChatroomQueueElement *)element
{
    // 聊天室新增队列元素
}
- (void)onChatroomQueuePolled:(V2NIMChatroomQueueElement *)element
{
    // 聊天室移除队列元素
}
- (void)onChatroomQueueDropped
{
    // 聊天室清空队列元素
}
- (void)onChatroomQueuePartCleared:(NSArray<V2NIMChatroomQueueElement *> *)elements
{
    // 聊天室清理部分队列元素
}
- (void)onChatroomQueueBatchUpdated:(NSArray<V2NIMChatroomQueueElement *> *)elements
{
    // 聊天室批量更新队列元素
}
- (void)onChatroomQueueBatchOffered:(NSArray<V2NIMChatroomQueueElement *> *)elements
{
    // 聊天室批量添加队列元素
}
@end
MyQueueListener *queueListener = [[MyQueueListener alloc] init];
//设置队列服务监听可以在进入聊天室之前就设置
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
[chatroomQueueService addQueueListener:queueListener];

macOS/Windows

C++V2NIMChatroomQueueListener listener;
listener.onChatroomQueueOffered = [](const V2NIMChatroomQueueElement& element) {
   // handle event
};
listener.onChatroomQueuePolled = [](const V2NIMChatroomQueueElement& element) {
   // handle event
};
listener.onChatroomQueueDropped = []() {
   // handle event
};
listener.onChatroomQueuePartCleared = [](const std::vector<V2NIMChatroomQueueElement>& keyValues) {
   // handle event
};
listener.onChatroomQueueBatchUpdated = [](const std::vector<V2NIMChatroomQueueElement>& keyValues) {
   // handle event
};
listener.onChatroomQueueBatchOffered = [](const std::vector<V2NIMChatroomQueueElement>& keyValues) {
   // handle event
};
chatroomQueueService.addQueueListener(listener);

Web/uni-app/小程序/Node.js/Electron/HarmonyOS

调用 on("EventName") 注册聊天室队列相关监听器，监听队列变更、清除等事件。

Web/uni-app/小程序

TypeScriptchatroom.V2NIMChatroomQueueListener.on('onChatroomQueueBatchOffered', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.V2NIMChatroomQueueListener.on('onChatroomQueueBatchUpdated', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.V2NIMChatroomQueueListener.on('onChatroomQueueOffered', function (element: V2NIMChatroomQueueElement) {})
chatroom.V2NIMChatroomQueueListener.on('onChatroomQueuePartCleared', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.V2NIMChatroomQueueListener.on('onChatroomQueuePolled', function (element: V2NIMChatroomQueueElement) {})
chatroom.V2NIMChatroomQueueListener.on('onChatroomQueueDropped', function () {})

Node.js/Electron

TypeScriptchatroom.chatroomQueueListener.on('chatroomQueueBatchOffered', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.chatroomQueueListener.on('chatroomQueueBatchUpdated', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.chatroomQueueListener.on('chatroomQueueOffered', function (element: V2NIMChatroomQueueElement) {})
chatroom.chatroomQueueListener.on('chatroomQueuePartCleared', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.chatroomQueueListener.on('chatroomQueuePolled', function (element: V2NIMChatroomQueueElement) {})
chatroom.chatroomQueueListener.on('chatroomQueueDropped', function () {})

HarmonyOS

TypeScriptchatroom.on('onChatroomQueueBatchOffered', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.on('onChatroomQueueBatchUpdated', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.on('onChatroomQueueOffered', function (element: V2NIMChatroomQueueElement) {})
chatroom.on('onChatroomQueuePartCleared', function (elements: V2NIMChatroomQueueElement[]) {})
chatroom.on('onChatroomQueuePolled', function (element: V2NIMChatroomQueueElement) {})
chatroom.on('onChatroomQueueDropped', function () {})

初始化队列

调用 queueInit 方法初始化聊天室队列。

示例代码如下：

Android

Java//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
chatroomQueueService.queueInit(100, new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        //success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //failed
    }
});

iOS

Objective-C//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
[chatroomQueueService queueInit:100 success:^() {
    //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++chatroomQueueService.queueInit(100, []() {
    // success
}, [](const V2NIMError& error) {
    // handle error
});

Web/uni-app/小程序

TypeScriptawait chatroom.V2NIMChatroomQueueService.queueInit(100)

Node.js/Electron

TypeScriptawait chatroomQueueService.queueInit(100)

HarmonyOS

TypeScriptawait chatroom.queueService.queueInit(100)

新增/更新队列元素

调用 queueOffer 方法在队列中新增或更新元素。

新增或更新元素成功后，会触发 onChatroomQueueOffered 回调。

示例代码如下：

Android

JavaV2NIMChatroomClient v2NIMChatroomClient = V2NIMChatroomClient.newInstance();
V2NIMChatroomEnterParams enterParams = getEnterParams();
v2NIMChatroomClient.enter("100", enterParams, new V2NIMSuccessCallback<V2NIMChatroomEnterResult>() {
    @Override
    public void onSuccess(V2NIMChatroomEnterResult v2NIMChatroomEnterResult) {
        //进入聊天室成功
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //进入聊天室失败
    }
});

……

//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClientv2NIMChatroomClient.getChatroomQueueService();

V2NIMChatroomQueueOfferParams offerParams = new V2NIMChatroomQueueOfferParams("key1","value1");
//设置元素是否为瞬态的,true表示元素是瞬态的,当前元素所属的成员退出或者掉线时会同步删除;false表示元素是持久的,会被保留
offerParams.setTransient(true);
//设置元素属于的账号,默认为当前操作者,管理员操作可以指定元素属于的合法账号
offerParams.setElementOwnerAccountId("other account");
chatroomQueueService.queueOffer(offerParams, new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        //success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //failed
    }
});

iOS

Objective-CV2NIMChatroomClient *client = [V2NIMChatroomClient newInstance];
V2NIMChatroomEnterParams *enterParams = [[V2NIMChatroomEnterParams alloc] init];
[client enter:@"100" enterParams:enterParams success:^(V2NIMChatroomEnterResult *result) {
    //进入聊天室成功
} failure:^(V2NIMError *error) {
    //进入聊天室失败
}];

……

//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];

V2NIMChatroomQueueOfferParams *offerParams = [[V2NIMChatroomQueueOfferParams alloc] init];
offerParams.elementKey = @"key";
offerParams.elementValue = @"value";
//设置元素是否为瞬态的。YES表示元素是瞬态的,当前元素所属的成员退出或者掉线时会同步删除;NO表示元素是持久的,会被保留
offerParams.transient = YES;
//设置元素属于的账号,默认为当前操作者,管理员操作可以指定元素属于的合法账号
offerParams.elementOwnerAccountId = @"other account";
[chatroomQueueService queueOffer:offerParams success:^() {
        //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++V2NIMChatroomQueueOfferParams params;
params.key = "key";
params.value = "value";
chatroomQueueService.queueOffer(params, []() {
   // success
}, [](const V2NIMError& error) {
   // handle error
});

Web/uni-app/小程序

TypeScriptawait chatroom.V2NIMChatroomQueueService.queueOffer(
  {
    "elementKey": "key5",
    "elementValue": "value5",
    "transient": false,
    "elementOwnerAccountId": "YOUR_ACCOUNT_ID"
  }
)

Node.js/Electron

TypeScriptawait chatroomQueueService.queueOffer({
    elementKey: 'your element key',
    elementValue: 'your element value'
})

HarmonyOS

TypeScriptawait chatroom.queueService.queueOffer(
  {
    "elementKey": "key5",
    "elementValue": "value5",
    "transient": false,
    "elementOwnerAccountId": "YOUR_ACCOUNT_ID"
  }
)

批量更新队列元素

调用 queueBatchUpdate 方法批量更新队列元素。

批量更新成功后，会触发 onChatroomQueueBatchUpdated 回调。

示例代码如下：

Android

Java//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
//待更新队列元素列表
List<V2NIMChatroomQueueElement> elements = new ArrayList<>();
elements.add(new V2NIMChatroomQueueElement("key1", "value1 new"));
elements.add(new V2NIMChatroomQueueElement("key2", "value2 new"));
//是否发送广播通知
boolean notificationEnabled = true;
//本次操作生成的通知中的扩展字段
String notificationExtension = "notificationExtension";
chatroomQueueService.queueBatchUpdate(elements, notificationEnabled, notificationExtension, new V2NIMSuccessCallback<List<String>>() {
    @Override
    public void onSuccess(List<String> result) {
        //success，result is non-existent element key list
        
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //failed
    }
});

iOS

Objective-C//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
//待更新队列元素列表
NSMutableArray<V2NIMChatroomQueueElement *> *elements = [NSMutableArray array];
V2NIMChatroomQueueElement* element;
element = [[V2NIMChatroomQueueElement alloc] init];
element.key = @"key1";
element.value = @"value1 new";
[elements addObject:element];

element = [[V2NIMChatroomQueueElement alloc] init];
element.key = @"key1";
element.value = @"value1 new";
[elements addObject:element];

//是否发送广播通知
BOOL notificationEnabled = YES;
//本次操作生成的通知中的扩展字段
NSString *notificationExtension = @"notificationExtension";
[chatroomQueueService queueBatchUpdate:elements notificationEnabled:notificationEnabled notificationExtension:notificationExtension success:^(NSArray<NSString *> *result) {
    //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++V2NIMChatroomQueueElement element;
element.key = "key";
element.value = "value";
nstd::vector<V2NIMChatroomQueueElement> elements;
elements.push_back(element);
chatroomQueueService.queueBatchUpdate(elements, true, "notificationExtension", [](const nstd::vector<nstd::string>& failedKeys) {
    // success
}, [](const V2NIMError& error) {
    // handle error
});

Web/uni-app/小程序

TypeScript const invalidKeys = await chatroom.V2NIMChatroomQueueService.queueBatchUpdate([
   {
     "key": "key1",
     "value": "valueA"
   },
   {
     "key": "key2",
     "value": "valueB"
   }
 ], true, 'An extension')
 
 console.log(invalidKeys) // ["key2"], because "key2" is not exist

Node.js/Electron

TypeScriptconst elementKeys = await chatroomQueueService.queueBatchUpdate([{
    elementKey: 'your element key',
    elementValue: 'your element value'
}], true, 'your notification extension')

HarmonyOS

TypeScriptconst invalidKeys = await chatroom.queueService.queueBatchUpdate([
{
    "key": "key1",
    "value": "valueA"
},
{
    "key": "key2",
    "value": "valueB"
}
], true, 'An extension')

console.log(invalidKeys) // ["key2"], because "key2" is not exist

取出指定的队列元素

调用 queuePoll 方法取出队列中的指定元素。若未指定元素，则默认取出队列的头元素。

取出成功后，会触发 onChatroomQueuePolled 回调。

示例代码如下：

Android

Java//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
chatroomQueueService.queuePoll("key1", new V2NIMSuccessCallback<V2NIMChatroomQueueElement>() {
    @Override
    public void onSuccess(V2NIMChatroomQueueElement element) {
       //success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //failed
    }
});

iOS

Objective-C//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
[chatroomQueueService queuePoll:@"key1" success:^(V2NIMChatroomQueueElement *result) {
    //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++chatroomQueueService.queuePoll("key", [](const V2NIMChatroomQueueElement& element) {
    // success
}, [](const V2NIMError& error) {
    // handle error
});

Web/uni-app/小程序

TypeScriptconst element = await chatroom.V2NIMChatroomQueueService.queuePoll("key1")

Node.js/Electron

TypeScriptconst element = await chatroomQueueService.queuePoll('your element key')

HarmonyOS

TypeScriptconst element = await chatroom.queueService.queuePoll("key1")

查询队列头元素

调用 queuePeek 方法查看队列的头元素。

示例代码如下：

Android

Java//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
chatroomQueueService.queuePeek(new V2NIMSuccessCallback<V2NIMChatroomQueueElement>() {
    @Override
    public void onSuccess(V2NIMChatroomQueueElement element) {
        //success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
      //failed  
    }
});

iOS

Objective-C//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
[chatroomQueueService queuePeek:^(V2NIMChatroomQueueElement *result) {
    //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++chatroomQueueService.queuePeek([](const V2NIMChatroomQueueElement& element) {
    // success
}, [](const V2NIMError& error) {
    // handle error
});

Web/uni-app/小程序

TypeScriptconst element = await chatroom.V2NIMChatroomQueueService.queuePeek()

Node.js/Electron

TypeScriptconst element = await chatroomQueueService.queuePeek()

HarmonyOS

TypeScriptconst element = await chatroom.queueService.queuePeek()

查询队列所有元素

调用 queueList 方法排序列出所有队列元素。

示例代码如下：

Android

Java//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
chatroomQueueService.queueList(new V2NIMSuccessCallback<List<V2NIMChatroomQueueElement>>() {
    @Override
    public void onSuccess(List<V2NIMChatroomQueueElement> v2NIMChatroomQueueElements) {
        //success   
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //failed
    }
});

iOS

Objective-C//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
[chatroomQueueService queueList:^(NSArray<V2NIMChatroomQueueElement *> *result) {
    //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++chatroomQueueService.queueList([](const nstd::vector<V2NIMChatroomQueueElement>& elements) {
    // success
}, [](const V2NIMError& error) {
    // handle error
});

Web/uni-app/小程序

TypeScriptconst elements = await chatroom.V2NIMChatroomQueueService.queueList()

Node.js/Electron

TypeScriptconst elements = await chatroomQueueService.queueList()
console.log(elements)

HarmonyOS

TypeScriptconst elements = await chatroom.queueService.queueList()

清空聊天室队列

调用 queueDrop 方法清空聊天室队列。

清空成功后，会触发 onChatroomQueueDropped 回调。

示例代码如下：

Android

Java//进入聊天室成功后才能使用队列服务
V2NIMChatroomQueueService chatroomQueueService = v2NIMChatroomClient.getChatroomQueueService();
chatroomQueueService.queueDrop(new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        //success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //failed
    }
});

iOS

Objective-C//进入聊天室成功后才能使用队列服务
id<V2NIMChatroomQueueService> chatroomQueueService = [v2NIMChatroomClient getChatroomQueueService];
[chatroomQueueService queueDrop:^() {
    //success
} failure:^(V2NIMError *error) {
    //failed
}];

macOS/Windows

C++chatroomQueueService.queueDrop([]() {
   // success
}, [](const V2NIMError& error) {
   // handle error
});

Web/uni-app/小程序

TypeScriptawait chatroom.V2NIMChatroomQueueService.queueDrop()

Node.js/Electron

TypeScriptawait chatroomQueueService.queueDrop()

HarmonyOS

TypeScriptawait chatroom.queueService.queueDrop()

涉及接口

Android/iOS/macOS/Windows

API	说明
`V2NIMChatroomClient.getChatroomQueueService`	获取聊天室队列服务类
`addQueueListener`	注册聊天室队列监听器
`removeQueueListener`	取消注册聊天室队列监听器
`queueInit`	初始化聊天室队列
`queueOffer`	在队列中新增或更新元素
`queueBatchUpdate`	批量更新队列元素
`queuePoll`	在队列中取出头元素或指定的元素
`queuePeek`	查询队列的头元素
`queueList`	排序列出所有队列元素
`queueDrop`	清空队列

Web/uni-app/小程序/Node.js/Electron/HarmonyOS

API	说明
`V2NIMChatroomClient.getChatroomQueueService`	获取聊天室队列服务类
`on("EventName")`	注册聊天室队列监听器
`off("EventName")`	取消注册聊天室队列监听器
`queueInit`	初始化聊天室队列
`queueOffer`	在队列中新增或更新元素
`queueBatchUpdate`	批量更新队列元素
`queuePoll`	在队列中取出头元素或指定的元素
`queuePeek`	查询队列的头元素
`queueList`	排序列出所有队列元素
`queueDrop`	清空队列

此文档是否对你有帮助？

有帮助

去反馈

技术原理
前提条件
聊天室队列相关事件监听
初始化队列
新增/更新队列元素
批量更新队列元素
取出指定的队列元素
查询队列头元素
查询队列所有元素
清空聊天室队列
涉及接口