聊天室队列指聊天室（房间）中由多个元素（key-value 键值对）构成的队列，应用于直播间中的连麦场景和礼物队列展示等场景。

本文介绍聊天室队列服务的技术原理、使用的前提条件以及实现聊天室队列相关操作的方法。

技术原理

网易云信 IM SDK 的 CHATROOM_BROWSER_SDK 下的 ChatroomQueueInterface 模块提供 ChatroomQueue 定义聊天室队列，其取值为 key-value 数组。

通过定义 key 和 value 的值，您可以定义聊天室队列中的元素。以直播连麦场景的开发为例，通过定义 key-value 键值对的值，可将麦位和用户账号关联起来定义为该场景里麦位队列的元素，之后便可调用 ChatroomQueueInterface 下的方法对 ChatroomQueue 进行相应的操作管理。

上图仅为示例，请以您的实际业务场景需求进行开发。

前提条件

在实现聊天室队列相关操作管理前，请确保您已：

• 通过聊天室概述了解聊天室的基本功能逻辑、注意事项和相关限制。
• 完成聊天室初始化和登录。

实现方法

初始化聊天室队列

调用 init 方法，调用时传入 queueInitOptions下的参数，即可初始化聊天室队列。

该方法主要用于设置聊天室队列的长度限制 maxItemCount ，即队列中可包含的最大元素数量（取值范围：0 至 1,000）。

接口原型如下：

jsexport type QueueInitOptions = {
  /**
   * 新建队列的长度限制(0~1000),可以对现有队列做此操作，修改现有队列的长度上限；当前队列如果已经超过了新的限制，元素不会减少，但是新元素无法增加
   */
  maxItemCount: number
}
/**
  * 初始化聊天室队列
  */
init(options: QueueInitOptions): Promise<void>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.init({maxItemCount:100})

排序列出所有元素

调用 fetch 方法可排序列出聊天室队列的所有元素。

接口原型如下：

js/**
  * 排序列出所有元素
  */
fetch(): Promise<ChatroomQueue[]>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.fetch()

加入或更新队列元素

调用 update 方法可加入或更新聊天室队列元素。调用时传入 QueueUpdateOptions 下的 account、elementKey、elementValue 和 transient，可定义加入/更新的新元素的所属用户账号、UniqKey、内容等特性。

接口原型如下：

jsexport type QueueUpdateOptions = {
  /**
   * 新元素的UniqKey，长度限制128字节
   */
  elementKey: string
  /**
   * 新元素内容，长度限制4096字节
   */
  elementValue: string
  /**
   * 可选参数，不传默认false，当提交这个新元素的用户从聊天室掉线或退出的时候，是否需要删除这个元素。
   */
  transient?: boolean
  /**
   * 可选参数，队列元素所属账号，默认不传表示队列元素属于当前操作人，管理员可以指定队列元素归属于其他合法账号
   */
  account?: string
}
/**
  * 加入或者更新队列元素
  */
update(options: QueueUpdateOptions): Promise<void>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.update({elementKey:'...',elementValue:'...'})

批量更新队列元素

调用 batchUpdate 方法可批量更新至多 100 个聊天室队列的元素。传入参数详见 QueueBatchUpdateOptions。

接口原型如下：

jsexport type QueueBatchUpdateOptions = {
  /**
   * 批量更新元素的key-value对，key/value分别是elementKey和elementValue（elementKey 限制 128, elementValue 限制 4096 字节），一次最多更新100个
  itemList: {
    [key: string]: string
  }
  /**
   * 是否需要发送广播通知，可选参数，不传默认false，当设置为 true 时，所有聊天室成员会收到类型为'updateQueue'的聊天室通知消息。
   */
  needNotify?: boolean
  /**
   * 通知中的自定义字段，长度限制2048
   */
  notifyExtension?: string
}
type ChatroomQueue = {
  [key: string]: string
}
/**
  * 批量更新聊天室队列元素
  */
batchUpdate(options: QueueBatchUpdateOptions): Promise<ChatroomQueue[]>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.batchUpdate({itemList:{a:"111"})

查看队列中首个元素

调用 pickHeader 方法可查看聊天室队列中的第一个元素。

接口原型如下：

jstype ChatroomQueue = {
  [key: string]: string
}
/**
  * 查看聊天室队列中的第一个元素
  */
pickHeader(): Promise<ChatroomQueue>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.pickHeader()

将指定元素从队列中踢除

调用 poll 方法可将指定元素（不传入参默认取出第一个元素）从聊天室队列中踢除。入参详情请参见 QueuePollOptions。

接口原型如下：

jstype ChatroomQueue = {
  [key: string]: string
}
export type QueuePollOptions = {
  /**
   * 需要取出的元素的 UniqKey, 传空传表示取出第一个元素
   */
  key?: string
}
/**
  * 取出聊天室队列指定/第一个元素
  */
poll(options: QueuePollOptions): Promise<ChatroomQueue>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.poll()

清除队列

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

接口原型如下：

js/**
  * 清空队列
  */
clear(): Promise<void>

const chatroom = new Chatroom(options)
chatroom.chatroomQueue.clear()