跳到主要内容

Hooks

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

提示

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

Hooks 定义​

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

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[]>;
}

调用与缓存​

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

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

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

代码示例​

import { IRCKitServiceHooks, RCKitInstaller } from '@rongcloud/global-im-uikit';
// 您也可以通过如下方式进行 Global IM UIKit 引用，为便于后续理解文档示例，此处使用 import * as RCIMKit 方式引用
// import { RCKitInstaller } from '@rongcloud/global-im-uikit';

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 将使用默认头像
    }));
  },
}

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