Hooks

Hooks 钩子函数用于在 Web IMKit 需要时，从业务层获取所需的必要数据，如用户信息、群组信息等。开发者需要在初始化 Web IMKit 时，按要求完成必要的钩子函数实现。

提示

由于钩子函数定义较为复杂，本章内容均使用 TypeScript 代码示例，以便于用户更好地理解钩子函数的参数和返回值数据结构。

Hooks 定义

Web IMKit 中通过 IRCKitServiceHooks 接口定义所需的所有钩子，声明如下：

TypeScript

export interface IRCKitServiceHooks {
  /**
   * 根据 userId 批量获取用户信息
   * @param userIds - 用户 ID 列表
   */
  reqUserProfiles(userIds: string[]): Promise<IRCKitUserProfile[]>;
  /**
   * 根据 groupId 批量获取群组信息
   * @param groupIds - 群组 ID 列表
   */
  reqGroupProfiles(groupIds: string[]): Promise<IRCKitGroupProfile[]>;
  /**
   * 批量获取系统会话信息，当会话列表中存在 ConversationType.SYSTEM 类型时，会调用此方法获取系统会话信息
   * @param targetIds - 系统会话 ID 列表
   */
  reqSystemProfiles(targetIds: string[]): Promise<IRCKitSystemProfile[]>;
  /**
   * 获取群组成员信息
   * @param groupId - 群组 ID
  */
  reqGroupMembers(groupId: string): Promise<IRCKitGroupMemberProfile[]>;
  /**
    * [可选]定义默认用户信息，以替换 SDK 默认初始数据，如头像、名称规则等
    * @param userId - 用户 ID
    */
  getDefaultUserProfile?(userId: string): IRCKitUserProfile;
  /**
    * [可选]定义默认群组信息，以替换 SDK 默认数据，如头像、名称规则等
    * @param groupId - 群组 ID
    */
  getDefaultGroupProfile?(groupId: string): IRCKitGroupProfile;
  /**
    * [可选]定义默认系统会话信息，以替换 SDK 默认数据，如头像、名称规则等
    * @param systemId - 系统会话 ID
    */
  getDefaultSystemProfile?(systemId: string): IRCKitSystemProfile;
  /**
   * [可选]批量获取用户在线状态
   * @param userIds - 用户 ID 列表
   */
  reqUserOnlineStatus?(userIds: string[]): Promise<IRCKitUserOnlineStatus[]>;
}

如需展示在线状态，除了实现 reqUserOnlineStatus 钩子外，还需要在 kitApp.ready() 前将 RCKitCommand.SHOW_USER_ONLINE_STATE 开关设置为 true。

调用与缓存

Web IMKit 对于从业务层获取到的用户信息、群组信息等，会在内部进行缓存，以避免重复请求。

下图以用户信息为例，展示了 Web IMKit 中用户信息的获取和更新机制。

当用户信息、群组信息等发生变化时，业务层可以调用 updateUserProfile 等方法通知 Web IMKit 更新缓存数据，并及时更新 UI 显示。详情请参考数据更新。

代码示例

TypeScript

import {
  IRCKitServiceHooks,
  RCKitInstaller,
  IRCKitUserProfile,
  IRCKitGroupProfile,
  IRCKitGroupMemberProfile,
  IRCKitSystemProfile,
  IRCKitUserOnlineStatus,
} from '@rongcloud/im-kit';

const hooks: IRCKitServiceHooks = {
  // 定义人员信息获取方法
  async reqUserProfiles(userIds: string[]): Promise<IRCKitUserProfile[]> {
    // userIds 为用户 ID 列表，业务层需要根据 userIds 提供对应的用户信息
    return userIds.map((userId) => ({
      userId,
      name: '', // 用户名称，请传递有效值，否则会影响用户信息展示
      portraitUri: '', // 用户头像，请传递有效值，当头像获取失败或未提供，SDK 将使用默认头像
    }));
  },

  // 定义群组信息获取方法
  async reqGroupProfiles(groupIds: string[]): Promise<IRCKitGroupProfile[]> {
    // groupIds 为群组 ID 列表，业务层需要根据 groupIds 提供对应的群组信息
    return groupIds.map((groupId) => ({
      groupId,
      name: '', // 群组名称，请传递有效值，否则会影响群组信息展示
      memberCount: 0, // 群成员数量，请传递有效值，否则会影响群组信息展示
      portraitUri: '', // 群组头像，请传递有效值，当头像获取失败或未提供，SDK 将使用默认头像
    }));
  },

  // 定义群组成员信息获取方法
  async reqGroupMembers(groupId: string): Promise<IRCKitGroupMemberProfile[]> {
    // groupId 为群组 ID，业务层需要根据 groupId 提供对应的群组成员信息
    return [
      // 需要业务层提供群组的真实成员信息，其中 nickname 为可选。
      // nickname 为空时，SDK 将通过 reqUserProfiles 获取的用户信息中的 name 字段作为群组成员昵称。
      // 为优化性能，建议业务层提供群组成员的真实昵称，以避免 SDK 内部多次调用 reqUserProfiles 方法。
      { userId: 'user-01', nickname: '' },
      { userId: 'user-02' }
    ]
  },

  // 定义系统会话信息获取方法
  async reqSystemProfiles(systemIds: string[]): Promise<IRCKitSystemProfile[]> {
    // systemIds 为系统会话 ID 列表，业务层需要根据 systemIds 提供对应的系统会话信息
    return systemIds.map((systemId) => ({
      systemId,
      name: '', // 系统会话名称，请传递有效值，否则会影响系统会话信息展示
      portraitUri: '', // 系统会话头像，请传递有效值，当头像获取失败或未提供，SDK 将使用默认头像
    }));
  },

  // 如需展示在线状态，可选实现该方法
  async reqUserOnlineStatus(userIds: string[]): Promise<IRCKitUserOnlineStatus[]> {
    return userIds.map((userId) => ({
      userId,
      online: false,
    }));
  },
}

// 初始化 IMKit，将 hooks 作为参数传入
const kitApp = RongIMLib.installPlugin(RCKitInstaller, { hooks });