消息与交互扩展

业务消息、订单入口和自定义资料页可以通过公开扩展接入。扩展负责展示和业务入口，通信、持久化、消息状态与服务端权限继续由原有 SDK 链路管理。

选择合适的扩展点

需求	Flutter 接入点	边界
业务消息正文	MixinImUIKitExtension.buildMessageContent	只处理自己的消息类型，其他类型返回 null
点击业务卡片	handleMessageTap	已消费返回 true；未处理返回 false
气泡和元数据样式	messageStyleResolver	保留默认正文和生命周期
引用卡片	messageQuoteBuilder	使用已有引用快照
长按菜单	messageActionsBuilder	追加或替换菜单不授予额外服务端权限
默认输入区业务按钮	composerActions	使用当前页面公开控制器执行操作
顶部、背景、输入区等	对应页面 Builder	整块替换后由宿主负责该块布局与交互

Flutter：为一种业务消息提供渲染

下面使用 x.example.order 演示订单卡片渲染。先在服务端注册业务类型并约定内容字段，再接入对应的客户端扩展。

import 'package:flutter/material.dart';
import 'package:mixinim_uikit/mixinim_uikit.dart';

class OrderExtension extends MixinImUIKitExtension {
  const OrderExtension(this.buildOrderCard);

  final Widget Function(MixinImMessage message) buildOrderCard;

  @override
  String get id => 'example.order';

  @override
  Widget? buildMessageContent(
    BuildContext context,
    MixinImMessage message,
    bool isSelf,
    MixinImThemeData theme,
  ) {
    if (message.contentType != 'x.example.order') return null;
    return buildOrderCard(message);
  }
}

buildOrderCard 由宿主实现，负责校验业务字段并渲染卡片。注册到当前页面配置：

final config = MixinImUIKitConfig(
  extensions: [OrderExtension(buildOrderCard)],
);

将此配置传给 MixinImChatPage.sdk(...)。继承扩展基类后，未覆盖的动作与点击使用默认空实现；不要额外复制消息库或创建长连接。

点击与优先级

多个扩展按声明顺序执行，第一个返回非空内容或已处理点击的扩展生效；全部不处理时回落到标准行为。业务卡片打开订单详情应经过当前账号的业务权限校验，不只信任消息中的跳转地址或标识。

页面还提供整块消息替换和专用点击回调。混合使用时先确定哪一层拥有该消息展示，避免同一次点击被两套导航处理。优先做局部扩展，完全替换时再接管对应生命周期。

消息合同与降级

业务消息应约定稳定类型、版本与可校验字段。旧客户端不认识某个类型时保留合理的未知消息提示；不要把业务对象、界面组件或原始登录凭据写入消息内容。

业务字段的解析失败属于卡片降级，不能因此改变 SDK 的消息 ID、序号或发送状态。发送、引用、转发和历史恢复使用同一份约定，并遵守当前服务端的类型及权限校验。

平台与账号生命周期

Android/iOS 原生提供主题、内容、菜单和页面回调。各平台按对应 API 选择扩展层级，原生内容 Builder 用于定制标准消息行中的正文。

切号、退出或页面销毁时，扩展取消自己发起的请求、播放器和导航回调。缓存只保留当前账号可访问的数据；异步结果回来时再次检查页面与账号，不能写回新的登录上下文。

相关文档：消息类型 · 消息操作 · 主题定制 · 账号生命周期