管理群成员名片

大约 9 分钟

管理群成员名片

功能说明

群成员名片是用户在特定群组内的个性化显示信息,用于区分该用户在不同群组中的身份展示,例如,展示部门、岗位、项目角色等群内身份信息。

例如,在企业群组中,成员可将在群组中的名片设置为“部门-姓名”或“岗位-姓名”的格式,便于群内成员快速识别和沟通。

React Native SDK 提供群成员名片管理功能,支持群成员名片的设置、本地查询、服务端获取和变更监听。开启 用户信息自动管理功能 后,SDK 还支持通过消息自动同步群成员名片更新。

技术原理

群成员名片管理功能主要由 ChatGroupManager 和 ChatGroupEventHandler 提供。SDK 通过“主动设置或拉取、本地内存存储、事件通知、消息触发自动同步”的机制管理群成员名片,具体如下:

  1. 当前登录用户可通过 ChatGroupManager.updateGroupNamecard 设置或更新自己在指定群组中的群成员名片。
  2. SDK 收到群成员名片变更通知,或通过消息自动同步群成员名片并更新本地内存后,会通过 ChatGroupEventHandler.onUserGroupNamecardChanged 事件通知 Flutter 业务层。
  3. SDK 支持通过 ChatGroupManager.fetchGroupMembersInfo 从服务端分页获取群成员信息,并将返回的群成员名片写入原生 SDK 本地内存。
  4. SDK 支持通过 ChatGroupManager.getGroupNamecard 从原生 SDK 本地内存读取指定成员在指定群组中的群成员名片。该方法返回 Future<String?>,不会主动请求服务端。
  5. 若在初始化 SDK 时将 ChatOptions.enableUserInfo 设为 true(默认为 false),发送群聊消息时会自动附带发送方群成员名片的更新时间;接收方开启该功能后,若消息携带有效的更新时间,且该时间晚于本地内存中的对应时间戳,或本地尚无对应名片缓存,SDK 会自动从服务端拉取最新群成员名片,获取成功后更新原生 SDK 本地内存,并通过 onUserGroupNamecardChanged 事件通知 Flutter 业务层。

内存更新流程如下图所示:

img

前提条件

开始接入前,请确保满足以下条件:

监听群成员名片更新

SDK 提供 ChatGroupEventListener,用于监听群成员名片更新事件。建议在业务初始化阶段完成监听注册,并在组件卸载或不再需要监听时移除监听器。

SDK 收到群成员名片变更通知,或通过消息自动同步群成员名片并更新本地内存后,会触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。该事件适用于以下场景:

  • 当前登录用户更新群成员名片后,群内其他 在线成员 收到变更通知。
  • 开启 用户信息自动管理功能 后,接收方因接收消息触发自动同步并更新本地内存后。

主动调用 ChatGroupManager#fetchMemberInfoListFromServer 获取群成员信息时,不会因本次拉取触发该事件。获取成功后,请根据接口返回结果刷新界面,不应等待名片变更事件。

const groupNamecardListener: ChatGroupEventListener = {
  onUserGroupNamecardChanged({ groupId, userId, namecard }) {
    console.log('群成员名片更新:', { groupId, userId, namecard });
    // 清除群名片时兼容 undefined、null 或空字符串等空值
  },
};

ChatClient.getInstance().groupManager.addGroupListener(
  groupNamecardListener
);

// 在页面或组件卸载时调用,移除同一个监听器对象。
function removeGroupNamecardListener(): void {
  ChatClient.getInstance().groupManager.removeGroupListener(
    groupNamecardListener
  );
}

设置群成员名片

调用 ChatGroupManager#updateGroupNamecard 设置或更新当前登录用户在指定群组中的群成员名片。群内其他在线成员收到对应的群成员名片变更通知后,会触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。

try {
  await ChatClient.getInstance().groupManager.updateGroupNamecard(
    'groupId',
    'new_namecard'
  );
  console.log('设置群成员名片成功');
} catch (error) {
  console.error('设置群成员名片失败:', error);
}

若要清除当前用户在该群组中的群名片,请省略第二个参数或传入 undefined:

try {
  await ChatClient.getInstance().groupManager.updateGroupNamecard('groupId');
} catch (error: unknown) {
  console.error('清除群成员名片失败:', error);
}

从服务端获取群成员名片

调用 ChatGroupManager#fetchMemberInfoListFromServer 从服务器分页获取群成员信息,包含群成员名片。

获取成功后,相关群成员信息会自动更新至本地内存。有关该接口的更多说明,详见 管理群成员。

// limit:每页期望返回的群成员数量,默认 200。
// 首次调用时将 `cursor` 传入空字符串 `''`,后续调用时传入上一次返回的 `result.cursor`。
try {
  const result = await ChatClient.getInstance()
    .groupManager.fetchMemberInfoListFromServer('groupId', '', 50);

  for (const member of result.list ?? []) {
    console.log('群成员信息:', {
      userId: member.memberId,
      nickname: member.nickname,
      avatarUrl: member.avatarUrl,
      namecard: member.namecard,
    });
  }

  // result.cursor 非空时,将其作为 cursor 获取下一页;为空时停止翻页
  // const nextResult = await ChatClient.getInstance()
  //   .groupManager.fetchMemberInfoListFromServer(
  //     'groupId',
  //     result.cursor,
  //     50
  //   );
} catch (error) {
  console.error('获取群成员信息失败:', error);
}

从本地内存获取群成员名片

调用 ChatGroupManager#getGroupNamecard 可从本地内存读取指定成员在指定群组中的群成员名片。该接口不会发起网络请求,适用于本地展示场景,返回类型为 Promise<string | undefined>。本地没有对应数据时可能返回 undefined,空字符串也会原样返回,展示时请兼容空值。

try {
  const namecard = await ChatClient.getInstance()
    .groupManager.getGroupNamecard('groupId', 'userId');
  console.log('群成员名片:', namecard);
} catch (error) {
  console.error('读取群成员名片失败:', error);
}

通过消息自动同步群成员名片

如果希望在发送消息时自动携带群成员名片的更新时间,并在接收消息时自动更新本地内存,需要在初始化 SDK 时开启 用户信息自动管理功能,即将 ChatOptions.enableUserInfo 设为 true。

const options = ChatOptions.withAppKey({
  appKey: 'your-org#your-app',
  enableUserInfo: true,
});

try {
  await ChatClient.getInstance().init(options);
} catch (error: unknown) {
  console.error('初始化 SDK 失败:', error);
}

提示

enableUserInfo 必须在调用 ChatClient#init 时通过 ChatOptions 传入。SDK 初始化完成后再修改原选项对象,不会重新配置已初始化的原生 SDK。

用户信息功能开启后,SDK 会执行以下操作:

  1. 当前登录用户更新群成员名片后,后续发送的消息会自动附带群成员名片更新时间。
  2. 接收方收到消息后,SDK 会将消息中的群成员名片更新时间与本地内存进行比较。
  3. 如果消息中的更新时间晚于本地内存,SDK 会自动从服务端拉取最新群成员名片。
  4. 获取成功后,SDK 会更新本地内存,并触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。

此外,开启用户信息功能后,还可以通过收到的 ChatMessage.senderInfo 获取消息发送方当前可用的群成员名片信息。群名片字段为 groupNameCard。详见 用户信息自动管理。

const senderInfoListener: ChatMessageEventListener = {
  onMessagesReceived(messages) {
    for (const message of messages) {
      console.log('发送方群成员名片:', message.senderInfo?.groupNameCard);
    }
  },
};

ChatClient.getInstance().chatManager.addMessageListener(senderInfoListener);

// 页面或组件卸载、不再需要监听时移除同一个监听器对象
function removeSenderInfoListener(): void {
  ChatClient.getInstance().chatManager.removeMessageListener(senderInfoListener);
}

注意事项

  • 群成员名片是用户在特定群组中的显示信息,不同群组之间互不影响。
  • ChatGroupManager#getGroupNamecard 仅查询本地内存,不会主动从服务端获取最新数据。
  • 更新名片后,发给群内其他成员的变更通知仅投递给在线用户;通过消息自动同步引起的本地更新,也可触发 ChatGroupEventListener#onUserGroupNamecardChanged。主动获取成员信息不会因本次拉取触发该事件,应根据接口返回结果刷新界面。
  • 若需通过消息自动同步群成员名片,必须在 SDK 初始化时将 ChatOptions.enableUserInfo 设为 true。
  • 开启 用户信息自动管理 后,群成员名片的自动更新依赖消息触发;若业务需要主动获取最新数据,仍应调用服务端接口。
  • ChatGroupMember 中的群名片字段为 namecard,ChatMessageSenderInfo 中的群名片字段为 groupNameCard,两者的大小写不同。

常见问题

设置群成员名片后,为何其他成员未立即收到事件?

调用 ChatGroupManager#updateGroupNamecard 后,当前登录用户在指定群组中的群成员名片会更新。其他 在线成员 在收到对应的群成员名片变更通知后,才会触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。

为何调用 getGroupNamecard 获取不到群成员名片?

ChatGroupManager#getGroupNamecard 仅从本地内存读取数据,不会主动从服务端获取最新信息。如果本地尚未缓存对应成员的群成员名片,返回结果可能为 undefined 或空字符串。此时可先调用 ChatGroupManager#fetchMemberInfoListFromServer 从服务端获取群成员信息。如需通过消息自动同步群成员名片,还需在初始化时开启用户信息功能。

从服务端获取的群成员信息是否写入本地内存?

会。调用 ChatGroupManager#fetchMemberInfoListFromServer 从服务端获取群成员信息成功后,返回结果中的群成员名片等数据会写入本地内存,后续可通过 ChatGroupManager#getGroupNamecard 直接读取。

开启用户信息自动管理后,群成员名片为何会自动更新?

初始化时将 ChatOptions.enableUserInfo 设为 true 后,发送消息时会自动附带发送方群成员名片更新时间。接收方收到消息后,SDK 会将消息中的更新时间与本地内存进行比较。如果消息中的更新时间晚于本地内存,SDK 会自动从服务端拉取最新群成员名片并更新本地内存。

通过消息自动同步群成员名片后,还需主动从服务端获取吗?

视业务场景而定。通过消息自动同步依赖消息触发;如果业务需要立即获取最新群成员名片,或当前没有消息触发同步,仍建议调用 ChatGroupManager#fetchMemberInfoListFromServer 主动从服务端获取最新数据。

相关文档

接口列表

API 名称所属模块/类说明
updateGroupNamecardChatGroupManager设置、更新或清除当前用户在指定群组中的群名片。
fetchMemberInfoListFromServerChatGroupManager从服务器分页获取群成员信息。
getGroupNamecardChatGroupManager从本地内存读取指定成员的群名片。
onUserGroupNamecardChangedChatGroupEventListener群成员名片发生变化并同步到本地时触发。
withAppKeyChatOptions使用 App Key 创建 SDK 初始化配置。也可根据业务配置使用 withAppId。
initChatClient使用指定配置初始化 SDK。
上次编辑于: