跳到主要内容

自定义消息

IMKit 支持自定义消息类型,并通过 IMKit 发送、接收和展示自定义消息。

注册自定义消息

注册消息是发送自定义消息的关键步骤,如不注册则无法发送自定义消息。

在建立 IM 连接之前,使用 imkit 实例的 registerMessageType 方法来注册自定义消息,该方法会返回自定义消息构造函数。

// registerMessageType 中参数设置需要按照参数说明顺序传递。不可改变顺序,
// 例如:如需发送状态消息 searchProp 参数不可不设置,可设置为 []
const PersonMessage = imkit.registerMessageType('kit:person', true, true);
参数类型说明是否必传
messageTypestring消息类型。请勿使用 RC: 开头的类型名,以免和 SDK 默认的消息名称冲突。如需多端互通(例如 Web 端与 Android、iOS 等移动端互通消息),注册的消息类型名必须保持多端一致,否则无法互通。
isPersitedboolean是否存储。
isCountedboolean是否计数。
searchPropstring[]搜索字段,web 端无需设置,搜索字段值设置为数字时取值范围为 (-Math.pow(2, 64), Math.pow(2, 64)) 且为整数
isStatusMessageboolean是否是状态消息。状态消息不存储、不计数,接收方在线时才能收到
提示

注意事项:

  1. 注册消息类型(imkit.registerMessageType)必须在 connect 之前调用,必须放在发送接收该自定义消息之前。
  2. 推荐将所有注册自定义消息代码放在 init 方法之后。
  3. 请尽量把应用中所有涉及到的自定义消息一次性统一注册,且同类型消息仅调用一次注册。

发送自定义消息

应用程序注册自定义消息后,可获取自定义消息体构造函数。在发送自定义消息前,使用该函数构建自定义消息体,例如 new PersonMessage({})。消息属性 key 可自定义,保持多端一致即可。

// 如已引入可忽略
import { ConversationType } from '@rongcloud/imlib-next'

// PersonMessage 中的属性需要多端保持一致,可根据用户侧需要进行定义。
const message = new PersonMessage({ key1: 'value1', key2: 'value2' })
const option = null;
const conversation = {
conversationType: ConversationType.PRIVATE,
targetId: "<targetId>",
};

imkit.sendMessage(conversation, message, option).then(res => {
console.info('发送消息结果:',res);
})
参数说明必传
conversation消息发送目标会话信息
message待发送的消息内容,通过 new 自定义消息得到消息实例
options定义发送行为中的一些可选项,如是否可拓展,推送等
  • conversation

    参数类型说明必传
    conversationTypeConversationType会话类型
    targetIdstring接收方 Id
  • options

提示

options 为可选项,options 中所有属性均为可选项,非必传。

参数类型说明
isStatusMessageboolean是否为状态消息
disableNotificationboolean是否发送静默消息
pushContentstringPush 信息
pushDatastringPush 通知携带的附加信息
isMentionedboolean是否为 @ 消息,只当 conversationType 值为 ConversationType.GROUP 时有效
directionalUserIdListstring[]用于发送群定向消息,只当 conversationType 值为 ConversationType.GROUP 时有效
isVoipPushboolean当对方为 iOS 设备且未在线时,其将收到 Voip Push. 此配置对 Android 无影响
canIncludeExpansionboolean是否允许消息被拓展
expansion[key: string]: string消息拓展内容数据
isFilerWhiteBlacklistboolean黑/白名单
pushConfigIPushConfig移动端推送配置(与 Android、iOS 端的 MessagePushConfig 作用相似)

设置自定义消息展示样式

应用程序需要在 IMKit SDK 初始化时传入 customMessage 对象实例,在该实例中设置自定义消息的样式。SDK 在会根据初始化时在 设置好的样式展示已发送或接收的自定义消息。

// 构造 IMKit 初始化参数
const customMessage = {
// 普通消息展示
userMessage: {
// key 为自定义消息的 messageType,return 的元素中暂不支持设置 class,如需设置样式可设置为行内样式。
'kit:person': (message) => {
const content = message.content;
return `<div style='padding: 0.5em 0.8333em;'>来自 ${content.name} 的好友请求</div>`;
}
},
// 通知类消息展示
notifyMessage: {
// key 为自定义消息的 messageType,return 的元素中暂不支持设置 class,如需设置样式可设置为行内样式。
'kit:notify': (message) => {
const content = message.content
const string = `<div>来自 ${content.name} 的好友请求</div>`
return string;
}
},
// 会话最后一条消息展示
lastMessage:{
// key 为自定义消息的 messageType,return 的元素中暂不支持设置 class,如需设置样式可设置为行内样式。
'kit:person': (message) => {
const content = message.content;
return `[好友请求]`;
},
'kit:notify': (message) => {
const content = message.content
const string = `[不带头像好友请求]`
return string;
}
}
};

// 特别注意:此处 init 仅为展示自定义消息设置,应用内不需要多次进行初始化
imkit.init({
customMessage:customMessage
});

提示

特别注意:

  1. 此处示例代码中的 init 调用仅为展示自定义消息设置,应用内不需要多次进行初始化。
  2. 存在自定义消息但未设置展示格式,会导致消息无法展示或展示为空。

customMessage 中传入的对象可包含以下参数:

参数说明
userMessage普通消息展示
notifyMessage通知类消息展示
lastMessage会话列表最后一条消息展示

上述参数所对应的展示位置可参见下图:

(height=300)

提示

如存在自定义消息但未设置展示格式,会导致消息无法展示或展示为空。