会话页面自定义

消息点击事件

您可以通过调用 addMessageClickListener 方法监听消息的点击事件。消息点击监听 MessageClickListener 的所有方法均为可选方法，可以按需实现。

提示

从 1.4.3 版本开始，onMessageClick 支持语音消息。
从 1.4.3 版本开始，所有方法均增加 Context、ClickEvent/GestureEvent 参数。

警告

为了避免内存泄漏，请将监听保存，在必要的时候移除。

接口定义

TypeScript
export interface MessageClickListener {
  /**
   * 消息头像点击事件
   */
  onMessagePortraitClick?: (message: Message, userId: string, context?: Context, event?: ClickEvent) => boolean;
  
  /**
   * 消息头像长按事件
   */
  onMessagePortraitLongClick?: (message: Message, user: UserInfoModel, context?: Context, event?: GestureEvent) => boolean;
  
  /**
   * 消息点击事件
   */
  onMessageClick?: (message: Message, context?: Context, event?: ClickEvent) => boolean;
  
  /**
   * 消息长按事件
   */
  onMessageLongClick?: (message: Message, context?: Context, event?: GestureEvent) => boolean;
  
  /**
   * 消息撤回编辑事件
   */
  onMessageRecallEditClick?: (message: Message, context?: Context, event?: ClickEvent) => boolean;
  
  /**
   * 文本消息超链接点击事件
   */
  onMessageLinkClick?: (message: Message, url: string, context?: Context, event?: ClickEvent) => boolean;
  
  /**
   * 文本消息 Email 点击事件
   */
  onMessageEmailClick?: (message: Message, email: string, context?: Context, event?: ClickEvent) => boolean;
  
  /**
   * 文本消息手机号点击事件
   */
  onMessagePhoneClick?: (message: Message, phone: string, context?: Context, event?: ClickEvent) => boolean;
}

方法说明

MessageClickListener

方法名	参数	返回值	说明	支持版本
`onMessagePortraitClick`	`message: Message` `userId: string` `context?: Context` `event?: ClickEvent`	`boolean`	消息头像点击事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessagePortraitLongClick`	`message: Message` `user: UserInfoModel` `context?: Context` `event?: GestureEvent`	`boolean`	消息头像长按事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessageClick`	`message: Message` `context?: Context` `event?: ClickEvent`	`boolean`	消息点击事件。从 `1.4.3` 版本开始支持语音消息。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessageLongClick`	`message: Message` `context?: Context` `event?: GestureEvent`	`boolean`	消息长按事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessageRecallEditClick`	`message: Message` `context?: Context` `event?: ClickEvent`	`boolean`	消息撤回编辑事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessageLinkClick`	`message: Message` `url: string` `context?: Context` `event?: ClickEvent`	`boolean`	文本消息超链接点击事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessageEmailClick`	`message: Message` `email: string` `context?: Context` `event?: ClickEvent`	`boolean`	文本消息 Email 点击事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+
`onMessagePhoneClick`	`message: Message` `phone: string` `context?: Context` `event?: ClickEvent`	`boolean`	文本消息手机号点击事件。返回 `true` 表示 App 处理该事件，SDK 不再处理；返回 `false` 表示由 SDK 处理	1.4.3+

示例代码

TypeScript
let msgClickListener: MessageClickListener = {
  onMessagePortraitClick: (message: Message, userId: string, context?: Context, event?: ClickEvent) => {
    // 消息头像点击事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessagePortraitLongClick: (message: Message, user: UserInfoModel, context?: Context, event?: GestureEvent) => {
    // 消息头像长按事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessageClick: (message: Message, context?: Context, event?: ClickEvent) => {
    // 消息点击事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessageLongClick: (message: Message, context?: Context, event?: GestureEvent) => {
    // 消息长按事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessageRecallEditClick: (message: Message, context?: Context, event?: ClickEvent) => {
    // 消息撤回编辑事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessageLinkClick: (message: Message, url: string, context?: Context, event?: ClickEvent) => {
    // 文本消息超链接点击事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessageEmailClick: (message: Message, email: string, context?: Context, event?: ClickEvent) => {
    // 文本消息 Email 点击事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
  onMessagePhoneClick: (message: Message, phone: string, context?: Context, event?: ClickEvent) => {
    // 文本消息手机号点击事件
    // true 由 App 处理该事件，SDK 不再处理。false 由 SDK 处理
    return false;
  },
}
RongIM.getInstance().conversationService().addMessageClickListener(msgClickListener);

增加消息气泡的长按事件

您可以通过 addMessageItemLongClickAction 方法设置会话页面的长按消息事件监听，在相关监听方法中自定义事件。

接口定义

TypeScript
/**
 * 长按事件配置接口
 */
export interface ItemLongClickAction<Message> {
  /**
   * 获取长按菜单显示的标题
   */
  obtainTitle: (context: Context, data: Message) => string | Resource;
  
  /**
   * 长按菜单项的点击事件
   */
  onClick: (context: Context, data: Message) => void;
  
  /**
   * 过滤条件，用于控制该长按菜单项是否显示
   */
  onFilter: (data: Message) => boolean;
  
  /**
   * 动作 ID，用于唯一标识该长按事件
   */
  actionId: string;
}

参数说明

ItemLongClickAction

参数名	类型	必填	说明
`obtainTitle`	`(context: Context, data: Message) => string \| Resource`	是	长按菜单显示的标题，返回字符串或资源 ID
`onClick`	`(context: Context, data: Message) => void`	是	用户点击长按菜单项时触发的回调函数
`onFilter`	`(data: Message) => boolean`	是	过滤条件函数，返回 `true` 表示显示该菜单项，返回 `false` 表示不显示。开发者可以根据 `Message` 对象的会话类型或者消息类型决定是否显示
`actionId`	`string`	是	动作的唯一标识符，相同的 ID 的长按事件只会增加一次

示例代码

TypeScript
let msgLongClickAction: ItemLongClickAction<Message> = {
  obtainTitle: (context: Context, data: Message): string | Resource => {
    return "自定义的消息长按事件"
  },
  onClick: (context: Context, data: Message): void => {
    promptAction.showToast({message: "点击了自定义的消息长按事件"})
  },
  onFilter: (data: Message): boolean => {
    // 是否显示该长按事件？true 显示；false 不显示
    // 开发者可以根据 Message 对象的会话类型或者消息类型决定是否显示
    return true;
  },
  // 自定义的消息长按事件 Id，相同的 Id 的长按事件只会增加一次
  actionId: 'CustomMessageActionId'
}
RongIM.getInstance().conversationService().addMessageItemLongClickAction(msgLongClickAction);

配置消息气泡的长按更多选项

在长按消息弹窗的菜单选项选择更多后，SDK 进入消息多选模式，多选模式下默认提供了删除按钮。您可以增删已有按钮、添加自定义按钮。

提示

IMKit SDK 没有内置消息转发功能，实现可以参照：转发消息。

接口定义

TypeScript
/**
 * 消息更多操作配置接口
 */
export interface MessageMoreAction {
  /**
   * 动作 ID
   */
  actionId: string;
  
  /**
   * 按钮位置
   */
  location: number;
  
  /**
   * 图标资源
   */
  icon: Resource;
  
  /**
   * 点击事件
   */
  onClick: (context: Context, data: Message[]) => boolean;
  
  /**
   * 过滤条件
   */
  onFilter: (data: Message[]) => boolean;
}

参数说明

MessageMoreAction

参数名	类型	必填	说明
`actionId`	`string`	是	动作的唯一标识符
`location`	`number`	是	按钮在底部的位置。根据 `location` 值，按照从小到大的顺序依次向右排列
`icon`	`Resource`	是	按钮显示的图标资源
`onClick`	`(context: Context, data: Message[]) => boolean`	是	点击事件回调函数。返回 `true` 表示聊天页面依旧处于多选状态；返回 `false` 表示聊天页面退出多选状态
`onFilter`	`(data: Message[]) => boolean`	是	过滤条件函数，返回 `true` 表示显示该按钮，返回 `false` 表示不显示

示例代码

TypeScript
let msgMoreAction: MessageMoreAction = {
  actionId: 'message_more_forward', // 动作 Id
  location: 100, // 按钮将放置在底部，根据 location 值，按照从小到大的顺序依次向右排列
  icon: $r("app.media.rc_message_more_forward"), // 图标

  onClick: (context: Context, data: Message[]): boolean => {
    // 处理自定义的点击事件
    // return true：聊天页面依旧处于多选状态
    // return false：聊天页面退出多选状态
    promptAction.showToast({message: "点击了聊天页面底部的更多按钮"});
    return true
  },
  onFilter: (data: Message[]): boolean => {
    // 是否显示该按钮，true 显示，false 不显示
    return true;
  }
}
RongIM.getInstance().conversationService().addMessageMoreAction(msgMoreAction)

修改消息气泡的 UI 配置

IMKit 从 1.4.3 版本开始支持通过 setConversationConfig 方法传入对应的 ConversationConfig 对象修改消息气泡的 UI 配置。支持设置的属性：边框圆角大小、边框色、背景色。

提示

仅支持初始化前的配置，若初始化后开发者设置，则不会生效。

修改边框圆角大小

边框圆角大小支持按消息方向来设置：

设置/获取接收的消息气泡边框圆角大小：setReceivedMessageBorderRadius、getReceivedMessageBorderRadius
设置/获取发送的消息气泡边框圆角大小：setSentMessageBorderRadius、getSentMessageBorderRadius

接口定义

TypeScript
/**
 * 边框圆角配置
 */
export interface BorderRadiuses {
  /**
   * 左上角圆角大小
   */
  topLeft: number;
  
  /**
   * 右上角圆角大小
   */
  topRight: number;
  
  /**
   * 左下角圆角大小
   */
  bottomLeft: number;
  
  /**
   * 右下角圆角大小
   */
  bottomRight: number;
}

/**
 * 设置接收的消息气泡边框圆角大小
 */
setReceivedMessageBorderRadius(borderRadius: BorderRadiuses): void

/**
 * 获取接收的消息气泡边框圆角大小
 */
getReceivedMessageBorderRadius(): BorderRadiuses

/**
 * 设置发送的消息气泡边框圆角大小
 */
setSentMessageBorderRadius(borderRadius: BorderRadiuses): void

/**
 * 获取发送的消息气泡边框圆角大小
 */
getSentMessageBorderRadius(): BorderRadiuses

参数说明

BorderRadiuses

参数名	类型	必填	说明
`topLeft`	`number`	是	左上角圆角大小，单位为 vp
`topRight`	`number`	是	右上角圆角大小，单位为 vp
`bottomLeft`	`number`	是	左下角圆角大小，单位为 vp
`bottomRight`	`number`	是	右下角圆角大小，单位为 vp

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
let receivedMessageBorderRadius: BorderRadiuses = {
  topLeft: 4,
  topRight: 8,
  bottomLeft: 8,
  bottomRight: 8
}
config.setReceivedMessageBorderRadius(receivedMessageBorderRadius);
RongIM.getInstance().conversationService().setConversationConfig(config);

修改边框色

边框色支持按消息方向来设置：

设置/获取接收的消息气泡边框色：setReceivedMessageBorderColor、getReceivedMessageBorderColor
设置/获取发送的消息气泡边框色：setSentMessageBorderColor、getSentMessageBorderColor

接口定义

TypeScript
/**
 * 设置接收的消息气泡边框色
 * @param objectName 消息类型的 objectName，为空字符串表示所有消息类型
 * @param color 边框颜色
 */
setReceivedMessageBorderColor(objectName: string, color: Color): void

/**
 * 获取接收的消息气泡边框色
 * @param objectName 消息类型的 objectName
 */
getReceivedMessageBorderColor(objectName: string): Color

/**
 * 设置发送的消息气泡边框色
 * @param objectName 消息类型的 objectName，为空字符串表示所有消息类型
 * @param color 边框颜色
 */
setSentMessageBorderColor(objectName: string, color: Color): void

/**
 * 获取发送的消息气泡边框色
 * @param objectName 消息类型的 objectName
 */
getSentMessageBorderColor(objectName: string): Color

参数说明

参数名	类型	必填	说明
`objectName`	`string`	是	消息类型的 objectName。为空字符串 `""` 表示所有消息类型；指定具体值（如 `"RC:TxtMsg"`）表示仅针对该消息类型
`color`	`Color`	是	边框颜色

使用示例

示例 1：修改特定消息类型的边框色

通过指定消息的 objectName 仅修改文本消息类型的边框色为灰色，其他消息类型不修改：

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setReceivedMessageBorderColor("RC:TxtMsg", Color.Gray);
RongIM.getInstance().conversationService().setConversationConfig(config);

示例 2：修改所有消息类型的边框色

修改全部消息类型的边框色为灰色：

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setReceivedMessageBorderColor("", Color.Gray);
RongIM.getInstance().conversationService().setConversationConfig(config);

示例 3：组合配置

通过指定消息的 objectName 仅修改文本消息类型的边框色为灰色，同时修改其余消息类型的边框色为蓝色，与接口调用顺序无关：

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setReceivedMessageBorderColor("RC:TxtMsg", Color.Gray);
config.setReceivedMessageBorderColor("", Color.Blue);
RongIM.getInstance().conversationService().setConversationConfig(config);

修改背景色

背景色支持按消息方向来设置：

设置/获取接收的消息气泡背景色：setReceivedMessageBackgroundColor、getReceivedMessageBackgroundColor
设置/获取发送的消息气泡背景色：setSentMessageBackgroundColor、getSentMessageBackgroundColor

接口定义

TypeScript
/**
 * 设置接收的消息气泡背景色
 * @param objectName 消息类型的 objectName，为空字符串表示所有消息类型
 * @param color 背景颜色
 */
setReceivedMessageBackgroundColor(objectName: string, color: Color): void

/**
 * 获取接收的消息气泡背景色
 * @param objectName 消息类型的 objectName
 */
getReceivedMessageBackgroundColor(objectName: string): Color

/**
 * 设置发送的消息气泡背景色
 * @param objectName 消息类型的 objectName，为空字符串表示所有消息类型
 * @param color 背景颜色
 */
setSentMessageBackgroundColor(objectName: string, color: Color): void

/**
 * 获取发送的消息气泡背景色
 * @param objectName 消息类型的 objectName
 */
getSentMessageBackgroundColor(objectName: string): Color

参数说明

参数名	类型	必填	说明
`objectName`	`string`	是	消息类型的 objectName。为空字符串 `""` 表示所有消息类型；指定具体值（如 `"RC:TxtMsg"`）表示仅针对该消息类型
`color`	`Color`	是	背景颜色

使用示例

示例 1：修改特定消息类型的背景色

通过指定消息的 objectName 仅修改文本消息类型的背景色为灰色，其他消息类型不修改：

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setReceivedMessageBackgroundColor("RC:TxtMsg", Color.Gray);
RongIM.getInstance().conversationService().setConversationConfig(config);

示例 2：修改所有消息类型的背景色

修改全部消息类型的背景色为灰色：

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setReceivedMessageBackgroundColor("", Color.Gray);
RongIM.getInstance().conversationService().setConversationConfig(config);

示例 3：组合配置

通过指定消息的 objectName 仅修改文本消息类型的背景色为灰色，同时修改其余消息类型的背景色为蓝色，与接口调用顺序无关：

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setReceivedMessageBackgroundColor("RC:TxtMsg", Color.Gray);
config.setReceivedMessageBackgroundColor("", Color.Blue);
RongIM.getInstance().conversationService().setConversationConfig(config);

自定义消息气泡子组件

IMKit 从 1.10.0 版本开始支持通过 setMessageBubbleComponentConfig 方法传入对应的 componentConfig 对象修改消息气泡的部分子组件。

接口定义

TypeScript
/**
 * 消息气泡组件配置
 * @since 1.10.0
 */
export interface MessageBubbleComponentConfig {
  /**
   * 组件标识
   */
  identifier: ComponentIdentifier,

  /**
   * 组件 WrappedBuilder
   * @since 1.6.0
   */
  component?: WrappedBuilder<MessageBubbleComponentData> | null,
}

/**
 * 消息气泡自定义组件数据，封装必要的参数透传给自定义组件
 * @since 1.10.0
 */
export class MessageBubbleComponentData {
  /**
   * 上下文
   */
  context: Context | undefined;
  
  /**
   * 消息体
   */
  uiMessage: UiMessage | undefined;
  
  /**
   * 头像配置
   */
  avatarConfig?: AvatarConfig
}

参数说明

MessageBubbleComponentConfig

参数名	类型	必填	说明	支持版本
`identifier`	`ComponentIdentifier`	是	组件标识，指定要自定义的组件类型。详见下方"支持的组件类型"	1.10.0
`component`	`WrappedBuilder<MessageBubbleComponentData>`	否	自定义组件构建器，用于构建自定义 UI 组件	1.6.0

MessageBubbleComponentData

参数名	类型	说明	支持版本
`context`	`Context`	应用上下文对象	1.10.0
`uiMessage`	`UiMessage`	消息对象，包含消息的详细数据	1.10.0
`avatarConfig`	`AvatarConfig`	头像配置信息，包含头像尺寸等属性	1.10.0

支持的组件类型

identifier 支持的组件类型说明：

组件类型	说明	支持版本
`MessageBubbleNicknameSuffix`	消息气泡中昵称后缀组件	1.10.0
`MessageBubbleAvatar`	消息气泡中头像组件	1.10.0

使用示例

示例 1：自定义消息气泡中的后缀组件

TypeScript
@Builder
export function buildNicknameSuffixComponent(data: MessageBubbleComponentData) {
  if (data.uiMessage?.message.conversationType === ConversationType.Group) {
    Image($r('app.media.app_icon')).width(15).height(15).margin({left: 5, bottom: 4})
  }
}
const messageBubbleComponentConfig: MessageBubbleComponentConfig = {
  identifier: ComponentIdentifier.MessageBubbleNicknameSuffix,
  component: wrapBuilder(buildNicknameSuffixComponent)
}
RongIM.getInstance().conversationService().setMessageBubbleComponentConfig(messageBubbleComponentConfig)

示例 2：自定义消息气泡中头像组件

TypeScript
@Builder
export function buildCustomMessageAvatar(data: MessageBubbleComponentData) {
  Stack({ alignContent: Alignment.Center }) {
    // 按需获取内置默认头像组件
    RongIM.getInstance().uiComponents().getDefaultMessageAvatar().builder(data)
    Image($r('app.media.avatar_frame_sample'))
      .width(data.avatarConfig?.size)
      .height(data.avatarConfig?.size)
      .objectFit(ImageFit.Contain)
      .hitTestBehavior(HitTestMode.Transparent)
  }
}
let messageBubbleAvatarComponentConfig: MessageBubbleComponentConfig = {
  identifier: ComponentIdentifier.MessageBubbleAvatar,
  component: wrapBuilder(buildCustomMessageAvatar),
}
RongIM.getInstance().conversationService().setMessageBubbleComponentConfig(messageBubbleAvatarComponentConfig)

自定义输入框按钮UI

从 1.5.1 版本开始，IMKit 支持配置会话页面输入框的 UI 组件。可通过 setInputAreaComponentConfig 接口设置自定义组件配置。

接口定义

TypeScript
export interface InputAreaComponentConfig {
  /**
   * 组件标识
   */
  identifier: ComponentIdentifier,
  
  /**
   * 组件 WrappedBuilder
   * @since 1.6.0
   */
  component: WrappedBuilder<[InputAreaComponentData]> | null,
}

/**
 * 输入区域自定义组件数据，封装必要的参数透传给自定义组件
 * @since 1.6.0
 */
export class InputAreaComponentData {
  /**
   * 上下文
   */
  context: Context | undefined;
  
  /**
   * 会话标识
   */
  convId: ConversationIdentifier | undefined;
  
  /**
   * 透传参数
   * 当 identifier 为某些枚举类型的情况下有值，其余情况下为空
   */
  data: string = "";
}

参数说明

InputAreaComponentConfig

参数名	类型	必填	说明	支持版本
`identifier`	`ComponentIdentifier`	是	组件标识，指定要自定义的组件类型。详见下方"支持的组件类型"	1.5.1
`component`	`WrappedBuilder<[InputAreaComponentData]>`	是	自定义组件构建器，用于构建自定义 UI 组件	1.6.0

InputAreaComponentData

参数名	类型	说明	支持版本
`context`	`Context`	应用上下文对象	1.6.0
`convId`	`ConversationIdentifier`	会话标识对象	1.6.0
`data`	`string`	透传参数。当 `identifier` 为 `InputBarVoiceButton` 时，值为 `"Voice"`（语音类型）或 `"Text"`（文本类型）；当 `identifier` 为 `InputBarEmoticonButton` 时，值为 `"Emoticon"`（表情类型）或 `"Text"`（文本类型）；当 `identifier` 为 `DestructBarVoiceButton` 时，值为 `"Voice"`（语音类型）或 `"Text"`（文本类型）	1.6.0

支持的组件类型

identifier 支持的组件类型说明：

组件类型	说明
`InputBarVoiceButton`	输入框左侧语音按钮
`InputBarEmoticonButton`	输入框表情按钮
`InputBarSendButton`	输入框发送按钮
`InputBarPluginButton`	输入框插件加号按钮
`InputBarExpandTextAreaButton`	文本输入组件输入了大于 2 行文本时，输入框左侧的展开输入按钮
`EmoticonBoardAddButton`	表情面板左下角的添加按钮

示例代码

TypeScript
// 设置接口
let InputBarPluginButton: InputAreaComponentConfig = {
  identifier: ComponentIdentifier.InputBarPluginButton,
  component: wrapBuilder(buildCustomInputBarPluginView),
}
RongIM.getInstance().conversationService().setInputAreaComponentConfig(InputBarPluginButton)
  
// 组件
@Builder
export function buildCustomInputBarPluginView(componentData: InputAreaComponentData) {
  CustomInputBarPluginView({ context: componentData.context, convId: componentData.convId, type: componentData.data })
}

@Component
export struct CustomInputBarPluginView {
  @Prop context: Context;
  @Prop convId: ConversationIdentifier;
  @Prop type: string;

  aboutToAppear(): void {
    console.log("CustomInputBarPluginView aboutToAppear " + this.type)
  }

  build() {
    Image($r('app.media.default_fmessage'))
      .size({ width: 30, height: 30 })
      .onTouch(() => {
        promptAction.showToast({ message: `点击了按钮` })
      })
  }
}

自定义会话页面按钮UI

从 1.6.0 版本开始，IMKit 支持配置会话页面的 UI 组件。可通过 setConversationContentComponentConfig 接口设置自定义组件配置。

接口定义

TypeScript
export interface ConversationContentComponentConfig {
  /**
   * 组件标识
   */
  identifier: ComponentIdentifier,

  /**
   * 组件 WrappedBuilder
   */
  component: WrappedBuilder<[ConversationContentComponentData]> | null,
}

/**
 * 会话自定义组件数据
 */
export class ConversationContentComponentData {
  /**
   * 上下文
   */
  context: Context | undefined;
  
  /**
   * 会话标识
   */
  convId: ConversationIdentifier | undefined;
  
  /**
   * 透传参数
   */
  data: number = 0;
  
  /**
   * 会话页面 ViewModel，用来执行后续的事件
   */
  conversationViewModel: IConversationViewModel | undefined
}

/**
 * ConversationViewModel 的能力接口
 */
export interface IConversationViewModel {
  /**
   * 进入会话时展示的未读消息的组件点击事件
   */
  onClickUnreadMessageButton(): void;
  
  /**
   * 进入会话时展示的未读@我的消息的组件点击事件
   */
  onClickUnreadMentionedMessageButton(): void;
  
  /**
   * 在进入会话后收到未读新消息的组件点击事件
   */
  onClickNewReceivedUnreadMessageButton(): void;
  
  /**
   * 获取输入框当前的文本输入组件的内容
   * @since 1.7.1
   */
  getInputTextAreaContent?(): string;
  
  /**
   * 获取消息列表
   * @since 1.7.1
   */
  getMessageList?(): UiMessage[];
  
  /**
   * 刷新某条消息
   * @since 1.7.1
   */
  refreshUiMessage?(message: Message): void;
}

参数说明

ConversationContentComponentConfig

参数名	类型	必填	说明	支持版本
`identifier`	`ComponentIdentifier`	是	组件标识，支持的类型：`ConversationUnreadMessageButton`（未读消息按钮）、`ConversationUnreadMentionedMessageButton`（未读@我的消息按钮）、`ConversationNewReceivedUnreadMessageButton`（新收到的未读消息按钮）	1.6.0
`component`	`WrappedBuilder<[ConversationContentComponentData]>`	是	自定义组件构建器	1.6.0

ConversationContentComponentData

参数名	类型	说明	支持版本
`context`	`Context`	应用上下文对象	1.6.0
`convId`	`ConversationIdentifier`	会话标识对象	1.6.0
`data`	`number`	透传参数。当 `identifier` 为 `ConversationNewReceivedUnreadMessageButton` 时，代表在会话中新收到的未读消息的数量；当 `identifier` 为 `ConversationUnreadMessageButton` 时，代表会话中的未读消息数量；当 `identifier` 为 `ConversationUnreadMentionedMessageButton` 时，代表当前@自己的未读消息的数量	1.6.0
`conversationViewModel`	`IConversationViewModel`	会话页面 ViewModel，用来执行后续的事件。当 `identifier` 为 `ConversationNewReceivedUnreadMessageButton` 时，调用 `onClickNewReceivedUnreadMessageButton` 执行新收到未读消息的点击事件；当 `identifier` 为 `ConversationUnreadMessageButton` 时，调用 `onClickUnreadMessageButton` 执行未读消息的点击事件；当 `identifier` 为 `ConversationUnreadMentionedMessageButton` 时，调用 `onClickUnreadMentionedMessageButton` 执行未读@我的消息的点击事件	1.6.0

IConversationViewModel

方法名	返回值	说明	支持版本
`onClickUnreadMessageButton`	`void`	进入会话时展示的未读消息的组件点击事件	1.6.0
`onClickUnreadMentionedMessageButton`	`void`	进入会话时展示的未读@我的消息的组件点击事件	1.6.0
`onClickNewReceivedUnreadMessageButton`	`void`	在进入会话后收到未读新消息的组件点击事件	1.6.0
`getInputTextAreaContent`	`string`	获取输入框当前的文本输入组件的内容	1.7.1
`getMessageList`	`UiMessage[]`	获取消息列表。注意：该返回列表仅用于读取，不建议修改	1.7.1
`refreshUiMessage`	`void`	刷新某条消息	1.7.1

使用示例

以下展示了进入会话后收到未读新消息的组件的自定义示例：

使用 alignRules 控制在屏幕中的位置
使用 ConversationContentComponentData.data 观察未读消息数
使用 ConversationContentComponentData.conversationViewModel 暴露会话页面能力，用来处理点击事件

示例 1：自定义未读消息按钮

TypeScript
@Builder
export function buildCustomConversationTopUnreadMessageButton(data: ConversationContentComponentData) {
  CustomConversationTopUnreadMessageButton({ context: data.context, convId: data.convId, unreadMessageCount: data.data, viewModel:data.conversationViewModel })
}

@Component
export struct CustomConversationTopUnreadMessageButton {
  @Prop context: Context;
  @Prop convId: ConversationIdentifier;
  @Prop unreadMessageCount: number;
  @Prop viewModel: IConversationViewModel;

  build() {
    if (this.unreadMessageCount > 10) {
      Row() {
        Image($r('app.media.rc_arrow')).width(12).height(9).objectFit(ImageFit.Contain)
        Text((this.unreadMessageCount > 99 ? "99+" : this.unreadMessageCount) + "条新消息")
          .fontSize(14)
          .fontColor($r('app.color.rc_color_111F2C'))
          .margin({ left: 6 })
      }
      .borderRadius({ topLeft: 24, bottomLeft: 24 })
      .height(48)
      .padding({ left: 10, right: 10 })
      .backgroundColor($r('app.color.rc_color_FFFFFF'))
      .alignRules({
        center: { anchor: "__container__", align: VerticalAlign.Center },
        right: { anchor: "__container__", align: HorizontalAlign.End }
      })
      .margin({ top: 14 })
      .onClick(() => {
        this.viewModel.onClickUnreadMessageButton()
      })
    }
  }
}

// 设置UI组件
let ConversationUnreadMessageButton: ConversationContentComponentConfig = {
  identifier: ComponentIdentifier.ConversationUnreadMessageButton,
  component: wrapBuilder(buildCustomConversationTopUnreadMessageButton),
}
RongIM.getInstance().conversationService().setConversationContentComponentConfig(ConversationUnreadMessageButton)

示例 2：设置其他按钮组件

TypeScript
// 自定义收到新的未读消息的UI组件
let ConversationNewReceivedUnreadMessageButton: ConversationContentComponentConfig = {
  identifier: ComponentIdentifier.ConversationNewReceivedUnreadMessageButton,
  component: wrapBuilder(buildCustomConversationBottomUnreadMessageButton),
}
RongIM.getInstance().conversationService().setConversationContentComponentConfig(ConversationNewReceivedUnreadMessageButton)

// 自定义顶部未读@我的消息的UI组件
let ConversationUnreadMentionedMessageButton: ConversationContentComponentConfig = {
  identifier: ComponentIdentifier.ConversationUnreadMentionedMessageButton,
  component: wrapBuilder(buildCustomConversationTopUnreadMentionedMessageButton),
}
RongIM.getInstance().conversationService().setConversationContentComponentConfig(ConversationUnreadMentionedMessageButton)

增加 + 号扩展栏插件

内置插件说明

IMKit 内置插件列表如下所示。其中位置插件 SDK 仅定义，实际需要 App 侧来实现。

插件	插件名称	插件名称常量
图片插件	ImagePlugin	`ImagePluginName` = `"RC:ImagePlugin"`
小视频插件	CameraPlugin	`CameraPluginName` = `"RC:CameraPlugin"`
文件插件	FilePlugin	`FilePluginName` = `"RC:FilePlugin"`
阅后即焚插件	DestructPlugin	`DestructPluginName` = `"RC:DestructPlugin"`
位置插件	LocationPlugin	`LocationPluginName` = `"RC:LocationPlugin"`

实现自定义插件

接口定义

TypeScript
/**
 * 扩展面板插件接口
 */
export interface IBoardPlugin {
  /**
   * 插件名，用来判断插件唯一标识
   * @returns 插件名
   * @version 1.4.3
   */
  pluginName(): string;
  
  /**
   * 返回插件的标题
   * @param context 上下文
   * @returns 标题
   */
  obtainTitle(context: Context): string | Resource;
  
  /**
   * 返回插件的图标
   * @param context 上下文
   * @returns 图标资源
   */
  obtainImage(context: Context): Resource;
  
  /**
   * 插件的点击事件
   * @param context 上下文
   * @param conId 会话标识
   */
  onClick(context: Context, conId: ConversationIdentifier): void;
  
  /**
   * 是否在会话中显示该插件
   * @param conId 会话标识
   * @returns 是否显示，true 显示；false 不显示
   */
  onFilter(conId: ConversationIdentifier): boolean;
}

方法说明

IBoardPlugin

方法名	参数	返回值	说明	支持版本
`pluginName`	无	`string`	插件的唯一标识名称。如果不设置则无法进行查找、替换操作	1.4.3
`obtainTitle`	`context: Context`	`string \| Resource`	返回插件显示的标题	-
`obtainImage`	`context: Context`	`Resource`	返回插件显示的图标资源	-
`onClick`	`context: Context` `conId: ConversationIdentifier`	`void`	插件的点击事件回调。开发者可在此处理具体的点击逻辑	-
`onFilter`	`conId: ConversationIdentifier`	`boolean`	过滤条件函数，返回 `true` 表示在该会话中显示该插件，返回 `false` 表示不显示	-

示例代码

TypeScript
import { IBoardPlugin } from '@rongcloud/imkit';
import { ConversationIdentifier } from '@rongcloud/imlib';
import { promptAction } from '@kit.ArkUI';

/**
 * 自定义插件
 */
export class CustomInfoMessagePlugin implements IBoardPlugin {

  /**
   * 插件名，用来判断插件唯一标识
   */
  pluginName(): string {
    return "CustomInfoMessagePlugin"
  }
  
  /**
   * 返回插件的标题
   */
  obtainTitle(context: Context): string | Resource {
    return "自定义小灰条消息"
  }

  /**
   * 返回插件的图标
   */
  obtainImage(context: Context): Resource {
    return $r("app.media.startIcon");
  }

  /**
   * 插件的点击事件
   */
  onClick(context: Context, conId: ConversationIdentifier): void {
    if (!conId) {
      return;
    }

    // 处理具体的点击事件
    // 开发者按照实际情况处理
    promptAction.showToast({ message: '点击了自定义插件' })
  }

  /**
   * 是否在会话中显示该插件
   */
  onFilter(conId: ConversationIdentifier): boolean {
    return true;
  }
}

自定义插件UI

从 1.5.1 版本开始，IMKit 默认允许配置插件的UI组件。可以根据插件名替换自定义插件的UI，如果想替换SDK内置的插件UI，插件名参照内置插件说明。

TypeScript
@Builder
export function buildCustomMessagePluginView(context: Context, convId: ConversationIdentifier) {
  CustomMessagePluginView({ context: context, convId: convId })
}

@Component
export struct CustomMessagePluginView {
  @Prop context: Context;
  @Prop convId: ConversationIdentifier;

  build() {
    Column() {
      Text("自定义插件名").width("100%").fontSize(12).textAlign(TextAlign.Center)
      Image($r("app.media.rc_file_apk_icon")).width(40).height(40)
    }.width("100%").height("100%")
    .justifyContent(FlexAlign.SpaceEvenly).alignItems(HorizontalAlign.Center)
  }
}

// 替换自定义插件的UI组件
RongIM.getInstance().conversationService().setBoardPluginView("CustomInfoMessagePlugin", wrapBuilder(buildCustomMessagePluginView))

将插件放到扩展栏里面

需要在聊天页面出现前调用

添加插件

TypeScript
let customInfoMessagePlugin = new CustomInfoMessagePlugin();
RongIM.getInstance().conversationService().addBoardPlugin(customInfoMessagePlugin);

将插件放到指定位置

提示

1.4.3 版本起，如果想调整 SDK 默认展示的插件以及插件的顺序，需要通过动态配置扩展面板插件功能配置。

TypeScript
let index : number = 0
let customInfoMessagePlugin = new CustomInfoMessagePlugin();
RongIM.getInstance().conversationService().insertBoardPlugin(index, customInfoMessagePlugin);

替换指定位置的插件，如果没有对应的索引，会将插件放到最后

提示

1.4.3 版本起，如果想调整 SDK 默认展示的插件以及插件的顺序，需要通过动态配置扩展面板插件功能配置。

TypeScript
let index : number = 0
let customInfoMessagePlugin = new CustomInfoMessagePlugin();
RongIM.getInstance().conversationService().replaceBoardPlugin(index, customInfoMessagePlugin);

移除特定的插件

提示

1.4.3 版本起，如果想调整 SDK 默认展示的插件以及插件的顺序，需要通过动态配置扩展面板插件功能配置

TypeScript
let customInfoMessagePlugin = new CustomInfoMessagePlugin();
RongIM.getInstance().conversationService().removeBoardPlugin(customInfoMessagePlugin);

根据插件名移除特定的插件

自定义插件实现 pluginName() 接口返回插件名，便可以通过 removeBoardPluginByName 来移除插件。
系统插件均实现了 pluginName()，可以参照上面表格中插件对应的名字，通过 removeBoardPluginByName 来移除插件。

TypeScript
RongIM.getInstance().conversationService().removeBoardPluginByName("插件名");

清空当前的插件。

提示

该接口只能清空通过 addBoardPlugin、insertBoardPlugin、replaceBoardPlugin 添加的插件。通过动态配置扩展面板插件可以做到彻底清空。

TypeScript
RongIM.getInstance().conversationService().clearBoardPlugin();

动态配置扩展面板插件

如果应用程序需要动态添加、删除扩展面板插件，或者调整插件位置，建议通过创建自定义的扩展面板配置实现这些自定义需求。

您需要实现 IExtensionConfig，创建自定义的扩展面板配置类，重写 getPluginModules() 方法。您可以增加或删除扩展项，也可以调整各插件的位置。在 SDK 初始化之后，调用 setExtensionConfig 方法设置好自定义的输入配置，SDK 会根据此配置展示扩展面板。

示例代码

TypeScript
// 获取当前的插件配置
let config = RongIM.getInstance().conversationService().getExtensionConfig()

let mCustomExtensionConfig: IExtensionConfig = {
  getPluginModules: (convId: ConversationIdentifier) => {
    // 根据插件配置获取对应会话标识的插件
    let currentPlugins = config.getPluginModules(ConversationIdentifier.createWith2(ConversationType.Private, "TargetID"))
    let plugins: ArrayList<IBoardPlugin> = new ArrayList<IBoardPlugin>()
    // 这里示范了去除文件插件的操作。当然也可以根据 pluginName 来重新排序插件等操作。
    for (let plugin of currentPlugins) {
      if (plugin.pluginName && plugin.pluginName() !== FilePluginName) {
        plugins.add(plugin)
      }
    }
    // 添加业务侧自定义的插件
    plugins.add(new TestPlugin1())
    plugins.add(new TestPlugin2())
    return plugins
  }
}

/// 在 SDK 初始化之后调用
RongIM.getInstance().conversationService().setExtensionConfig(mCustomExtensionConfig)

消息头像圆角控制

您可以通过全局配置控制消息头像圆角展示，需要在会话页面展示前设置。

接口定义

TypeScript
setMessageAvatarStyle(style: AvatarStyle): void

参数说明

参数名	类型	必填	说明
`style`	`AvatarStyle`	是	头像样式。可选值：`AvatarStyle.Cycle`（圆形）、`AvatarStyle.Rectangle`（矩形）

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig();
config.setMessageAvatarStyle(AvatarStyle.Cycle);
RongIM.getInstance().conversationService().setConversationConfig(config);

修改消息可撤回的最大时间

IMKit 默认允许在消息发送后 180 秒内撤回。您可以通过全局配置调整该上限，需要在会话页面展示前设置。

接口定义

TypeScript
setMaxRecallDuration(duration: number): void

参数说明

参数名	类型	必填	说明
`duration`	`number`	是	可撤回的最大时间，单位为秒

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setMaxRecallDuration(180)
RongIM.getInstance().conversationService().setConversationConfig(config)

修改撤回后可重新编辑的时间

IMKit 默认允许在消息撤回后 30 秒内可点击重新编辑，仅文本消息支持撤回再编辑。您可以通过全局配置调整该上限，需要在会话页面展示前设置。

接口定义

TypeScript
setMaxEditableDuration(duration: number): void

参数说明

参数名	类型	必填	说明
`duration`	`number`	是	可重新编辑的最大时间，单位为秒

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setMaxEditableDuration(30)
RongIM.getInstance().conversationService().setConversationConfig(config)

文本消息字体高亮颜色

IMKit 默认允许配置 SDK 内置文本消息中的 URL、手机号、@ 信息等高亮字体颜色，默认黑色。您可以通过全局配置调整，需要在会话页面展示前设置。

接口定义

TypeScript
setStyleFontColor(color): void

参数说明

参数名	类型	必填	说明
`color`	颜色值	是	高亮字体颜色，如 `Color.Blue`

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setStyleFontColor(Color.Blue)
RongIM.getInstance().conversationService().setConversationConfig(config)

文本和引用消息内容自定义渲染

从 1.6.0 版本开始，IMKit 支持配置 SDK 内置文本、引用消息的文本内容渲染拦截事件接口。您可以通过全局配置调整，需要在会话页面展示前设置。

注意

该接口如果返回 true，那么文本消息字体高亮颜色则不会生效。

接口定义

TypeScript
setMessageRenderTextInterceptor(interceptor: (controller: TextController, content: string) => boolean): void

参数说明

拦截器函数

参数名	类型	说明
`controller`	`TextController`	文本控制器对象，用于设置样式化字符串
`content`	`string`	消息的文本内容
返回值	`boolean`	返回 `true` 表示拦截并使用自定义渲染，返回 `false` 表示不拦截，使用默认渲染

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
let interceptor = (controller: TextController, content: string) => {
  if ("不需要拦截的场景") {
    return false
  }
  let styledString: MutableStyledString = new MutableStyledString(content)
  // 内容匹配到 regContent 则变成红色高亮
  let regContent = "融云"
  let matches = content.matchAll(new RegExp(regContent, 'g'));
  // 是否匹配到内容
  let hasMatch = false
  for (let match of matches) {
    hasMatch = true
    const index = match.index
    if (index != undefined) {
      styledString.setStyle({
        start: index,
        length: regContent.length,
        styledKey: StyledStringKey.FONT,
        styledValue: new TextStyle({ fontColor: Color.Red })
      })
    }
  }
  controller.setStyledString(styledString)
  return true
}
config.setMessageRenderTextInterceptor(interceptor)
RongIM.getInstance().conversationService().setConversationConfig(config)

设置文件消息的文件类型图标

IMKit 默认允许配置 SDK 内置文件消息的文件类型图标。您可以通过全局配置调整，需要在会话页面展示前设置。

设置文件消息的文件类型图标

您可以通过 setFileMessageIcons 覆盖默认的文件消息的文件类型图标。

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
//设置图片
let iconsMap: Map<string, Resource> = new Map<string, Resource>();
//覆盖SDK默认图片
iconsMap.set('doc', $r("app.media.doc_icon"));
iconsMap.set('mp3', $r("app.media.mp3_icon"));
iconsMap.set('pdf', $r("app.media.pdf_icon"));
iconsMap.set('rmvb', $r("app.media.rmvb_icon"));
iconsMap.set('default', $r("app.media.rc_default_icon"));
config.setFileMessageIcons(iconsMap);
RongIM.getInstance().conversationService().setConversationConfig(config)

获取文件消息内的文件类型图标 map

您可以通过 getFileMessageIcons 获取文件消息内的文件类型图标 map。

示例代码

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.getFileMessageIcons();

可以通过 getFileMessageIcon 获取文件消息内的文件类型图标，如果找不到，返回 SDK 内置的默认图标。

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.getFileMessageIcon('doc');

修改消息重发开关

IMKit 从 1.4.3 版本开始支持消息发送失败时自动消息重发。

提示

为了跟 iOS、Android 端现有逻辑保持一致，该配置默认值为为 true。

从 1.4.3 以下版本升级的客户，会改变默认行为，如果不想消息重发，需要主动设置为 false。

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setEnableResendMessage(false)
RongIM.getInstance().conversationService().setConversationConfig(config)

群消息回执配置

IMKit 从 1.7.1 版本开始支持群消息回执支持配置每条消息都显示已读未读信息。该配置默认为false。

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setEnableShowAllGroupReceipt(true)
RongIM.getInstance().conversationService().setConversationConfig(config)

引用消息点击跳转行为配置

从 1.6.0 版本开始，IMKit 默认允许配置 SDK 内置引用消息的引用消息点击跳转行为。您可以通过全局配置调整，需要在会话页面展示前设置。

SDK 配置默认为 JumpToDetailPage。

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setReferencedMessageClickType(ReferencedMessageClickType.ScrollToReferencedMessage)
RongIM.getInstance().conversationService().setConversationConfig(config)

ReferencedMessageClickType 说明

TypeScript
// 引用消息的被引用消息体点击后的处理方式
export enum ReferencedMessageClickType {
  /**
   * 跳转到预览页面。
   */
  JumpToDetailPage,
  /**
   * 滚动到被引用消息，如果被引用消息在本地数据库中不存在，则不会进行跳转，并提示"未找到被引用消息"
   */
  ScrollToReferencedMessage
}

设置主窗口 WindowStage

从 1.8.0 版本开始，IMKit 支持配置 WindowStage，用于处理 Kit 页面的全屏与非全屏适配。您需要在会话页面展示前完成配置。

提示

配置 WindowStage 有助于 IMKit 正确处理页面布局，确保在不同显示模式下都能正常展示。

TypeScript
export default class EntryAbility extends UIAbility {

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 方式一：通过配置设置
    let config = RongIM.getInstance().conversationService().getConversationConfig()
    config.setMainWindowStage(() => {
      return windowStage
    })
    RongIM.getInstance().conversationService().setConversationConfig(config)
    
    // 方式二：通过 AppStorage 设置
    AppStorage.set('windowStage', windowStage)
    
    windowStage.loadContent('pages/SplashPage');
  }

}

会话页面事件

IMKit 提供了会话页面事件监听器 ConversationEventListener，可监听会话页面中输入 @ 时跳转用户列表选择用户事件、当输入状态变化时的事件。需要在会话页面展示前设置。

接口定义

TypeScript
export interface ConversationEventListener {
  /**
   * 输入 @ 时，跳转用户列表选择用户
   * @param select 选中的用户信息回调
   */
  onInputMention?: (select: (user: UserInfoModel) => void) => void;

  /**
   * 当输入状态变化时
   * @param isEditing 是否正在编辑
   */
  onEditChange?: (isEditing: boolean) => void;
}

方法说明

ConversationEventListener

方法名	参数	返回值	说明
`onInputMention`	`select: (user: UserInfoModel) => void`	`void`	输入 @ 时触发。`select` 为回调函数，在选择用户后调用，将用户信息传递给 SDK
`onEditChange`	`isEditing: boolean`	`void`	输入状态变化时触发。`isEditing` 为 `true` 表示正在编辑，`false` 表示停止编辑

设置/移除会话页面事件监听

您可以使用 RongIM 的 addConversationEventListener 和 removeConversationEventListener 方法添加或移除监听器。

警告

建议在合适的时机移除监听器，避免内存泄露。如果在页面中监听，建议在 aboutToAppear 中添加监听，在 aboutToDisappear 中移除监听。

示例代码

TypeScript
// 添加监听器
RongIM.getInstance().conversationService().addConversationEventListener(listener);
// 移除监听器
RongIM.getInstance().conversationService().removeConversationEventListener(listener);

使用示例

示例 1：输入 @ 时跳转页面并返回数据

当会话页面输入框输入 @ 时，会触发 onInputMention 方法。如果未设置，SDK 默认不处理该事件。

处理流程：

收到 onInputMention 时跳转到用户列表页面选择用户
返回到当前页面后，调用 select 回传 UserInfoModel 给 SDK

TypeScript
let conversationEventListener: ConversationEventListener = {
  onInputMention: (select: (user: UserInfoModel) => void) => {
    if (this.conId.conversationType === ConversationType.Group) {
      // 1. 跳转到用户列表页面选择用户
      // new NavPathStack().pushPath();
      
      // 2. 调用 select 回传 UserInfoModel 给 SDK
      const userInfo = new UserInfoModel('userId', 'userName', '')
      select(userInfo);
    }
  }
}

示例 2：监听输入状态变化

当会话页面输入状态发生变化时，会触发 onEditChange 方法。如果未设置，SDK 默认不处理该事件。

TypeScript
let conversationEventListener: ConversationEventListener = {
  onEditChange: (isEditing: boolean) => {
    // isEditing 代表输入状态发生变化
  }
}

会话页面代理接口

IMKit 提供了会话页面代理接口 ConversationComponentDelegate，可监听会话页面生命周期。

接口定义

TypeScript
export interface ConversationComponentDelegate {
  /**
   * IConversationViewModel 的创建回调
   * @version 1.7.1
   */
  onViewModelBind?: (vm: IConversationViewModel) => void;

  /**
   * IConversationViewModel 的清理回调
   * @version 1.7.1
   */
  onViewModelClear?: () => void;

  /**
   * 当前会话输入区域组件可见性配置
   * 仅影响当前 ConversationComponent 会话页面
   * @since 1.10.0
   */
  componentVisibilityConfig?: Map<ComponentIdentifier, Visibility>;
}

/**
 * 会话页面 ViewModel 接口
 */
export interface IConversationViewModel {
  /**
   * 进入会话时展示的未读消息的组件点击事件
   */
  onClickUnreadMessageButton(): void;
  
  /**
   * 进入会话时展示的未读@我的消息的组件点击事件
   */
  onClickUnreadMentionedMessageButton(): void;
  
  /**
   * 在进入会话后收到未读新消息的组件点击事件
   */
  onClickNewReceivedUnreadMessageButton(): void;

  /**
   * 更新输入框的文本组件的内容
   * @since 1.7.0
   */
  onChangeInputTextAreaContent?(text: string): void;
  
  /**
   * 获取输入框当前的文本输入组件的内容
   * @since 1.7.0
   */
  getInputTextAreaContent?(): string;

  /**
   * 获取消息列表
   * @since 1.7.1
   */
  getMessageList?(): UiMessage[];

  /**
   * 刷新某条消息
   * @since 1.7.1
   */
  refreshUiMessage?(message: Message): void;
}

方法说明

ConversationComponentDelegate

方法名/属性名	类型	说明	支持版本
`onViewModelBind`	`(vm: IConversationViewModel) => void`	IConversationViewModel 的创建回调。可在此方法中获取 ViewModel 实例	1.7.1
`onViewModelClear`	`() => void`	IConversationViewModel 的清理回调。在页面销毁时调用	1.7.1
`componentVisibilityConfig`	`Map<ComponentIdentifier, Visibility>`	当前会话输入区域组件可见性配置。仅影响当前 ConversationComponent 会话页面	1.10.0

IConversationViewModel

方法名	参数	返回值	说明	支持版本
`onClickUnreadMessageButton`	无	`void`	进入会话时展示的未读消息的组件点击事件	-
`onClickUnreadMentionedMessageButton`	无	`void`	进入会话时展示的未读@我的消息的组件点击事件	-
`onClickNewReceivedUnreadMessageButton`	无	`void`	在进入会话后收到未读新消息的组件点击事件	-
`onChangeInputTextAreaContent`	`text: string`	`void`	更新输入框的文本组件的内容	1.7.0
`getInputTextAreaContent`	无	`string`	获取输入框当前的文本输入组件的内容	1.7.0
`getMessageList`	无	`UiMessage[]`	获取消息列表。注意：该返回列表仅用于读取，不建议修改	1.7.1
`refreshUiMessage`	`message: Message`	`void`	刷新某条消息	1.7.1

使用示例

示例 1：获取 ViewModel

构建 ConversationComponentDelegate 接口传给 ConversationComponent，在 onViewModelBind 方法中可以拿到 IConversationViewModel。

TypeScript
@Component
struct CustomChatPage {
  private vm: IConversationViewModel | undefined
  private delegate: ConversationComponentDelegate = {
    onViewModelBind: (vm: IConversationViewModel) => {
      this.vm = vm;
    },
    onViewModelClear: () => {
      this.vm = undefined
    }
  }

  build() {
    ConversationComponent({
      conversationData: this.conversationComponentData,
      pageShow: this.pageShow,
      isEdit: this.isEdit,
      delegate: this.delegate,
    }).layoutWeight(1)
  }
}

示例 2：按会话维度控制输入框按钮可见性

componentVisibilityConfig 支持按会话设置输入区按钮的可见性，满足"一个用户在多个会话使用不同扩展能力"的诉求。

提示

仅影响当前 ConversationComponent 页面
支持的组件标识查看 InputAreaComponentConfig

TypeScript
@Component
struct CustomChatPage {
  private vm: IConversationViewModel | undefined
  private delegate: ConversationComponentDelegate = {
    onViewModelBind: (vm: IConversationViewModel) => {
      this.vm = vm;
    },
    onViewModelClear: () => {
      this.vm = undefined
    },
    componentVisibilityConfig: new Map([
      [ComponentIdentifier.InputBarVoiceButton, Visibility.None],
      [ComponentIdentifier.InputBarEmoticonButton, Visibility.Visible],
      [ComponentIdentifier.InputBarSendButton, Visibility.Visible],
      [ComponentIdentifier.InputBarPluginButton, Visibility.None],
    ])
  }

  build() {
    ConversationComponent({
      conversationData: this.conversationComponentData,
      pageShow: this.pageShow,
      isEdit: this.isEdit,
      delegate: this.delegate,
    }).layoutWeight(1)
  }
}

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

消息点击事件​

接口定义​

方法说明​

示例代码​

增加消息气泡的长按事件​

接口定义​

参数说明​

示例代码​

配置消息气泡的长按更多选项​

接口定义​

参数说明​

示例代码​

修改消息气泡的 UI 配置​

修改边框圆角大小​

接口定义​

参数说明​

示例代码​

修改边框色​

接口定义​

参数说明​

使用示例​

示例 1：修改特定消息类型的边框色​

示例 2：修改所有消息类型的边框色​

示例 3：组合配置​

修改背景色​

接口定义​

参数说明​

使用示例​

示例 1：修改特定消息类型的背景色​

示例 2：修改所有消息类型的背景色​

示例 3：组合配置​

自定义消息气泡子组件​

接口定义​

参数说明​

支持的组件类型​

使用示例​

示例 1：自定义消息气泡中的后缀组件​

示例 2：自定义消息气泡中头像组件​

自定义输入框按钮UI​

接口定义​

参数说明​

支持的组件类型​

示例代码​

自定义会话页面按钮UI​

接口定义​

参数说明​

使用示例​

示例 1：自定义未读消息按钮​

示例 2：设置其他按钮组件​

增加 + 号扩展栏插件​

内置插件说明​

实现自定义插件​

接口定义​

方法说明​

示例代码​

自定义插件UI​

将插件放到扩展栏里面​

添加插件​

将插件放到指定位置​

替换指定位置的插件，如果没有对应的索引，会将插件放到最后​

移除特定的插件​

根据插件名移除特定的插件​

清空当前的插件。​

消息点击事件

接口定义

方法说明

示例代码

增加消息气泡的长按事件

接口定义

参数说明

示例代码

配置消息气泡的长按更多选项

接口定义

参数说明

示例代码

修改消息气泡的 UI 配置

修改边框圆角大小

接口定义

参数说明

示例代码

修改边框色

接口定义

参数说明

使用示例

示例 1：修改特定消息类型的边框色

示例 2：修改所有消息类型的边框色

示例 3：组合配置

修改背景色

接口定义

参数说明

使用示例

示例 1：修改特定消息类型的背景色

示例 2：修改所有消息类型的背景色

示例 3：组合配置

自定义消息气泡子组件

接口定义

参数说明

支持的组件类型

使用示例

示例 1：自定义消息气泡中的后缀组件

示例 2：自定义消息气泡中头像组件

自定义输入框按钮UI

接口定义

参数说明

支持的组件类型

示例代码

自定义会话页面按钮UI

接口定义

参数说明

使用示例

示例 1：自定义未读消息按钮

示例 2：设置其他按钮组件

增加 + 号扩展栏插件

内置插件说明

实现自定义插件

接口定义

方法说明

示例代码

自定义插件UI

将插件放到扩展栏里面

添加插件

将插件放到指定位置

替换指定位置的插件，如果没有对应的索引，会将插件放到最后

移除特定的插件

根据插件名移除特定的插件

清空当前的插件。

动态配置扩展面板插件

示例代码

消息头像圆角控制

接口定义

参数说明

示例代码

修改消息可撤回的最大时间

接口定义

参数说明

示例代码

修改撤回后可重新编辑的时间

接口定义

参数说明

示例代码

文本消息字体高亮颜色

接口定义

参数说明