APIs

基准：ZIMKit Flutter v2.0.0（2026-10-14 与源码核对）

This document describes the APIs available in ZIMKit, including initialization, conversation management, messaging, group operations, and user management.

Table of Contents

• ZIMKit Singleton
  • init
  • uninit
  • getVersion
• Conversation APIs
  • getConversationListNotifier
  • getConversation
  • getTotalUnreadMessageCount
  • deleteConversation
  • deleteAllConversation
  • clearUnreadCount
  • loadMoreConversation
  • getOfflineConversationInfo
  • updateConversationPinnedState
  • setConversationNotificationStatus
  • queryUser
• Message APIs
  • getMessageListNotifier
  • getOnMessageReceivedNotifier
  • loadMoreMessage
  • sendTextMessage
  • replyMessage
  • sendFileMessage
  • sendMediaMessage
  • sendCustomMessage
  • sendCombineMessage
  • queryCombineMessageDetail
  • deleteMessage
  • deleteAllMessage
  • recallMessage
  • updateLocalExtendedData
  • addMessageReaction
  • deleteMessageReaction
  • downloadMediaFile
• Group APIs
  • createGroup
  • joinGroup
  • addUsersToGroup
  • removeUsersFromGroup
  • leaveGroup
  • queryGroupInfo
  • disbandGroup
  • transferGroupOwner
  • queryGroupMemberInfo
  • queryGroupOwner
  • queryGroupMemberList
  • queryGroupMemberCount
  • setGroupMemberRole
  • getGroupStateChangedEventStream
  • getGroupNameUpdatedEventStream
  • getGroupAvatarUrlUpdatedEventStream
  • getGroupNoticeUpdatedEventStream
  • getGroupAttributesUpdatedEventStream
  • getGroupMemberStateChangedEventStream
  • getGroupMemberInfoUpdatedEventStream
• User APIs
  • connectUser
  • renewToken
  • disconnectUser
  • currentUser
  • queryUser
  • updateUserInfo
  • getConnectionStateChangedEventStream
• Helper APIs
  • registerAppLifecycleStateChangedListener
  • unregisterAppLifecycleStateChangedListener
  • isAppLocked
  • setForwardMessages
  • getForwardMessages
  • getForwardType
  • clearForwardMessages

---

ZIMKit Singleton

init

• Description Initializes the ZIMKit SDK with the given app credentials and configuration.

• Prototype

  Future<void> init({
    required int appID,
    String appSign = '',
    String appSecret = '',
    ZIMKitConfig? config,
    ZIMKitEvents? events,
  })
  

• Example

  await ZIMKit().init(
    appID: yourAppID,
    appSign: yourAppSign,
    config: ZIMKitConfig(),
    events: ZIMKitEvents(),
  );
  

uninit

• Description Uninitializes the ZIMKit SDK and releases all resources.

• Prototype

  Future<void> uninit()
  

• Example

  await ZIMKit().uninit();
  

getVersion

• Description Returns the current version string of ZIMKit.

• Prototype

  String getVersion()
  

• Example

  final version = ZIMKit().getVersion();
  print('ZIMKit version: $version');
  

---

Conversation APIs

getConversationListNotifier

• Description Gets a Future that resolves to a notifier for the conversation list.

• Prototype

  Future<ZIMKitConversationListNotifier> getConversationListNotifier()
  

• Example

  final notifier = await ZIMKit().getConversationListNotifier();
  

getConversation

• Description Gets a ValueNotifier for a specific conversation by ID and type.

• Prototype

  ValueNotifier<ZIMKitConversation> getConversation(
    String id,
    ZIMConversationType type,
  )
  

• Example

  final conversation = ZIMKit().getConversation('user123', ZIMConversationType.peer);
  

getTotalUnreadMessageCount

• Description Gets a notifier for the total unread message count across all conversations.

• Prototype

  ValueNotifier<int> getTotalUnreadMessageCount()
  

• Example

  final unreadCount = ZIMKit().getTotalUnreadMessageCount();
  

deleteConversation

• Description Deletes a conversation and optionally its messages.

• Prototype

  Future<void> deleteConversation(
    String id,
    ZIMConversationType type, {
    bool isAlsoDeleteMessages = false,
    bool isAlsoDeleteFromServer = true,
  })
  

• Example

  await ZIMKit().deleteConversation(
    'conversation123',
    ZIMConversationType.peer,
    isAlsoDeleteMessages: true,
  );
  

deleteAllConversation

• Description Deletes all conversations.

• Prototype

  Future<void> deleteAllConversation({
    bool isAlsoDeleteFromServer = true,
    bool isAlsoDeleteMessages = false,
  })
  

• Example

  await ZIMKit().deleteAllConversation(isAlsoDeleteMessages: true);
  

clearUnreadCount

• Description Clears the unread count for a specific conversation.

• Prototype

  Future<void> clearUnreadCount(
    String conversationID,
    ZIMConversationType conversationType,
  )
  

• Example

  await ZIMKit().clearUnreadCount('user123', ZIMConversationType.peer);
  

loadMoreConversation

• Description Loads more conversations from the server.

• Prototype

  Future<int> loadMoreConversation()
  

• Example

  final count = await ZIMKit().loadMoreConversation();
  

getOfflineConversationInfo

• Description Gets information about offline message cache.

• Prototype

  Future<ZegoZIMKitOfflineMessageCacheInfo> getOfflineConversationInfo({
    bool selfDestructing = true,
  })
  

• Example

  final info = await ZIMKit().getOfflineConversationInfo();
  

updateConversationPinnedState

• Description Updates the pinned state of a conversation.

• Prototype

  Future<void> updateConversationPinnedState(
    String conversationID,
    ZIMConversationType conversationType,
    bool isPinned,
  )
  

• Example

  await ZIMKit().updateConversationPinnedState(
    'conversation123',
    ZIMConversationType.peer,
    true,
  );
  

setConversationNotificationStatus

• Description Sets the notification status (mute/unmute) for a conversation.

• Prototype

  Future<void> setConversationNotificationStatus(
    String conversationID,
    ZIMConversationType conversationType,
    ZIMConversationNotificationStatus status,
  )
  

• Example

  await ZIMKit().setConversationNotificationStatus(
    'conversation123',
    ZIMConversationType.peer,
    ZIMConversationNotificationStatus.notNotify,
  );
  

queryUser

• Description Queries user information by user ID.

• Prototype

  Future<ZIMUserFullInfo> queryUser(String userID)
  

• Example

  final userInfo = await ZIMKit().queryUser('user123');
  

---

Message APIs

getMessageListNotifier

• Description Gets a notifier for the message list of a specific conversation.

• Prototype

  Future<ZIMKitMessageListNotifier> getMessageListNotifier(
    String conversationID,
    ZIMConversationType type,
  )
  

• Example

  final notifier = await ZIMKit().getMessageListNotifier('user123', ZIMConversationType.peer);
  

getOnMessageReceivedNotifier

• Description Gets a notifier for receiving new messages.

• Prototype

  ValueNotifier<ZIMKitReceivedMessages?> getOnMessageReceivedNotifier()
  

• Example

  final notifier = ZIMKit().getOnMessageReceivedNotifier();
  

loadMoreMessage

• Description Loads more messages for a conversation.

• Prototype

  Future<int> loadMoreMessage(
    String conversationID,
    ZIMConversationType conversationType,
  )
  

• Example

  await ZIMKit().loadMoreMessage('user123', ZIMConversationType.peer);
  

sendTextMessage

• Description Sends a text message to a conversation.

• Prototype

  Future<void> sendTextMessage(
    String conversationID,
    ZIMConversationType type,
    String text, {
    ZIMKitMessage? repliedMessage,
    FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
    Function(ZIMKitMessage)? onMessageSent,
  })
  

• Example

  await ZIMKit().sendTextMessage(
    'user123',
    ZIMConversationType.peer,
    'Hello!',
  );
  

replyMessage

• Description Replies to a specific message with text.

• Prototype

  Future<void> replyMessage(
    String conversationID,
    ZIMConversationType type,
    ZIMKitMessage repliedMessage,
    String text, {
    FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
    Function(ZIMKitMessage)? onMessageSent,
  })
  

• Example

  await ZIMKit().replyMessage(
    'user123',
    ZIMConversationType.peer,
    originalMessage,
    'This is a reply',
  );
  

sendFileMessage

• Description Sends files sequentially. By default, known image, video, and audio extensions select their matching message type; set autoDetectType to false to send each item as a file message. The optional progress callback reports upload progress for this call.

• Prototype

  Future<void> sendFileMessage(
    String conversationID,
    ZIMConversationType type,
    List<ZIMKitPlatformFile> files, {
    bool autoDetectType = true,
    ZIMMediaUploadingProgress? mediaUploadingProgress,
    FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
    Function(ZIMKitMessage)? onMessageSent,
  })
  

• Example

  await ZIMKit().sendFileMessage(
    'user123',
    ZIMConversationType.peer,
    [file],
  );
  

sendMediaMessage

• Description Sends media messages (images, videos, audio) sequentially. The optional progress callback reports upload progress for this call.

• Prototype

  Future<void> sendMediaMessage(
    String conversationID,
    ZIMConversationType type,
    List<ZIMKitPlatformFile> files, {
    ZIMMediaUploadingProgress? mediaUploadingProgress,
    FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
    Function(ZIMKitMessage)? onMessageSent,
  })
  

• Example

  await ZIMKit().sendMediaMessage(
    'user123',
    ZIMConversationType.peer,
    [imageFile],
  );
  

sendCustomMessage

• Description Sends a custom message with user-defined type and content.

• Prototype

  Future<void> sendCustomMessage(
    String conversationID,
    ZIMConversationType type, {
    required int customType,
    required String customMessage,
    String? searchedContent,
    FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
    Function(ZIMKitMessage)? onMessageSent,
  })
  

• Example

  await ZIMKit().sendCustomMessage(
    'user123',
    ZIMConversationType.peer,
    customType: 1001,
    customMessage: '{"action": "like"}',
  );
  

sendCombineMessage

• Description Sends a combined message containing multiple messages.

• Prototype

  Future<void> sendCombineMessage(
    String conversationID,
    ZIMConversationType type, {
    required String title,
    required String summary,
    required List<ZIMKitMessage> messageList,
    FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
    Function(ZIMKitMessage)? onMessageSent,
  })
  

• Example

  await ZIMKit().sendCombineMessage(
    'user123',
    ZIMConversationType.peer,
    title: 'Chat History',
    summary: ['Message 1', 'Message 2'],
    messageList: messages,
  );
  

queryCombineMessageDetail

• Description Queries the detail of a combined message.

• Prototype

  Future<List<ZIMKitMessage>> queryCombineMessageDetail(
    ZIMKitMessage message,
  )
  

• Example

  final messages = await ZIMKit().queryCombineMessageDetail(combineMessage);
  

deleteMessage

• Description Deletes specified messages from a conversation.

• Prototype

  Future<void> deleteMessage(List<ZIMKitMessage> messages)
  

• Example

  await ZIMKit().deleteMessage([message1, message2]);
  

deleteAllMessage

• Description Deletes all messages in a conversation.

• Prototype

  Future<void> deleteAllMessage({
    required String conversationID,
    required ZIMConversationType conversationType,
    required bool isAlsoDeleteServerMessage,
  })
  

• Example

  await ZIMKit().deleteAllMessage(
    conversationID: 'user123',
    conversationType: ZIMConversationType.peer,
    isAlsoDeleteServerMessage: true,
  );
  

recallMessage

• Description Recalls (deletes) a sent message within the time limit.

• Prototype

  Future<void> recallMessage(ZIMKitMessage message)
  

• Example

  await ZIMKit().recallMessage(message);
  

updateLocalExtendedData

• Description Updates local extended data for a message.

• Prototype

  Future<void> updateLocalExtendedData(
    ZIMKitMessage message,
    String localExtendedData,
  )
  

• Example

  await ZIMKit().updateLocalExtendedData(message, '{"key": "value"}');
  

addMessageReaction

• Description Adds a reaction (emoji) to a message.

• Prototype

  Future<void> addMessageReaction(
    ZIMKitMessage message,
    String reactionType,
  )
  

• Example

  await ZIMKit().addMessageReaction(message, '👍');
  

deleteMessageReaction

• Description Deletes a reaction from a message.

• Prototype

  Future<void> deleteMessageReaction(
    ZIMKitMessage message,
    String reactionType,
  )
  

• Example

  await ZIMKit().deleteMessageReaction(message, '👍');
  

downloadMediaFile

• Description Downloads media file for a message (image, video, audio, file).

• Prototype

  void downloadMediaFile(ZIMKitMessage message)
  

• Example

  ZIMKit().downloadMediaFile(message);
  

---

Group APIs

createGroup

• Description Creates a new group with the specified name and initial members.

• Prototype

  Future<String?> createGroup(
    String name,
    List<String> inviteUserIDs, {
    String id = '',
  })
  

• Example

  final groupID = await ZIMKit().createGroup(
    'My Group',
    ['user1', 'user2'],
  );
  

joinGroup

• Description Joins an existing group.

• Prototype

  Future<int> joinGroup(String conversationID)
  

• Example

  final errorCode = await ZIMKit().joinGroup('group123');
  

addUsersToGroup

• Description Adds users to an existing group.

• Prototype

  Future<int> addUsersToGroup(
    String conversationID,
    List<String> userIDs,
  )
  

• Example

  await ZIMKit().addUsersToGroup('group123', ['user4', 'user5']);
  

removeUsersFromGroup

• Description Removes users from a group.

• Prototype

  Future<int> removeUsersFromGroup(
    String conversationID,
    List<String> userIDs,
  )
  

• Example

  await ZIMKit().removeUsersFromGroup('group123', ['user4']);
  

leaveGroup

• Description Leaves a group.

• Prototype

  Future<int> leaveGroup(String conversationID)
  

• Example

  await ZIMKit().leaveGroup('group123');
  

queryGroupInfo

• Description Queries group information.

• Prototype

  ValueNotifier<ZIMKitGroupInfo> queryGroupInfo(String conversationID)
  

• Example

  final groupInfo = ZIMKit().queryGroupInfo('group123');
  

disbandGroup

• Description Disbands (deletes) a group. Only the group owner can perform this action.

• Prototype

  Future<int> disbandGroup(String conversationID)
  

• Example

  await ZIMKit().disbandGroup('group123');
  

transferGroupOwner

• Description Transfers group ownership to another member.

• Prototype

  Future<int> transferGroupOwner(
    String conversationID,
    String toUserID,
  )
  

• Example

  await ZIMKit().transferGroupOwner('group123', 'newOwnerID');
  

queryGroupMemberInfo

• Description Queries information about a specific group member.

• Prototype

  Future<ZIMGroupMemberInfo?> queryGroupMemberInfo(
    String conversationID,
    String userID,
  )
  

• Example

  final memberInfo = await ZIMKit().queryGroupMemberInfo('group123', 'user123');
  

queryGroupOwner

• Description Gets a notifier for the group owner information.

• Prototype

  ValueNotifier<ZIMGroupMemberInfo?> queryGroupOwner(String conversationID)
  

• Example

  final owner = ZIMKit().queryGroupOwner('group123');
  

queryGroupMemberList

• Description Gets a notifier for the list of group members. onError receives a final query failure after any eligible relogin retry; callers can show an error and retry the query.

• Prototype

  ListNotifier<ZIMGroupMemberInfo> queryGroupMemberList(
    String conversationID, {void Function(Object error)? onError})
  

• Example

  final memberList = ZIMKit().queryGroupMemberList('group123');
  

queryGroupMemberCount

• Description Gets a notifier for the count of group members.

• Prototype

  ValueNotifier<int> queryGroupMemberCount(String conversationID)
  

• Example

  final count = ZIMKit().queryGroupMemberCount('group123');
  

setGroupMemberRole

• Description Sets the role for a group member.

• Prototype

  Future<int> setGroupMemberRole({
    required String conversationID,
    required String userID,
    required int role,
  })
  

• Example

  await ZIMKit().setGroupMemberRole(
    conversationID: 'group123',
    userID: 'user123',
    role: ZIMGroupMemberRole.manager,
  );
  

getGroupStateChangedEventStream

• Description Gets a stream for group state changed events.

• Prototype

  Stream<ZIMKitEventGroupStateChanged> getGroupStateChangedEventStream()
  

• Example

  ZIMKit().getGroupStateChangedEventStream().listen((event) {
    print('Group state changed: ${event.state}');
  });
  

getGroupNameUpdatedEventStream

• Description Gets a stream for group name updated events.

• Prototype

  Stream<ZIMKitEventGroupNameUpdated> getGroupNameUpdatedEventStream()
  

• Example

  ZIMKit().getGroupNameUpdatedEventStream().listen((event) {
    print('Group name updated to: ${event.groupName}');
  });
  

getGroupAvatarUrlUpdatedEventStream

• Description Gets a stream for group avatar URL updated events.

• Prototype

  Stream<ZIMKitEventGroupAvatarUrlUpdated> getGroupAvatarUrlUpdatedEventStream()
  

• Example

  ZIMKit().getGroupAvatarUrlUpdatedEventStream().listen((event) {
    print('Group avatar updated');
  });
  

getGroupNoticeUpdatedEventStream

• Description Gets a stream for group notice updated events.

• Prototype

  Stream<ZIMKitEventGroupNoticeUpdated> getGroupNoticeUpdatedEventStream()
  

• Example

  ZIMKit().getGroupNoticeUpdatedEventStream().listen((event) {
    print('Group notice updated: ${event.notice}');
  });
  

getGroupAttributesUpdatedEventStream

• Description Gets a stream for group attributes updated events.

• Prototype

  Stream<ZIMKitEventGroupAttributesUpdated> getGroupAttributesUpdatedEventStream()
  

• Example

  ZIMKit().getGroupAttributesUpdatedEventStream().listen((event) {
    print('Group attributes updated');
  });
  

getGroupMemberStateChangedEventStream

• Description Gets a stream for group member state changed events (joined/left).

• Prototype

  Stream<ZIMKitEventGroupMemberStateChanged> getGroupMemberStateChangedEventStream()
  

• Example

  ZIMKit().getGroupMemberStateChangedEventStream().listen((event) {
    print('Member ${event.userID} ${event.state}');
  });
  

getGroupMemberInfoUpdatedEventStream

• Description Gets a stream for group member info updated events.

• Prototype

  Stream<ZIMKitEventGroupMemberInfoUpdated> getGroupMemberInfoUpdatedEventStream()
  

• Example

  ZIMKit().getGroupMemberInfoUpdatedEventStream().listen((event) {
    print('Member info updated: ${event.userID}');
  });
  

---

User APIs

connectUser

• Description Connects a user to the ZIM service with the given credentials.

• Prototype

  Future<int> connectUser({
    required String id,
    String name = '',
    String avatarUrl = '',
    String token = '',
  })
  

• Example

  await ZIMKit().connectUser(
    id: 'user123',
    name: 'John Doe',
    avatarUrl: 'https://example.com/avatar.png',
    token: tokenFromYourServer,
  );
  

renewToken

• Description Renews the current login token. Obtain the new token from your server.

• Prototype

  Future<int> renewToken(String token)
  

• Returns Returns 0 on success, or the ZIM error code on failure.

• Example

  final errorCode = await ZIMKit().renewToken(tokenFromYourServer);
  if (errorCode != 0) {
    debugPrint('Token renewal failed: $errorCode');
  }
  

disconnectUser

• Description Disconnects the current user from the ZIM service.

• Prototype

  Future<void> disconnectUser()
  

• Example

  await ZIMKit().disconnectUser();
  

currentUser

• Description Gets the current user's information.

• Prototype

  ZIMUserFullInfo? currentUser()
  

• Example

  final user = ZIMKit().currentUser();
  

queryUser

• Description Queries user information by user ID.

• Prototype

  Future<ZIMUserFullInfo> queryUser(String id)
  

• Example

  final userInfo = await ZIMKit().queryUser('user123');
  

updateUserInfo

• Description Updates the current user's information.

• Prototype

  Future<int> updateUserInfo({
    String name = '',
    String avatarUrl = '',
  })
  

• Example

  await ZIMKit().updateUserInfo(
    name: 'New Name',
    avatarUrl: 'https://example.com/new_avatar.png',
  );
  

getConnectionStateChangedEventStream

• Description Gets a stream for connection state changed events.

• Prototype

  Stream<ZegoSignalingPluginConnectionStateChangedEvent> getConnectionStateChangedEventStream()
  

• Example

  ZIMKit().getConnectionStateChangedEventStream().listen((event) {
    print('Connection state: ${event.state}');
  });
  

---

Helper APIs

registerAppLifecycleStateChangedListener

• Description Registers a message handler for app lifecycle state changes.

• Prototype

  void registerAppLifecycleStateChangedListener(
    ZegoPluginAdapterMessageHandler listener,
  )
  

• Example

  ZIMKit().registerAppLifecycleStateChangedListener((message) {
    print('Received message: $message');
  });
  

unregisterAppLifecycleStateChangedListener

• Description Unregisters a previously registered message handler.

• Prototype

  void unregisterAppLifecycleStateChangedListener(
    ZegoPluginAdapterMessageHandler listener,
  )
  

• Example

  ZIMKit().unregisterAppLifecycleStateChangedListener(listener);
  

isAppLocked

• Description Checks if the app is currently in a locked state.

• Prototype

  Future<bool> isAppLocked()
  

• Example

  final isLocked = await ZIMKit().isAppLocked();
  

setForwardMessages

• Description Sets the messages to be forwarded and the forward type.

• Prototype

  void setForwardMessages(
    List<ZIMKitMessage> messages,
    ZIMKitForwardType forwardType,
  )
  

• Example

  ZIMKit().setForwardMessages(messages, ZIMKitForwardType.merge);
  

getForwardMessages

• Description Gets the messages currently set for forwarding.

• Prototype

  List<ZIMKitMessage> getForwardMessages()
  

• Example

  final messages = ZIMKit().getForwardMessages();
  

getForwardType

• Description Gets the current forward type.

• Prototype

  ZIMKitForwardType? getForwardType()
  

• Example

  final type = ZIMKit().getForwardType();
  

clearForwardMessages

• Description Clears the forward messages and resets the forward type.

• Prototype

  void clearForwardMessages()
  

• Example

  ZIMKit().clearForwardMessages();