跳到主要内容

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 });