Events topic

Events

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

This document describes the event callback classes in ZIMKit. These classes are used to listen to various events occurring in ZIMKit.

ZIMKitEvents

ZIMKit Event Callback Class. Used to listen to various events occurring in ZIMKit.

Name Description Type Default Value
message Message-related events ZIMKitMessageEvents ZIMKitMessageEvents()
conversation Conversation-related events ZIMKitConversationEvents ZIMKitConversationEvents()
user User-related events ZIMKitUserEvents ZIMKitUserEvents()
group Group-related events ZIMKitGroupEvents ZIMKitGroupEvents()
connection Connection-related events ZIMKitConnectionEvents ZIMKitConnectionEvents()
onError Error event callback void Function(ZIMKitErrorEvent event)? null

Example:

ZIMKitEvents(
  message: ZIMKitMessageEvents(
    onMessageReceived: (event) {
      print('Received message: ${event.message}');
    },
    onMessageSent: (event) {
      print('Sent message: ${event.message}');
    },
  ),
  conversation: ZIMKitConversationEvents(
    onConversationChanged: (event) {
      print('Conversation changed: ${event.conversation}');
    },
  ),
)

ZIMKitMessageEvents

Message-related events.

onMessageReceived

  • Description Triggered when a message is received.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageReceived;

  • Example

    ZIMKitMessageEvents(
  onMessageReceived: (event) {
    print('Message received from ${event.message.info.senderUserID}');
  },
)

onMessageSent

  • Description Triggered when a message is sent successfully.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageSent;

  • Example

    ZIMKitMessageEvents(
  onMessageSent: (event) {
    print('Message sent to ${event.message.info.conversationID}');
  },
)

onMessageSendFailed

  • Description Triggered when a message fails to send.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageSendFailed;

  • Example

    ZIMKitMessageEvents(
  onMessageSendFailed: (event) {
    print('Message failed to send');
  },
)

onMessageDeleted

  • Description Triggered when a message is deleted.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageDeleted;

  • Example

    ZIMKitMessageEvents(
  onMessageDeleted: (event) {
    print('Message deleted');
  },
)

onMessageRevoked

  • Description Triggered when a message is revoked.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageRevoked;

  • Example

    ZIMKitMessageEvents(
  onMessageRevoked: (event) {
    print('Message revoked');
  },
)

onMessageReplied

  • Description Triggered when a message is replied to.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageReplied;

  • Example

    ZIMKitMessageEvents(
  onMessageReplied: (event) {
    print('Message replied');
  },
)

onMessageForwarded

  • Description Triggered when a message is forwarded.

  • Prototype

    final void Function(ZIMKitMessageEvent event)? onMessageForwarded;

  • Example

    ZIMKitMessageEvents(
  onMessageForwarded: (event) {
    print('Message forwarded');
  },
)

onMessageReactionAdded

  • Description Triggered when a reaction is added to a message.

  • Prototype

    final void Function(ZIMKitMessageReactionEvent event)? onMessageReactionAdded;

  • Example

    ZIMKitMessageEvents(
  onMessageReactionAdded: (event) {
    print('${event.user.name} added ${event.reaction}');
  },
)

onMessageReactionDeleted

  • Description Triggered when a reaction is removed from a message.

  • Prototype

    final void Function(ZIMKitMessageReactionEvent event)? onMessageReactionDeleted;

  • Example

    ZIMKitMessageEvents(
  onMessageReactionDeleted: (event) {
    print('${event.user.name} removed ${event.reaction}');
  },
)

onMediaTransferProgress

  • Description Triggered for each media upload or download progress update, including image messages loaded through the SDK image cache. isUploading distinguishes the direction; sizes are in bytes. Image downloads can report totalSize as 0 when the server does not provide the content length.

  • Prototype

    final void Function(ZIMKitMediaTransferProgressEvent event)? onMediaTransferProgress;

  • Example

    ZIMKitMessageEvents(
  onMediaTransferProgress: (event) {
    print('${event.isUploading ? 'Upload' : 'Download'}: '
        '${(event.progress * 100).toStringAsFixed(0)}%');
  },
)

ZIMKitConversationEvents

Conversation-related events.

onConversationChanged

  • Description Triggered when conversation information changes.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationChanged;

  • Example

    ZIMKitConversationEvents(
  onConversationChanged: (event) {
    print('Conversation changed: ${event.conversation.id}');
  },
)

onConversationAdded

  • Description Triggered when a new conversation is added.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationAdded;

  • Example

    ZIMKitConversationEvents(
  onConversationAdded: (event) {
    print('New conversation: ${event.conversation.id}');
  },
)

onConversationDeleted

  • Description Triggered when a conversation is deleted.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationDeleted;

  • Example

    ZIMKitConversationEvents(
  onConversationDeleted: (event) {
    print('Conversation deleted');
  },
)

onConversationPinned

  • Description Triggered when a conversation is pinned.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationPinned;

  • Example

    ZIMKitConversationEvents(
  onConversationPinned: (event) {
    print('Conversation pinned');
  },
)

onConversationUnpinned

  • Description Triggered when a conversation is unpinned.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationUnpinned;

  • Example

    ZIMKitConversationEvents(
  onConversationUnpinned: (event) {
    print('Conversation unpinned');
  },
)

onConversationMuted

  • Description Triggered when a conversation is muted.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationMuted;

  • Example

    ZIMKitConversationEvents(
  onConversationMuted: (event) {
    print('Conversation muted');
  },
)

onConversationUnmuted

  • Description Triggered when a conversation is unmuted.

  • Prototype

    final void Function(ZIMKitConversationEvent event)? onConversationUnmuted;

  • Example

    ZIMKitConversationEvents(
  onConversationUnmuted: (event) {
    print('Conversation unmuted');
  },
)

onTotalUnreadCountChanged

  • Description Triggered when the total unread count changes.

  • Prototype

    final void Function(int totalUnreadCount)? onTotalUnreadCountChanged;

  • Example

    ZIMKitConversationEvents(
  onTotalUnreadCountChanged: (count) {
    print('Total unread: $count');
  },
)

ZIMKitUserEvents

User-related events.

onUserInfoUpdated

  • Description Triggered when user information is updated.

  • Prototype

    final void Function(ZIMKitUserEvent event)? onUserInfoUpdated;

  • Example

    ZIMKitUserEvents(
  onUserInfoUpdated: (event) {
    print('User info updated: ${event.user.name}');
  },
)

onUserAvatarUpdated

  • Description Triggered when user avatar is updated.

  • Prototype

    final void Function(ZIMKitUserEvent event)? onUserAvatarUpdated;

  • Example

    ZIMKitUserEvents(
  onUserAvatarUpdated: (event) {
    print('User avatar updated');
  },
)

ZIMKitGroupEvents

Group-related events.

onGroupCreated

  • Description Triggered when a group is created.

  • Prototype

    final void Function(ZIMKitGroupEvent event)? onGroupCreated;

  • Example

    ZIMKitGroupEvents(
  onGroupCreated: (event) {
    print('Group created');
  },
)

onGroupDismissed

  • Description Triggered when a group is dismissed.

  • Prototype

    final void Function(ZIMKitGroupEvent event)? onGroupDismissed;

  • Example

    ZIMKitGroupEvents(
  onGroupDismissed: (event) {
    print('Group dismissed');
  },
)

onGroupJoined

  • Description Triggered when the current user joins a group.

  • Prototype

    final void Function(ZIMKitGroupEvent event)? onGroupJoined;

  • Example

    ZIMKitGroupEvents(
  onGroupJoined: (event) {
    print('Joined group');
  },
)

onGroupLeft

  • Description Triggered when the current user leaves a group.

  • Prototype

    final void Function(ZIMKitGroupEvent event)? onGroupLeft;

  • Example

    ZIMKitGroupEvents(
  onGroupLeft: (event) {
    print('Left group');
  },
)

onGroupInfoUpdated

  • Description Triggered when group information is updated.

  • Prototype

    final void Function(ZIMKitGroupEvent event)? onGroupInfoUpdated;

  • Example

    ZIMKitGroupEvents(
  onGroupInfoUpdated: (event) {
    print('Group info updated');
  },
)

onGroupMemberJoined

  • Description Triggered when a member joins a group.

  • Prototype

    final void Function(ZIMKitGroupEvent event, List<ZIMKitUser> members)? onGroupMemberJoined;

  • Example

    ZIMKitGroupEvents(
  onGroupMemberJoined: (event, members) {
    for (final user in members) {
      print('${user.name} joined the group');
    }
  },
)

onGroupMemberLeft

  • Description Triggered when a member leaves a group.

  • Prototype

    final void Function(ZIMKitGroupEvent event, List<ZIMKitUser> members)? onGroupMemberLeft;

  • Example

    ZIMKitGroupEvents(
  onGroupMemberLeft: (event, members) {
    for (final user in members) {
      print('${user.name} left the group');
    }
  },
)

onGroupMemberInfoUpdated

  • Description Triggered when a group member's information is updated.

  • Prototype

    final void Function(ZIMKitGroupEvent event, ZIMKitUser member)? onGroupMemberInfoUpdated;

  • Example

    ZIMKitGroupEvents(
  onGroupMemberInfoUpdated: (event, member) {
    print('Member info updated: ${member.name}');
  },
)

ZIMKitConnectionEvents

Connection-related events.

onConnectionStateChanged

  • Description Triggered when the connection state changes.

  • Prototype

    final void Function(ZIMKitConnectionStateEvent event)? onConnectionStateChanged;

  • Example

    ZIMKitConnectionEvents(
  onConnectionStateChanged: (event) {
    print('Connection state: ${event.state}');
  },
)

onTokenWillExpire

  • Description Triggered when the token will expire (notified 30 seconds in advance).

  • Prototype

    final void Function(ZIMKitTokenExpiredEvent event)? onTokenWillExpire;

  • Example

    ZIMKitConnectionEvents(
  onTokenWillExpire: (event) {
    print('Token will expire in ${event.remainSeconds} seconds');
  },
)

onTokenExpired

  • Description Triggered when the login token expires. Fetch a new token from your server and call ZIMKit().renewToken(token).

  • Prototype

    final void Function()? onTokenExpired;

  • Example

    ZIMKitConnectionEvents(
  onTokenExpired: () {
    print('Token expired, please re-login');
  },
)

ZIMKitErrorEvent

Error event class. Contains error information when an error occurs.

Properties

Name Description Type
code Error code int
message Error message String
stream Error stream type String

Example:

ZIMKitEvents(
  onError: (event) {
    print('Error occurred: ${event.code} - ${event.message}');
  },
)

Audio Recording Events

onAudioRecordStarted

  • Description Triggered when audio recording starts.

  • Prototype

    final void Function()? onAudioRecordStarted;

onAudioRecordCompleted

  • Description Triggered when audio recording completes.

  • Prototype

    final void Function(ZIMAudioRecordData recordData)? onAudioRecordCompleted;

onAudioRecordCancelled

  • Description Triggered when audio recording is cancelled.

  • Prototype

    final void Function()? onAudioRecordCancelled;

onAudioRecordFailed

  • Description Triggered when audio recording fails.

  • Prototype

    final void Function(int errorCode)? onAudioRecordFailed;

onAudioPlayCompleted

  • Description Triggered when audio playback completes.

  • Prototype

    final void Function(int messageID)? onAudioPlayCompleted;

onAudioPlayFailed

  • Description Triggered when audio playback fails.

  • Prototype

    final void Function(int messageID, int errorCode)? onAudioPlayFailed;

onAudioPlayProgress

  • Description Triggered during audio playback progress.

  • Prototype

    final void Function(int messageID, int progress)? onAudioPlayProgress;

Classes

ZIMKit Get started APIs Configs Events
ZIMKit - Zego Instant Messaging Kit