ZIM 升级指南

2026-06-24

本文介绍 ZIM React Native SDK 版本升级时的一些说明和注意事项。

3.0.0 升级指南

注意

本次版本（3.0.0）移除了部分已废弃超过 1 年的接口及相关枚举值和字段，同时对部分接口新增了废弃标记。React Native SDK 同时涉及 TypeScript 接口层和原生层（iOS/Android）的变更，请参考以下说明完成迁移。

废弃接口删除

ZIM 初始化接口（create）

废弃的旧版 create(appID: number) 接口已被移除，请使用接受 ZIMAppConfig 参数的 create 接口代替。

新版本用法

const appConfig: ZIMAppConfig = {
    appID: 12345678,
    appSign: 'appSign',
};
ZIM.create(appConfig);

const appConfig: ZIMAppConfig = {
    appID: 12345678,
    appSign: 'appSign',
};
ZIM.create(appConfig);

ZIM 登录接口（login）

废弃的旧版 login(userInfo: ZIMUserInfo, token: string) 接口已被移除，请使用接受 userID 和 ZIMLoginConfig 参数的 login 接口代替。

新版本用法

const loginConfig: ZIMLoginConfig = {
    userName: 'userName',
    token: '', // 若使用 Token 鉴权，请填写 Token
    isOfflineLogin: false,
};
await zim.login('userID', loginConfig);

const loginConfig: ZIMLoginConfig = {
    userName: 'userName',
    token: '', // 若使用 Token 鉴权，请填写 Token
    isOfflineLogin: false,
};
await zim.login('userID', loginConfig);

ZIM 消息发送接口（sendMessage）

废弃的 sendPeerMessage、sendRoomMessage、sendGroupMessage 以及 sendMediaMessage 接口已被移除，请统一使用带 notification 参数的 sendMessage 接口代替。

新版本用法

const textMessage: ZIMTextMessage = {
    type: 1,
    message: 'Hello',
};
const config: ZIMMessageSendConfig = {
    priority: 1,
};
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // 消息发送前的业务逻辑
    },
};
zim.sendMessage(textMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 消息发送结果
    })
    .catch((errorInfo) => {
        // 消息发送失败
    });

const textMessage: ZIMTextMessage = {
    type: 1,
    message: 'Hello',
};
const config: ZIMMessageSendConfig = {
    priority: 1,
};
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // 消息发送前的业务逻辑
    },
};
zim.sendMessage(textMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 消息发送结果
    })
    .catch((errorInfo) => {
        // 消息发送失败
    });

ZIM 媒体文件下载接口（downloadMediaFile）

废弃的旧版 downloadMediaFile（不含 config 参数）接口已被移除，请使用含 ZIMMediaDownloadConfig 参数的新版 downloadMediaFile 接口代替。

新版本用法

const config: ZIMMediaDownloadConfig = {};
zim.downloadMediaFile(imageMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // 下载进度
}).then((res: ZIMMediaDownloadedResult) => {
    // 下载完成
}).catch((errorInfo) => {
    // 下载失败
});

const config: ZIMMediaDownloadConfig = {};
zim.downloadMediaFile(imageMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // 下载进度
}).then((res: ZIMMediaDownloadedResult) => {
    // 下载完成
}).catch((errorInfo) => {
    // 下载失败
});

ZIM 消息接收回调接口

在 2.18.0 中已废弃的 receivePeerMessage、receiveRoomMessage、receiveGroupMessage 事件在本版本中正式移除，建议迁移至 messageReceived。

新版本用法

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // 根据 conversationType 处理不同类型会话的消息
});

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // 根据 conversationType 处理不同类型会话的消息
});

ZIM 呼叫邀请回调接口

旧版 callInvitationRejected、callInvitationAccepted、callInviteesAnsweredTimeout 事件已被移除，请使用 callUserStateChanged 事件代替。callInvitationTimeout 事件的回调参数也已更新，新增了 ZIMCallInvitationTimeoutInfo 参数。

新版本用法

zim.on('callUserStateChanged', (zim: ZIM, result: ZIMCallUserStateChangedEventResult) => {
    const { callUserList, callID } = result;
    // callUserList 包含状态变更的用户列表
    // 可统一处理接受、拒绝、超时等状态变更
});

zim.on('callUserStateChanged', (zim: ZIM, result: ZIMCallUserStateChangedEventResult) => {
    const { callUserList, callID } = result;
    // callUserList 包含状态变更的用户列表
    // 可统一处理接受、拒绝、超时等状态变更
});

importLocalMessages / exportLocalMessages 接口删除

importLocalMessages 和 exportLocalMessages 接口已在 3.0.0 版本中暂时移除，且暂无替代接口。后续版本将重新开放该功能，请关注 SDK 更新日志。

新增废弃接口（建议迁移）

ZIM 消息接收回调接口

peerMessageReceived、roomMessageReceived、groupMessageReceived 事件在本版本中新增废弃标记，当前仍可正常使用，但建议尽快迁移至 messageReceived。

建议使用（新事件）

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // 根据 conversationType 处理不同类型会话的消息
});

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // 根据 conversationType 处理不同类型会话的消息
});

ZIMGroupConversation 废弃

ZIMGroupConversation 在 3.0.0 中已被废弃，其中的 isDisabled 和 mutedExpiredTime 字段请通过基类 ZIMConversation 的对应属性替代：

ZIMGroupConversation（已废弃）	ZIMConversation（替代属性）
`isDisabled`	`isConversationDisabled`
`mutedExpiredTime`	`selfMutedExpiredTime`

新版本用法

const isDisabled: boolean = conversation.isConversationDisabled;
const mutedExpiredTime: number = conversation.selfMutedExpiredTime;

const isDisabled: boolean = conversation.isConversationDisabled;
const mutedExpiredTime: number = conversation.selfMutedExpiredTime;

枚举值移除

ZIMMessageType 枚举值移除

ZIMMessageType.System（值为 30）已从 ZIMMessageType 枚举中移除，同时 ZIMSystemMessage 类型也已被移除。如需发送系统级指令，请使用 ZIMCommandMessage 代替。

新版本用法

// 使用 ZIMCommandMessage 代替 ZIMSystemMessage
const commandMessage: ZIMCommandMessage = {
    type: 2,
    message: new Uint8Array([/* payload bytes */]),
};
zim.sendMessage(commandMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送结果
    });

// 使用 ZIMCommandMessage 代替 ZIMSystemMessage
const commandMessage: ZIMCommandMessage = {
    type: 2,
    message: new Uint8Array([/* payload bytes */]),
};
zim.sendMessage(commandMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送结果
    });

ZIMCallUserState 枚举值移除

ZIMCallUserState.Offline（值为 4）已从 ZIMCallUserState 枚举中移除，请检查代码中是否有对该枚举值的判断并将其删除。

// 以下枚举值已移除，请检查并删除代码中对该值的引用
// ZIMCallUserState.Offline  （值为 4）

// 以下枚举值已移除，请检查并删除代码中对该值的引用
// ZIMCallUserState.Offline  （值为 4）

字段变更

ZIMUserFullInfo.userAvatarUrl 废弃

ZIMUserFullInfo.userAvatarUrl 已废弃，请使用 ZIMUserFullInfo.baseInfo.userAvatarUrl 代替。

新版本用法

const avatarUrl: string = userFullInfo.baseInfo.userAvatarUrl;

const avatarUrl: string = userFullInfo.baseInfo.userAvatarUrl;

ZIMMessage.conversationSeq 替换为 messageSeq

ZIMMessage.conversationSeq 已被移除，请使用 ZIMMessage.messageSeq 代替。

新版本用法

const seq: number = message.messageSeq;

const seq: number = message.messageSeq;

ZIMMessageDeletedInfo.isDeleteConversationAllMessage 移除

ZIMMessageDeletedInfo.isDeleteConversationAllMessage 已被移除，请使用 ZIMMessageDeletedInfo.messageDeleteType 代替。

新版本用法

const deleteType: ZIMMessageDeleteType = deletedInfo.messageDeleteType;
// 通过 deleteType 判断是单条删除还是全量删除

const deleteType: ZIMMessageDeleteType = deletedInfo.messageDeleteType;
// 通过 deleteType 判断是单条删除还是全量删除

ZIMGroupMemberInfo.memberAvatarUrl 移除

ZIMGroupMemberInfo.memberAvatarUrl 已被移除，请使用 ZIMGroupMemberInfo.userAvatarUrl 代替。

新版本用法

const avatarUrl: string = groupMemberInfo.userAvatarUrl;

const avatarUrl: string = groupMemberInfo.userAvatarUrl;

ZIMGroupOperatedInfo 结构变更

ZIMGroupOperatedInfo.operatedUserInfo 字段已被移除，其内部字段已平铺到 ZIMGroupOperatedInfo，可直接从 ZIMGroupOperatedInfo 中获取对应字段。

新版本用法

// 直接从 ZIMGroupOperatedInfo 获取字段
const operatorUserID: string = groupOperatedInfo.userID;
const operatorUserName: string = groupOperatedInfo.userName;
const operatorAvatarUrl: string = groupOperatedInfo.userAvatarUrl;

// 直接从 ZIMGroupOperatedInfo 获取字段
const operatorUserID: string = groupOperatedInfo.userID;
const operatorUserName: string = groupOperatedInfo.userName;
const operatorAvatarUrl: string = groupOperatedInfo.userAvatarUrl;

ZIMCallInvitationSentInfo.errorInvitees 替换

ZIMCallInvitationSentInfo.errorInvitees 已被移除，请使用 ZIMCallInvitationSentInfo.errorUserList 代替，类型由 ZIMCallUserInfo[] 变更为 ZIMErrorUserInfo[]。

新版本用法

zim.callInvite(invitees, config)
    .then((res: ZIMCallInvitationSentResult) => {
        for (const errorUser of res.errorUserList) {
            // errorUser.userID, errorUser.reason
        }
    });

zim.callInvite(invitees, config)
    .then((res: ZIMCallInvitationSentResult) => {
        for (const errorUser of res.errorUserList) {
            // errorUser.userID, errorUser.reason
        }
    });

ZIMConversationChangeInfo 字段变更

ZIMConversationChangeInfo 中的 event 属性（类型 ZIMConversationEvent）已被移除，请使用同结构下的 action 属性（类型 ZIMConversationChangeAction）代替。

新版本用法

zim.on('conversationChanged', (zim: ZIM, result: ZIMConversationChangedEventResult) => {
    result.infoList.forEach(changeInfo => {
        const action: ZIMConversationChangeAction = changeInfo.action;
        // 根据 action 处理会话变更
    });
});

zim.on('conversationChanged', (zim: ZIM, result: ZIMConversationChangedEventResult) => {
    result.infoList.forEach(changeInfo => {
        const action: ZIMConversationChangeAction = changeInfo.action;
        // 根据 action 处理会话变更
    });
});

类型接口名称变更

ZIMEventHandler.ts 中所有以 ZIMEventOf 为前缀的 TypeScript interface 已按统一规范重命名：

命名规则：ZIMEventOf<Name>Result → ZIM<Name>EventResult

典型示例：

旧类型名	新类型名
`ZIMEventOfConversationMessageReceivedResult`	`ZIMConversationMessageReceivedEventResult`
`ZIMEventOfCallInvitationRejectedResult`	`ZIMCallInvitationRejectedEventResult`
`ZIMEventOfCallInvitationAcceptedResult`	`ZIMCallInvitationAcceptedEventResult`
`ZIMEventOfCallInviteesAnsweredTimeoutResult`	`ZIMCallInviteesAnsweredTimeoutEventResult`

影响范围说明

此变更对绝大多数开发者透明，无需任何代码改动。原因：zim.on(eventName, callback) 的回调参数类型由 TypeScript 根据事件名自动推导，无需显式引用这些接口名称。

仅当您在代码中显式标注了 ZIMEventOf* 类型名称时，才会出现 TypeScript 编译报错，按上表完成类型名替换即可。

枚举值重命名

ZIMGroupMessageNotificationStatus

ZIMGroupMessageNotificationStatus.Disturb 已重命名为 ZIMGroupMessageNotificationStatus.DoNotDisturb，请检查代码中所有相关引用并替换。

新版本用法

const status = ZIMGroupMessageNotificationStatus.DoNotDisturb;

const status = ZIMGroupMessageNotificationStatus.DoNotDisturb;

setRoomMembersAttributes 行为变更

从 3.0.0 版本开始，如果通过 setRoomMembersAttributes 设置房间用户属性时，isDeleteAfterOwnerLeft 为 false，那么房间用户属性不会在用户离开房间后删除。在 2.x.x 版本中，用户离开房间后会先删除属性，用户回到房间后会再次恢复。

2.19.0 升级指南

注意

从 2.19.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.19.0 版本时，请您阅读以下指南。

downloadMediaFile 及相关回调

废弃原接口 downloadMediaFile，请使用同名 downloadMediaFile 代替。新版本的 downloadMediaFile 新增了 config 参数，新增了 config 参数，可用于指定下载组合消息中的单个媒体内容。

ZIMMediaDownloadingProgress 以及 ZIMMediaDownloadedResult 中，参数 message 的类型从 ZIMMediaMessage 变更为 ZIMMessage，以适应组合消息使用，TypeScript 开发者需要根据 IDE 的编译错误提示修正调用。

2.19.0版本用法（下载组合消息指定媒体内容）

// 假设 multipleMessage.messageInfoList[0] 是文本消息，multipleMessage.messageInfoList[1] 是图片消息
const multipleMessage: ZIMMessage = {
    type: 10,
    messageInfoList: [
        { type: 1, message: "Hello, World!" },
        { type: 11, fileLocalPath: '' }
    ]
}

const config: ZIMMediaDownloadConfig = {
    // 指定下载图片消息
    messageInfoIndex: 1
}
// !mark(1:4)

zim.downloadMediaFile(multipleMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // 下载进度
    // 开发者需要判断 message 的类型并转换成对应类型的消息
    if (message.type === 10) {
// !mark
        const multipleMessage: ZIMMultipleMessage = message as ZIMMultipleMessage
        // 处理组合消息
    }
    // 其他类型消息的处理
    ......

}).then((res: ZIMMediaDownloadedResult) => {
    // 下载完成
    // 开发者需要判断 message 的类型并转换成对应类型的消息
    if (res.message.type === 10) {
// !mark
        const multipleMessage = res.message as ZIMMultipleMessage
        // 处理组合消息
    }
    // 其他类型消息的处理
    ......
}).catch((errorInfo) => {
    // 下载失败
})

// 假设 multipleMessage.messageInfoList[0] 是文本消息，multipleMessage.messageInfoList[1] 是图片消息
const multipleMessage: ZIMMessage = {
    type: 10,
    messageInfoList: [
        { type: 1, message: "Hello, World!" },
        { type: 11, fileLocalPath: '' }
    ]
}

const config: ZIMMediaDownloadConfig = {
    // 指定下载图片消息
    messageInfoIndex: 1
}
// !mark(1:4)

zim.downloadMediaFile(multipleMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // 下载进度
    // 开发者需要判断 message 的类型并转换成对应类型的消息
    if (message.type === 10) {
// !mark
        const multipleMessage: ZIMMultipleMessage = message as ZIMMultipleMessage
        // 处理组合消息
    }
    // 其他类型消息的处理
    ......

}).then((res: ZIMMediaDownloadedResult) => {
    // 下载完成
    // 开发者需要判断 message 的类型并转换成对应类型的消息
    if (res.message.type === 10) {
// !mark
        const multipleMessage = res.message as ZIMMultipleMessage
        // 处理组合消息
    }
    // 其他类型消息的处理
    ......
}).catch((errorInfo) => {
    // 下载失败
})

sendMessage 及相关回调

自 2.19.0 版本后，发送多媒体消息需使用 sendMessage 接口。sendMediaMessage 接口被废弃，以实现发送消息的统一性和便于后续的通用扩展。

ZIMMessageSendNotification 中，onMediaUploadingProgress 回调方法的 message 参数类型从 ZIMMessage 变更为 ZIMMediaMessage，以确保仅媒体消息会被回调通知，Typescript 开发者需要根据 IDE 的编译错误提示修正调用。(目前仅使用 Typescripts 开发语言且使用了 replyMessage 接口的开发者会受到需要解决编译报错的影响)。

2.19.0版本用法

const imageMessage: ZIMMessage = {
    type: 11,
    fileLocalPath: ''
}

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // 开发者可以监听这个回调执行消息发送前的业务逻辑
    },
// !mark
    onMessageUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => {
        // 多媒体上传进度
    }
}

// !mark
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 消息发送结果
    }).catch((errorInfo) => {
        // 消息发送失败
    })

const imageMessage: ZIMMessage = {
    type: 11,
    fileLocalPath: ''
}

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // 开发者可以监听这个回调执行消息发送前的业务逻辑
    },
// !mark
    onMessageUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => {
        // 多媒体上传进度
    }
}

// !mark
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 消息发送结果
    }).catch((errorInfo) => {
        // 消息发送失败
    })

2.18.0 升级指南

注意

从 2.18.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.18.0 版本时，请您阅读以下指南。

单聊消息接收回调

原单聊消息接收回调 receivePeerMessage 已被废弃，请使用 peerMessageReceived 代替。

新回调支持以下功能：

用户在线时，可通过此回调接收在线单聊消息。
用户重新登录 ZIM SDK 后，可以通过此回调接收离线期间（最长7天）收到的所有单聊消息。

//新接口
peerMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

//老接口
receivePeerMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

//新接口
peerMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

//老接口
receivePeerMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

房间消息接收回调

原房间消息接收回调 receiveRoomMessage 已被废弃，请使用 roomMessageReceived 代替。

新回调支持以下功能：

用户在线时，可通过此回调接收在线房间消息。
用户从离线恢复到在线后，若仍在房间中，即可通过此回调接收离线期间内的所有房间消息。

//新接口
roomMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

//老接口
receiveRoomMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

//新接口
roomMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

//老接口
receiveRoomMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

群组消息接收回调

原群组消息接收回调 receiveGroupMessage 已被废弃，请使用 groupMessageReceived 代替。

新回调支持以下功能：

用户在线时，可通过此回调接收在线群组消息。
用户重新登录 ZIM SDK 后，可以通过通过此回调接收离线期间（最长7天）收到的所有群聊消息。

//新接口
groupMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

    
//老接口
receiveGroupMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

//新接口
groupMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

    
//老接口
receiveGroupMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

2.16.0 升级指南

注意

从 2.16.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.16.0 版本时，请您阅读以下指南。

callCancel

说明

以下变更仅对进阶模式呼叫邀请而言。

在新版本的 callCancel 中，如果参数 userIDs 包含一个 userID，则该接口将仅取消邀请该被叫用户。如果 userIDs 参数为空，则该接口将对所有被叫用户取消邀请。

而对于旧版本的 callCancel 接口，无论参数 userIDs 是否为空，均视为对所有被叫用户取消邀请。

由于旧版 ZIM SDK 不兼容单独取消逻辑，因此如果您既需要保留使用老版本 ZIM 实现的取消逻辑，又需要使用新版本的单独取消功能，请隔离新老版本 ZIM 之间的呼叫功能。

2.16.0版本用法

// 单独取消 userIdA 、userIdB
const callID = 'xxxx';
const invitees = ['userIdA','userIdB'];  // 被邀请人ID列表
const config: ZIMCallCancelConfig  = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // 操作成功
    })
    .catch((err: ZIMError) => {
        // 操作失败
    })

// 取消整个呼叫邀请,当整个呼叫中所有被叫都未接受时可以调用成功    
const callID = 'xxxx';
const invitees = [];  // 被邀请人ID列表
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // 操作成功
    })
    .catch((err: ZIMError) => {
        // 操作失败
    })

// 单独取消 userIdA 、userIdB
const callID = 'xxxx';
const invitees = ['userIdA','userIdB'];  // 被邀请人ID列表
const config: ZIMCallCancelConfig  = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // 操作成功
    })
    .catch((err: ZIMError) => {
        // 操作失败
    })

// 取消整个呼叫邀请,当整个呼叫中所有被叫都未接受时可以调用成功    
const callID = 'xxxx';
const invitees = [];  // 被邀请人ID列表
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // 操作成功
    })
    .catch((err: ZIMError) => {
        // 操作失败
    })