IM UIKit 的会话模块（nim_chatkit_ui）的ChatUIConfig提供会话界面 UI 的自定义配置项，助您快速实现该界面的 UI 个性化定制。

请确保在会话界面加载之前完成该界面的 UI 自定义。

功能介绍

可自定义元素

会话界面可自定义的 UI 元素包括但不限于下图中的标注项。

自定义配置项

ChatUIConfig配置项具体说明如下：

属性	类型	说明
receiveMessageBg	BoxDecoration	他人发送消息内容的背景装饰器
selfMessageBg	BoxDecoration	自己发送消息内容的背景装饰器
userNickColor	Color	不设置头像的用户所展示的文字头像中的文字颜色
userNickTextSize	double	不设置头像的用户所展示的文字头像中的文字字体大小
messageTextColor	Color	文本消息字体颜色
messageTextSize	double	文本消息字体大小
avatarCornerRadius	double	头像的圆角，0 代表方形，16 为圆形。
timeTextSize	double	消息列表中，时间字体大小
timeTextColor	Color	消息列表中，时间字体颜色
signalBgColor	Color	被标记消息的背景色
showP2pMessageStatus	bool	单聊中是否展示已读未读状态
showTeamMessageStatus	bool	群聊中是否展示已读未读状态
enableMessageLongPress	bool	长按弹框功能开关
popMenuConfig	PopMenuConfig	长按弹框配置，详见下文的PopMenuConfig 弹框配置项说明
keepDefaultMoreAction	bool	保留默认的更多面板按钮
moreActions	List<ActionItem>	更多面板自定义按钮，详见下文的ActionItem 更多按钮配置项说明
keepDefaultInputAction	bool	保留默认的输入框功能按钮，默认为 true
inputActions	List<ActionItem>	自定义输入框功能按钮，详见下文的ActionItem 更多按钮配置项说明
messageBuilder	ChatKitMessageBuilder	自定义消息构建，详见下文的 ChatKitMessageBuilder 自定义消息构建配置项说明
messageClickListener	MessageClickListener	消息点击事件，详见会话消息事件监听
getPushPayload	Map<String, dynamic> Function(NIMMessage message)	设置推送payload 的回调方法，会在消息发送前调用
imagePlaceHolder	Widget Function(double aspectRatio, {double? width})?	设置图片消息显示的预占位图
maxVideoSize	int	视频消息最大size 单位M，不设置默认为200
maxFileSize	int	文件消息最大size 单位M，不设置默认为200
locationProvider	ChatKitLocationProvider	定位消息提供者，接入地理位置消息时使用
onTapAitLink	Function(String account, String text)	被@的消息点击回调

• PopMenuConfig 弹框配置项说明

属性	类型	说明
enableForward	bool	转发
enableCopy	bool	复制
enableReply	bool	回复
enablePin	bool	Pin
enableDelete	bool	删除
enableRevoke	bool	撤回

• ActionItem 更多按钮配置项说明

属性	类型	说明
type	String	按钮类型
icon	Widget	按钮图标
title	String	按钮标题
onTap	Function(BuildContext context)	按钮点击事件
permissions	List<Permission>	按钮点击需要请求的权限
deniedTip	String	权限拒绝后的提示

• ChatKitMessageBuilder 自定义消息构建配置项说明

属性	类型	说明
textMessageBuilder	ChatMessageItemBuilder	文案类型消息构建
audioMessageBuilder	ChatMessageItemBuilder	音频类型消息构建
imageMessageBuilder	ChatMessageItemBuilder	图片类型消息构建
videoMessageBuilder	ChatMessageItemBuilder	视频类型消息构建
tipsMessageBuilder	ChatMessageItemBuilder	提醒类型消息构建
fileMessageBuilder	ChatMessageItemBuilder	文件类型消息构建
locationMessageBuilder	ChatMessageItemBuilder	位置类型消息构建
extendBuilder	Map<NIMMessageType, ChatMessageItemBuilder?>	自定义类型消息构建

所有类型的消息构建都会覆盖掉对应类型的默认消息组件。

关于自定义消息的详细内容，请参见实现自定义消息收发。

自定义方式

您可通过两种方式自定义会话界面的 UI 样式，即单实例全局自定义和单界面自定义。

单实例全局自定义

假设您的应用有多个会话界面，则通过ChatUIConfig的配置项进行全局自定义后，自定义配置在单个实例全局生效，所有会话界面都将按自定义的 UI 样式进行展示。

示例代码如下：

dart// 设置ChatKitClient的chatUIConfig
ChatKitClient.instance.chatUIConfig = ChatUIConfig(
  // 设置接收消息的背景
  receiveMessageBg: BoxDecoration(
    color: Colors.amberAccent,
  ),
  // 头像的圆角
  avatarCornerRadius: 5,
);

单界面自定义

通过ChatUIConfig的配置项，可对单个会话界面进行 UI 样式自定义。

该种方式优先级大于全局配置方式。换而言之，如果在单实例全局自定义后在进行单界面自定义，则后者的配置会覆盖前者的。

示例代码如下：

dartChatPage(
  sessionId: 'sessionId',
  sessionType: NIMSessionType.p2p,
  // 设置ChatPage页面的config参数
  chatUIConfig: ChatUIConfig(
    // 设置接收消息的背景
    receiveMessageBg: BoxDecoration(
      color: Colors.amberAccent,
    ),
    // 头像的圆角
    avatarCornerRadius: 5,
  ),
)

示例

设置消息Item

• 假设您需要标记消息背景色、已读未读状态等。

  • 示例代码

    dartChatUIConfig(
      // 设置标记消息背景色，见图一
      signalBgColor: Colors.yellowAccent,
      // 消息已读未读状态，见图二
      showP2pMessageStatus: true,
      showTeamMessageStatus: true,
    );
    

  • UI 效果

    图一	图二

• 假设您需要修改消息背景色，头像圆角，消息字体，时间字体等。

  • 示例代码

    dartChatUIConfig(
      // 设置接收消息的背景
      receiveMessageBg: BoxDecoration(
        color: Colors.amberAccent,
        borderRadius: const BorderRadius.only(
          topRight: Radius.circular(12),
          bottomLeft: Radius.circular(12),
          bottomRight: Radius.circular(12)),
      ),
      // 头像圆角
      avatarCornerRadius: 16,
      // 消息字体颜色和大小
      messageTextColor: Colors.green,
      messageTextSize: 20,
      // 时间字体颜色和大小
      timeTextColor: Colors.black,
      timeTextSize: 16,
    );
    

  • UI 效果

    默认样式	自定义样式

设置长按弹窗

通过对PopMenuConfig的配置，可以控制消息长按弹窗中的显示项。

假设您需要隐藏转发按钮。

• 示例代码

  dartChatUIConfig(
    popMenuConfig: PopMenuConfig(
      // 不显示转发
      enableForward: false,
    ),
  );
  

• UI 效果

  默认样式	自定义样式

设置更多面板的自定义按钮

通过配置moreActions来给更多面板添加自定义按钮，同时，如果您不需要展示原本的默认按钮，那可以将keepDefaultMoreAction设置为false。

例如，添加一个发送自定义消息的按钮，示例代码如下：

dartChatKitClient.instance.chatUIConfig = ChatUIConfig(
  keepDefaultMoreAction: true,
  moreActions: [
    // 添加一个更多面板按钮
    ActionItem(
      type: 'custom',
      icon: Icon(Icons.android_outlined),
      title: "自定义",
      onTap: (BuildContext context) async {
        var vm = context.read<ChatViewModel>();
        var msg = await MessageBuilder.createCustomMessage(
          sessionId: vm.sessionId,
          sessionType: vm.sessionType,
          content: '自定义消息');
        if (msg.isSuccess && msg.data != null) {
          Fluttertoast.showToast(msg: '发送自定义消息！');
          vm.sendMessage(msg.data!);
        }
      },
    ),
  ],
  // 自定义消息体组件构造
  messageBuilder: messageBuilder,
);

效果如下图所示：