====== 管理子区 ======

更新时间：2022-08-10

子区是群组成员的子集，是支持多人沟通的即时通讯系统，本文介绍如何使用环信即时通讯 IM React Native SDK 在实时互动 app 中创建和管理子区，并实现子区相关功能。

===== 技术原理 =====

环信即时通讯 IM React Native SDK 提供 ''%%ChatManager%%''、''%%ChatMessageThread%%''、''%%ChatMessageEventListener%%'' 和 ''%%ChatMessageThreadEvent%%'' 类，用于管理子区，支持你通过调用 API 在项目中实现如下功能：

  * 创建、解散子区
  * 加入、退出子区
  * 子区踢人
  * 修改子区名称
  * 获取子区详情
  * 获取子区成员列表
  * 获取子区列表
  * 批量获取子区中的最新消息
  * 监听子区事件

===== 前提条件 =====

开始前，请确保满足以下条件：

  * 完成 ''%%1.0.5 及以上版本%%'' SDK 初始化，详见 [[ccim:rn:quickstart|快速开始]] 及 [[ccim:rn:overview|SDK 集成概述]]。
  * 了解环信即时通讯 IM API 的[[https://docs-im.easemob.com/ccim/limitation|使用限制]]。
  * 了解子区和子区成员数量限制，详见 [[https://docs-im.easemob.com/ccim/limitation|使用限制]]。
  * 联系商务开通子区功能。

===== 实现方法 =====

本节介绍如何使用环信即时通讯 IM React Native SDK 提供的 API 实现上述功能。

==== 创建子区 ====

所有群成员均可以调用 ''%%createChatThread%%'' 方法，基于一条群组消息新建子区。

单设备登录时，子区所属群组的所有成员均会收到 ''%%ChatMessageEventListener#onChatMessageThreadCreated%%''回调；多设备登录时，其他设备会同时收到 ''%%ChatMultiDeviceEventListener#onThreadEvent%%'' 回调，回调事件为 ''%%THREAD_CREATE%%''。

示例代码如下：

<code typescript>
// name: 即将创建的子区的名字
// msgId: 子区的父消息 ID
// parentId: 子区的父节点，通常是群组 ID
ChatClient.getInstance()
  .chatManager.createChatThread(name, msgId, parentId)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 解散子区 ====

仅子区所在群组的群主和群管理员可以调用 ''%%destroyChatThread%%'' 方法解散子区。

单设备登录时，子区所属群组的所有成员均会收到 ''%%ChatMessageEventListener#onChatMessageThreadDestroyed%%'' 回调；多设备登录时，其他设备会同时收到 ''%%ChatMultiDeviceEventListener#onThreadEvent%%'' 回调，回调事件为 ''%%THREAD_DESTROY%%''。

**注意** 解散子区或解散子区所在的群组后，将删除本地数据库及内存中关于该子区的全部数据，需谨慎操作。

示例代码如下：

<code typescript>
// chatThreadID: 子区 ID
// 执行子区销毁，请谨慎使用。
ChatClient.getInstance()
  .chatManager.destroyChatThread(chatThreadID)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 加入子区 ====

子区所在群组的所有成员均可以调用 ''%%joinChatThread%%'' 方法加入群组，

加入子区的具体步骤如下：

  - 收到 ''%%ChatMessageEventListener#onChatMessageThreadCreated%%'' 回调或 ''%%ChatMessageEventListener#onChatMessageThreadUpdated%%'' 回调，或调用 ''%%fetchChatThreadWithParentFromServer%%'' 方法从服务器获取指定群组的子区列表，从中获取到想要加入的子区 ID。
  - 调用 ''%%joinChatThread%%'' 传入子区 ID 加入对应子区。

多设备登录时，其他设备会同时收到 ''%%ChatMultiDeviceEventListener#onThreadEvent%%'' 回调，回调事件为 ''%%THREAD_JOIN%%''。

示例代码如下：

<code typescript>
// chatThreadID: 子区 ID
ChatClient.getInstance()
  .chatManager.joinChatThread(chatThreadID)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 退出子区 ====

子区成员均可以主动调用 ''%%leaveChatThread%%'' 方法退出子区，退出子区后，该成员将不会再收到子区消息。

多设备登录时，其他设备会同时收到 ''%%ChatMultiDeviceEventListener#onThreadEvent%%'' 回调，回调事件为 ''%%THREAD_LEAVE%%''。

示例代码如下：

<code typescript>
// chatThreadID: 子区 ID
ChatClient.getInstance()
  .chatManager.leaveChatThread(chatThreadID)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 从子区移出成员 ====

仅群主和群管理员可以调用 ''%%removeMemberWithChatThread%%'' 方法将指定成员 (群管理员或普通成员) 踢出子区，被踢出子区的成员将不再接收到子区消息。

被踢出子区的成员会收到 ''%%ChatMessageEventListener#onUserRemoved%%'' 回调。多设备登录时，执行踢人操作的成员的其他设备会同时收到 ''%%ChatMultiDeviceEventListener#onThreadEvent%%'' 回调，回调事件为 ''%%THREAD_KICK%%''。

示例代码如下：

<code typescript>
// chatThreadID: 子区 ID
// member: 子区成员的用户 ID
ChatClient.getInstance()
  .chatManager.removeMemberWithChatThread(chatThreadID, memberId)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 修改子区名称 ====

仅群主和群管理员以及子区的创建者可以调用 ''%%updateChatThreadName%%'' 方法修改子区名称。

单设备登录时，子区所属群组的所有成员会收到 ''%%ChatMessageEventListener#onChatMessageThreadUpdated%%'' 回调；多设备登录时，其他设备会同时收到 ''%%ChatMultiDeviceEventListener#onThreadEvent%%'' 回调，回调事件为 ''%%THREAD_UPDATE%%''。

示例代码如下：

<code typescript>
// chatThreadID: 子区 ID
// newChatThreadName: 修改的子区名称，长度不超过 64 个字符
ChatClient.getInstance()
  .chatManager.updateChatThreadName(chatThreadID, newName)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 获取子区详情 ====

子区所属群组的所有成员均可以调用 ''%%fetchChatThreadFromServer%%'' 从服务器获取子区详情。

示例代码如下：

<code typescript>
// chatThreadID: 子区 ID
ChatClient.getInstance()
  .chatManager.fetchChatThreadFromServer(chatThreadID)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 获取子区成员列表 ====

子区所属群组的所有成员均可以调用 ''%%fetchMembersWithChatThreadFromServer%%'' 方法从服务器分页获取子区成员列表。

<code typescript>
// chatThreadId: 子区 ID
// pageSize: 单次请求返回的成员数，取值范围为 [1, 50]
// cursor: 开始获取数据的游标位置，首次调用方法时传 `null` 或空字符串
ChatClient.getInstance()
  .chatManager.fetchMembersWithChatThreadFromServer(
    chatThreadID,
    cursor,
    pageSize
  )
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 获取子区列表 ====

  - 用户可以调用 ''%%fetchJoinedChatThreadFromServer%%'' 方法从服务器分页获取自己加入和创建的子区列表：

<code typescript>
// pageSize: 单次请求返回的子区数，取值范围为 [1, 50]
// cursor: 开始获取数据的游标位置，首次调用方法时传 `null` 或空字符串
ChatClient.getInstance()
  .chatManager.fetchJoinedChatThreadFromServer(cursor, pageSize)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

<HTML><ol start="2" style="list-style-type: decimal;"></HTML>
<HTML><li></HTML>用户可以调用 ''%%fetchJoinedChatThreadWithParentFromServer%%'' 方法从服务器分页获取指定群组中自己加入和创建的子区列表：<HTML></li></HTML><HTML></ol></HTML>

<code typescript>
// parentId: 群组 ID
// pageSize: 单次请求返回的子区数，取值范围为 [1, 50]
// cursor: 开始获取数据的游标位置，首次调用方法时传 `null` 或空字符串
ChatClient.getInstance()
  .chatManager.fetchJoinedChatThreadWithParentFromServer(
    parentId,
    cursor,
    pageSize
  )
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

<HTML><ol start="3" style="list-style-type: decimal;"></HTML>
<HTML><li></HTML>用户还可以调用 ''%%fetchChatThreadWithParentFromServer%%'' 方法从服务器分页获取指定群组的子区列表：<HTML></li></HTML><HTML></ol></HTML>

<code typescript>
// parentId: 群组 ID
// pageSize: 单次请求返回的子区数，取值范围为 [1, 50]
// cursor: 开始获取数据的游标位置，首次调用方法时传 `null` 或空字符串
ChatClient.getInstance()
  .chatManager.fetchChatThreadWithParentFromServer(parentId, cursor, pageSize)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 批量获取子区中的最新一条消息 ====

用户可以调用 ''%%fetchLastMessageWithChatThread%%'' 方法从服务器批量获取子区中的最新一条消息。

示例代码如下：

<code typescript>
// chatThreadIDs: 要查询的子区 ID 列表，每次最多可传入 20 个子区 ID
ChatClient.getInstance()
  .chatManager.fetchLastMessageWithChatThread(chatThreadIDs)
  .then((result) => {
    console.log("success: ", result);
  })
  .catch((error) => {
    console.log("fail: ", error);
  });
</code>

==== 监听子区事件 ====

''%%ChatManager%%'' 类中提供子区事件的监听接口。开发者可以通过设置此监听，获取子区中的事件，并做出相应处理。如果不再使用该监听，需要移除，防止出现内存泄漏。

示例代码如下：

<code typescript>
class ChatMessageEvent implements ChatMessageEventListener {
  onChatMessageThreadCreated(msgThread: ChatMessageThreadEvent): void {
    console.log(`onChatMessageThreadCreated: `, msgThread);
  }
  onChatMessageThreadUpdated(msgThread: ChatMessageThreadEvent): void {
    console.log(`onChatMessageThreadUpdated: `, msgThread);
  }
  onChatMessageThreadDestroyed(msgThread: ChatMessageThreadEvent): void {
    console.log(`onChatMessageThreadDestroyed: `, msgThread);
  }
  onChatMessageThreadUserRemoved(msgThread: ChatMessageThreadEvent): void {
    console.log(`onChatMessageThreadUserRemoved: `, msgThread);
  }
  // 其他回调接收省略，实际开发中需添加
}

const listener = new ChatMessageEvent();
// 添加子区相关的监听器
ChatClient.getInstance().chatManager.addMessageListener(listener);

// 移除监听器
ChatClient.getInstance().chatManager.removeMessageListener(listener);

// 移除所有消息监听器
ChatClient.getInstance().chatManager.removeAllMessageListener();
</code>