用户信息自动管理

大约 8 分钟

用户信息自动管理

功能说明

自 v1.13.0 起，环信即时通讯 IM HarmonyOS SDK 提供用户信息自动管理功能。开启该功能后，SDK 可自动维护用户信息的同步与内存更新，帮助开发者减少手动拉取、存储和更新用户信息的工作量。

该功能适用于会话列表、消息列表、群聊页面等需要展示用户昵称、头像、备注、群成员名片的场景。

本文提及的用户信息指用于业务展示的用户相关信息，包括 用户属性、好友备注 和 群成员名片。

技术原理

用户信息自动管理功能由 ChatOptions#setEnableUserInfo(true) 控制。开启后，SDK 按以下流程处理用户信息同步与本地内存更新：

  1. 用户登录成功后，SDK 自动从服务端获取当前登录用户的信息，并写入本地内存。
  2. 当用户更新自身信息后，后续发送的消息会携带对应信息的更新时间。
  3. 接收方收到消息后，SDK 会解析消息中的发送方信息及更新时间。
  4. SDK 会将消息中的更新时间与本地内存中的时间戳进行比较。
  5. 如果消息中的更新时间晚于本地内存，SDK 会自动 从服务端拉取最新用户属性 或 群成员名片。
  6. 拉取成功后，SDK 会自动更新本地内存。
  7. 本地内存更新完成后，SDK 会通过事件通知上层应用，业务层可据此刷新 UI。

该功能的核心是：SDK 自动完成用户信息获取、更新检测、本地内存更新和变更通知。

内存更新流程如下：

img

前提条件

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

  • 已将 SDK 升级至 v1.13.0 或以上版本。
  • 已完成 SDK 初始化。详见 快速开始。
  • 已了解即时通讯 IM 的相关使用限制。详见使用限制。

开启用户信息自动管理

在 SDK 初始化前，调用 ChatOptions#setEnableUserInfo(true)：

ChatClient.getInstance().init(context, {
  appKey: "your_appkey",
  isEnableUserInfo: true
});

提示

必须在调用 ChatClient.getInstance().init(context, options) 初始化 SDK 之前调用 ChatOptions#setEnableUserInfo(true)，否则该功能不会生效。

监听用户属性更新

SDK 提供 UserInfoListener，用于监听用户属性更新事件，主要包括：

  • UserInfoListener#onSelfUserInfoUpdate：当前登录用户的属性同步或更新并写入本地内存后触发该事件。
  • UserInfoListener#onUserInfoUpdate：其他用户属性更新并写入本地内存后触发，包括以下场景：

建议在业务初始化阶段完成监听注册，以便在登录后的初始同步、消息触发或主动拉取等场景中及时接收事件并刷新界面。 关于其他场景下用户属性变更通知机制，详见 监听用户属性变更。

添加监听：

const listener: UserInfoListener = {
  onSelfUserInfoUpdate: (userInfo: UserInfo) => {
    ChatLog.d(
      `当前用户信息更新: userId=${userInfo.userId}, nickname=${userInfo.nickname}, avatarUrl=${userInfo.avatarUrl}`
    );
  },

  onUserInfoUpdate: (userInfoList: Array<UserInfo>) => {
    userInfoList.forEach((userInfo: UserInfo) => {
      ChatLog.d(
        `用户信息更新: userId=${userInfo.userId}, nickname=${userInfo.nickname}, avatarUrl=${userInfo.avatarUrl}`
      );
    });
  }
};

ChatClient.getInstance().userInfoManager()?.addListener(listener);

移除监听：

ChatClient.getInstance().userInfoManager()?.removeListener(listener);

通过消息获取发送方信息

对于 1.13.0 或以上版本，开启用户信息自动管理后，如果发送方在发送消息时携带了自己的用户信息，则无论发送方与接收方是否为好友关系，当接收方收到该消息，且消息中携带的发送方用户属性更新时间晚于本地缓存时，SDK 会重新拉取该用户属性，并触发 UserInfoListener#onUserInfoUpdate 事件。

接收方收到该消息后，可以通过 ChatMessage#getSenderInfo() 获取当前可用的发送方信息，包括昵称、头像、备注和群成员名片。

function handleReceivedMessages(messages: Array<ChatMessage>): void {
  messages.forEach((message: ChatMessage) => {
    const senderInfo: ChatSenderInfo | undefined = message.getSenderInfo();
    if (senderInfo) {
      console.info(
        `发送方信息: userId=${senderInfo.userId}, nickname=${senderInfo.nickname}, ` +
        `avatarUrl=${senderInfo.avatarUrl}, remark=${senderInfo.remark}, namecard=${senderInfo.namecard}`
      );
    }
  });
}

提示

ChatMessage#getSenderInfo() 返回的是当前本地可用的发送方信息。如果消息触发了用户信息更新，最新数据会在 SDK 完成本地内存更新后，通过 UserInfoListener 的相关事件通知业务层。

从本地内存读取用户属性

自 v1.13.0 起，你可以调用 UserInfoManager#getUserInfoById 直接从本地内存读取用户属性。该接口返回的是用户的 UserInfo。它适用于直接从本地缓存读取指定用户的资料，不会发起网络请求，因此可以作为好友列表读取能力之外的补充资料读取方式。

const userInfoMap: Map<string, UserInfo> = await ChatClient.getInstance()
  .userInfoManager()!
  .getUserInfoById(['userId1', 'userId2']);

userInfoMap.forEach((userInfo: UserInfo, userId: string) => {
  console.info(
    `本地用户属性: userId=${userId}, nickname=${userInfo.nickname}, avatarUrl=${userInfo.avatarUrl}`
  );
});

提示

该接口仅返回本地内存的数据。如需主动从服务端获取最新用户属性，请调用 UserInfoManager#fetchUserInfoById 方法。详见 管理用户属性。

注意事项

  • ChatOptions#setEnableUserInfo(true) 必须在 SDK 初始化前调用。
  • 建议优先注册 UserInfoListener，以便在本地内存更新后及时刷新业务界面。
  • ChatMessage#getSenderInfo() 表示当前本地可用的发送方信息，不保证一定是刚收到消息时的最终最新值。
  • 当消息中的更新时间晚于本地内存时，SDK 会自动从服务端拉取最新数据并更新本地内存。
  • UserInfoManager#getUserInfoById 仅查询本地内存，不会主动从服务端拉取最新数据。

常见问题

何时开启用户信息自动管理？

必须在调用 ChatClient.getInstance().init(context, options) 初始化 SDK 之前调用 ChatOptions#setEnableUserInfo(true)。如果在 SDK 初始化完成后再设置，用户信息自动管理功能不会生效。

功能开启后，SDK 会自动执行哪些操作？

开启用户信息自动管理功能 后，SDK 会在登录成功后自动同步当前登录用户信息；在发送消息时自动附带发送方信息及更新时间；在接收消息后自动比较消息中的更新时间与本地内存；在检测到数据更新时自动从服务端拉取最新信息并更新本地内存，同时通过 UserInfoListener 通知业务层。

ChatMessage#getSenderInfo() 一定最新？

不一定。ChatMessage#getSenderInfo() 返回的是当前本地可用的发送方信息。如果消息触发了用户信息更新，SDK 会先从服务端拉取最新数据并更新本地内存，随后通过 UserInfoListener 通知业务层刷新界面。

为何建议尽早注册监听？

开启用户信息自动管理功能 后，SDK 可能在登录后的初始同步以及消息触发的用户信息更新场景中通知业务层。建议在业务初始化阶段完成 UserInfoListener 注册，以便及时接收事件并刷新界面。

本地读取和服务端获取有何区别？

UserInfoManager#getUserInfoById 仅查询本地内存，不会发起网络请求，适用于本地展示场景。如果业务需要获取最新的用户属性，应调用 UserInfoManager#fetchUserInfoById 主动从服务端获取。

功能开启后需自己维护内存吗？

通常不需要。开启 ChatOptions#setEnableUserInfo(true) 后，SDK 会负责用户信息的自动同步、更新时间比较、本地内存更新和事件通知。业务层通常只需从本地内存读取数据，并在相关事件中刷新界面。

相关功能

管理群成员名片

启用用户信息自动管理后，SDK 也支持群成员名片的自动同步与更新。你可以进一步实现群成员名片的设置、查询和变更监听。详见 管理群成员名片。

用户属性与用户信息

  • 用户信息：指用于业务展示的用户相关信息，包括 用户属性、好友备注 和 群成员名片。
  • 用户属性：指用户可设置和管理的资料字段，例如，用户昵称、头像、邮箱、电话号码等。你可通过相关接口对这些字段进行设置、更新和查询。详见 管理用户属性。例如，你可以通过 UserInfoManager#updateUserInfo 设置当前登录用户的昵称、头像等资料。若用户信息自动管理功能开通（调用 ChatOptions#setEnableUserInfo(true)），更新后的信息会在后续发送消息时自动参与同步。

通过消息同步的发送方信息

开启用户信息自动管理后，接收到的消息中会包含发送方相关信息，包括昵称、头像、备注和群成员名片。业务可通过 ChatMessage#getSenderInfo() 获取当前本地可用的发送方信息。

上次编辑于:
环信 IM 文档
© 环信 2026