IM 即时通讯
Android
产品介绍
简介
产品优势
主要功能
功能介绍
帐号集成与登录
群组功能
聊天室功能
聊天室标签功能
圈组功能
多端登录与互踢策略
质量数据监控台
海外数据中心
IM平滑迁移方案
接口及业务限制
更新日志
IM UIKit 更新日志
NIM SDK 开发版更新日志
NIM SDK 稳定版更新日志
体验 Demo
下载 SDK 与 Demo 源码
快速开始
跑通 IM Demo 源码
实现单聊消息收发(不含 UI)
跑通圈组 Demo 源码
实现圈组消息收发(不含 UI)
含 UI 集成
什么是 IM UIKit
IM UIKit 功能概览
快速集成 IM UIKit
组件导入
初始化
界面跳转
自定义用户信息
全局配置
会话列表相关
集成会话列表界面
会话列表事件监听
自定义会话列表界面 UI
会话列表 API 概览
会话消息相关
集成会话界面
会话界面事件监听
实现音视频通话
实现地理位置消息功能(含 UI)
实现自定义消息发送(含 UI)
自定义会话界面 UI
会话消息 API 概览
通讯录相关
集成通讯录界面
自定义通讯录界面 UI
通讯录界面事件监听
通讯录 API 概览
IM UIKit 常见问题排查
IM UIKit API 概览
不含 UI 集成
集成 SDK
初始化
登录相关
登录 IM
多端登录与互踢
登出 IM
消息相关
消息概述
消息收发
自定义消息收发
消息配置选项
NOS 存储场景
广播消息收发
消息已读回执
消息撤回
消息重发与转发
消息更新
消息过滤
语音消息处理
插入本地消息
历史消息
最近会话
服务端会话服务
用户资料
用户关系
在线状态订阅
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
Android 离线推送
实现离线推送
配置消息的推送属性
设置群消息强制推送
设置推送全局免打扰
设置多端推送策略
集成小米推送
集成华为推送
集成荣耀推送
集成 OPPO 推送
集成 vivo 推送
集成魅族推送
集成谷歌推送(FCM)
消息提醒
实现消息提醒
配置消息提醒功能
设置群消息强制提醒
设置消息提醒文案
定制通知栏显示信息
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
聊天室
圈组功能
圈组概述
登录管理
服务器相关
服务器概述
服务器管理
服务器成员管理
游客功能
服务器未读数管理
频道相关
频道概述
频道管理
频道黑白名单
实时互动频道
频道分组
频道分组黑白名单
频道未读数管理
搜索服务器和频道
身份组相关
身份组概述
身份组应用场景
服务器身份组
频道身份组
用户定制权限
频道分组身份组
自定义权限项
成员权限查询与判定
身份组相关查询
圈组订阅机制
圈组消息相关
图解圈组消息流转
圈组消息收发
圈组消息撤回
圈组消息更新
圈组消息删除
消息正在输入
会话消息回复(Thread)
圈组快捷评论
获取频道最后一条消息
查询历史消息
查询@我的消息
圈组消息缓存
圈组消息搜索
圈组系统通知相关
圈组系统通知概述
圈组系统通知收发
圈组系统通知更新
圈组离线推送
圈组内容审核
圈组相关抄送
圈组第三方回调
圈组各端接口命名差异
反垃圾
聊天扩展
其他
最佳实践
IM 登录最佳实践
IM 应用隐私合规
聊天室重要消息投递
API 参考
Android SDK API
Android SDK 状态码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
开通聊天室功能
配置应用客户端标识
常见问题
FAQ
错题集
Android 端推送问题排查
第三方推送厂商的限制说明
服务协议

自定义会话界面 UI

更新时间: 2023/03/27 15:21:16

IM UIKit 的会话模块(chatkit-ui)提供会话界面 UI 的自定义配置项,助您快速实现该界面的 UI 个性化定制。您也可以直接修改布局文件(chat_layout_fragment.xml)的源码自定义 UI。

请确保在会话界面加载之前完成该界面的 UI 自定义,具体加载的对象包括ChatP2PFragment(单聊 Fragment)的 Activity、ChatTeamFragment(群聊 Fragment)的 Activity 和您的 Application。

自定义功能概述

UI 元素自定义

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

您可通过ChatUIConfig中的个性化配置项修改会话界面 UI 元素,如消息体、输入按钮和消息长按菜单等,具体如下:

属性
类型 说明
messageItemClickListener IMessageItemClickListener 用于设置消息体中的点击事件处理
messageProperties MessageProperties 消息页面的UI个性化定制,包括常用的字体颜色、大小、是否可见、背景色等属性等,具体见下文的 MessageProperties 个性化配置项
permissionListener IPermissionListener 系统权限申请监听器,可用于修改系统权限申请的默认实现
chatFactory IChatFactory 消息页面中,消息体的ViewHolder的构建器,可用于修改默认消息体UI的创建。
chatViewCustom IChatViewCustom 消息页面中,获取页面的整个视图。可用于在页面中添加、移除或者修改布局元素。
chatInputMenu IChatInputMenu 消息页面中,输入框按钮定制。可用于修改输入框按钮以及更多中按钮的增加、修改和删除。
chatPopMenu IChatPopMenu 消息页面中,消长按消息体弹出菜单定制。用于对长按菜单的增加、删除和修改。
popMenuClickListener IChatPopMenuClickListener 消息页面中,消长按消息体弹出菜单定制。用于对长按菜单点击事件的修改,可修改默认实现和自定义菜单的点击。
  • MessageProperties 个性化配置项

    属性
    类型 说明
    selfMessageBg Drawable 自己发送的消息体的背景色,具体自定义示例见下文的修改消息体背景色
    receiveMessageBg Drawable 接收到的消息体的背景色,具体自定义示例见下文的修改消息体背景色
    receiveMessageRes int 他人发送消息内容的背景资源ID,支持drawable/color
    selfMessageRes int 自己发送消息内容的背景资源ID,支持drawable/color
    userNickColor int 不设置头像的用户所展示的文字头像中的文字颜色
    userNickTextSize int 不设置头像的用户所展示的文字头像中的文字字体大小
    messageTextColor int 文本消息字体颜色
    messageTextSize int 文本消息字体大小
    avatarCornerRadius float 头像的圆角,0 代表方形,30dp 为原型。这里需要自行将 dp 转换为 px
    timeTextSize int 消息列表中,时间字体大小
    timeTextColor int 消息列表中,时间字体颜色
    signalBgColor int 被标记消息的背景色(见下图一)
    showP2pMessageStatus boolean 单聊中是否展示已读未读状态(见下图二)
    showTeamMessageStatus boolean 群聊中是否展示已读未读状态(见下图二)
    showTitleBar boolean 会话界面是否展示标题栏,具体自定义示例见下文的隐藏界面标题栏
    showTitleBarRightIcon boolean 是否展示标题栏右侧图标按钮
    titleBarRightRes int 设置标题栏右侧图标按钮展示图标,具体自定义示例见下文的修改界面标题右侧图标
    titleBarRightClick View.OnClickListener 标题栏右侧图标的点击事件,具体配置示例见下文的修改界面标题右侧图标
    chatViewBackground Drawable 设置会话界面背景色,具体自定义示例见下文的修改会话界面背景色
    图一
    图二
    标记消息背景色示意图.png 已读未读状态.png

界面布局自定义

除了界面的 UI 元素,您也可对界面的布局进行自定义,会话界面的默认布局如下图所示。

该界面各视图的说明如下:

属性
类型 说明
ChatViewTitle BackTitleBar 会话界面(即聊天界面)的标题视图,可通过ChatViewgetTitleBar()来获取视图进行样式修改
ChatViewBodyTop FrameLayout 会话界面的消息列表上方的小块视图,可通过ChatViewgetChatBodyTopLayout()来获取视图进行样式修改。该视图可用于在消息列表和顶部界面标题中间增加新的 UI 元素
ChatViewBody FrameLayout 会话界面的消息列表视图,可通过ChatViewgetChatBodyLayout()来获取视图进行样式修改。布局中包含ChatMessageListView消息列表和通知文本视图。文本视图 ID 为tvNotification,用于断网提示
ChatViewBodyBottom FrameLayout 会话界面的消息列表下视图,可通过ChatViewgetChatBodyBottomLayout()来获取视图进行样式修改。用于在消息列表和底部输入框中间增加新的 UI 元素,具体自定义示例请参见下文的在输入框上方增加按钮
ChatViewBottom FrameLayout 会话界面的底部输入框视图,可通过ChatViewgetChatBottomLayout()来获取视图进行样式修改。布局中包含底部输入框视图MessageBottomLayout
ChatMessageListView ChatMessageListView 会话界面的消息列表,可通过ChatViewgetMessageListView()来获取视图进行样式修改
MessageBottomLayout MessageBottomLayout 会话界面的底部输入框视图,可通过ChatViewgetInputView()来获取视图进行样式修改

在会话界面,上述元素都可以通过ChatView提供的相应接口获取。ChatView的获取可参考上述的ChatUIConfig:chatViewCustom来获取整个界面视图。

自定义示例

修改界面标题栏右侧图标

会话界面标题采用的是 IM UIKit 内部封装的标题视图BackTitleBar,包含左侧返回按钮、中间标题区域、右侧按钮区域。

  • 示例代码

        ChatUIConfig chatUIConfig = new ChatUIConfig();
          chatUIConfig.messageProperties = new MessageProperties();
          //设置右侧按钮图标
          chatUIConfig.messageProperties.titleBarRightRes = R.drawable.ic_user_setting;
          //设置右侧按钮点击事件
          chatUIConfig.messageProperties.titleBarRightClick = new View.OnClickListener() {
              @Override
              public void onClick(View v) {
                  //todo 右侧按钮的点击事件
              }
          };
          ChatKitClient.setChatUIConfig(chatUIConfig);
    
  • 效果对比

    默认
    自定义后
    Screenshot_20221018_154951.png

隐藏界面标题栏

  • 示例代码

        ChatUIConfig chatUIConfig = new ChatUIConfig();
        chatUIConfig.messageProperties = new MessageProperties();
          //设置标题不可见
        chatUIConfig.messageProperties.showTitleBar = false;
        ChatKitClient.setChatUIConfig(chatUIConfig);
    
  • 效果对比

    默认
    自定义后
    不隐藏会话界面标题.png 隐藏会话界面标题.png

修改会话界面背景色

  • 示例代码
    ChatUIConfig chatUIConfig = new ChatUIConfig();
    chatUIConfig.messageProperties = new MessageProperties();
    //会话页面背景色
    chatUIConfig.messageProperties.chatViewBackground =
        new ColorDrawable(context.getResources().getColor(R.color.color_blue_3a9efb));
    ChatKitClient.setChatUIConfig(chatUIConfig);
    
  • 效果对比
    默认
    自定义后
    会话背景色默认.png 会话背景色自定义.png

修改消息体背景色

  • 示例代码

    ChatUIConfig chatUIConfig = new ChatUIConfig();
    chatUIConfig.messageProperties = new MessageProperties();
    //会话发送消息背景色
    chatUIConfig.messageProperties.selfMessageBg =new ColorDrawable(context.getResources().getColor(R.color.color_blue_3a9efb));
    //会话接受消息背景色
    chatUIConfig.messageProperties.receiveMessageBg =new ColorDrawable(context.getResources().getColor(R.color.color_666666));;
    ChatKitClient.setChatUIConfig(chatUIConfig);
    
  • 效果对比

    默认
    自定义后
    消息体背景色默认.png 消息提背景色自定义.png

不展示消息长按菜单

长按消息默认会弹出操作菜单,该菜单可设置为长按消息时不展示。

  • 默认展示该菜单

  • 示例代码

    以下为不展示消息长按菜单的示例代码:

    ChatUIConfig chatUIConfig = new ChatUIConfig();
      chatUIConfig.chatPopMenu =
            new IChatPopMenu() {
              @Override
              public boolean showDefaultPopMenu() {
                return false;
              }
            };
        ChatKitClient.setChatUIConfig(chatUIConfig);
    
    

去除消息长按菜单的【标记】按钮

  • 示例代码

    ChatUIConfig chatUIConfig = new ChatUIConfig();
    chatUIConfig.chatPopMenu = new IChatPopMenu() {
              @NonNull
              @Override
              public List<ChatPopMenuAction> customizePopMenu(
                  List<ChatPopMenuAction> menuList, ChatMessageBean messageBean) {
                  if(menuList != null){
                      for (int index = menuList.size() - 1;index >=0;index--){
                          if (TextUtils.equals(menuList.get(index).getAction(),ActionConstants.POP_ACTION_PIN)){
                              menuList.remove(index);
                              break;
                          }
                      }
                  }
                  return menuList;
              }
            };
      ChatKitClient.setChatUIConfig(chatUIConfig);
    
    
  • 效果对比

    默认
    自定义后
    操作菜单未去除标记.jpg 操作菜单去除标记.jpg

上述代码的public List<ChatPopMenuAction> customizePopMenu(List<ChatPopMenuAction> menuList, ChatMessageBean messageBean)方法中,menuList参数会把当前 IM UIKit 的默认实现的能力传递过来。如果不需要默认实现的能力,在该方法中将menuList清空即可。同时也可对menuList进行操作来调整菜单顺序。messageBean代表当前长按消息的消息实体类。IM UIKit 默认实现的能力如下表示所示:

标识Action
说明
ActionConstants.POP_ACTION_REPLY 回复消息
ActionConstants.POP_ACTION_COPY 复制消息
ActionConstants.POP_ACTION_RECALL 撤回消息
ActionConstants.POP_ACTION_PIN 标记消息
ActionConstants.POP_ACTION_MULTI_SELECT 多选消息
ActionConstants.POP_ACTION_DELETE 删除消息
ActionConstants.POP_ACTION_TRANSMIT 转发消息

在界面底部菜单栏增加按钮

  • 示例打码

        ChatUIConfig chatUIConfig = new ChatUIConfig();
        chatUIConfig.chatInputMenu =
            new IChatInputMenu() {
              @Override
              public List<ActionItem> customizeInputBar(List<ActionItem> actionItemList) {
                //向输入区域的菜单中增加一个按钮,其中ActionItem,第一个参数action为该菜单项的唯一KEY,在下面点击事件中进行区分。第二个参数为图片资源
                actionItemList.add(new ActionItem("custom_action",R.drawable.ic_user_setting));
                return actionItemList;
              }
              //新增加的菜单的点击事件,action为添加时候填写的唯一值
              @Override
              public boolean onCustomInputClick(Context context, View view, String action) {
                ToastX.showShortToast(action);
                return true;
              }
            };
        ChatKitClient.setChatUIConfig(chatUIConfig);
    
    
  • 效果对比

    默认
    自定义后
    默认底部输入区域.png 底部输入区域增加按钮.png

在【更多】区域增加按钮

您可根据业务需求在聊天输入区域的更多按钮.png下增加自定义按钮。

示例代码

    ChatUIConfig chatUIConfig = new ChatUIConfig();
    chatUIConfig.chatInputMenu =
        new IChatInputMenu() {
          @Override
          public List<ActionItem> customizeInputMore(List<ActionItem> actionItemList) {
            //向输入区域的菜单中增加一个按钮,其中ActionItem,第一个参数action为该菜单项的唯一KEY,在下面点击事件中进行区分。第二个参数为图片资源,第三个参数为展示文案
            actionItemList.add(new ActionItem("custom_more_1",R.drawable.ic_user_setting,R.string.chat));
            return actionItemList;
          }
          //新增加的菜单的点击事件,action为添加时候填写的唯一值
          @Override
          public boolean onCustomInputClick(Context context, View view, String action) {
            ToastX.showShortToast(action);
            return true;
          }
        };
    ChatKitClient.setChatUIConfig(chatUIConfig);

更多区域中,IM UIKit 默认实现的按钮只有拍摄按钮,其对应的 Action 为ActionConstants.ACTION_TYPE_CAMERA

示例代码解读

上述代码的public boolean customizeInputBar(List<ActionItem> actionItemList)方法中,actionItemList参数会把当前 IM UIKit 的默认实现的能力传递过来。如果不需要默认实现的能力,在该方法中将actionItemList清空即可。同时也可对actionItemList进行操作来调整菜单顺序。IM UIKit 默认实现的能力如下表示所示:

标识Action
说明
ActionConstants.ACTION_TYPE_RECORD 录音功能
ActionConstants.ACTION_TYPE_EMOJI 表情功能
ActionConstants.ACTION_TYPE_ALBUM 发送图片
ActionConstants.ACTION_TYPE_MORE 展开更多菜单
ActionConstants.ACTION_TYPE_CAMERA 弹出拍照和录像弹窗
ActionConstants.ACTION_TYPE_TAKE_PHOTO 拍照
ActionConstants.ACTION_TYPE_TAKE_VIDEO 录像
ActionConstants.ACTION_TYPE_LOCATION 地理位置

效果对比

默认
自定义后
底部输入区域更多默认样式.png 底部输入区域更多自定义.png

在【更多】区域移除按钮

您可根据业务需求在聊天输入区域的更多按钮.png下删除 IM UIKit 的内置按钮。以下以“移除发送地理位置消息的按钮”为例进行说明。

示例代码

ChatUIConfig chatUIConfig = new ChatUIConfig();
chatUIConfig.chatInputMenu =
            new IChatInputMenu() {
              @Override
              public List<ActionItem> customizeInputBar(List<ActionItem> actionItemList) {
                //个性化配置输入框下方按钮,actionItemList传递默认配置的四个按钮:语音、表情、图片和更多。
                //您可以根据自己的需求修改actionItemList的数量和顺序,ChatKit-UI会按照您的返回结果展示。
                return actionItemList;
              }

              @Override
              public List<ActionItem> customizeInputMore(List<ActionItem> actionItemList) {
              //个性化配置更多面板中按钮,actionItemList传递默认配置的四个按钮:拍摄、文件、位置和音视频通话。
                  for (int index = 0;index < actionItemList.size();index++){
                  //根据Action判断按钮是否删除
                      if (TextUtils.equals(actionItemList.get(index).getAction(),
                              ActionConstants.ACTION_TYPE_LOCATION)){
                          actionItemList.remove(index);
                          break;
                      }
                  }
                  return actionItemList;
              }

              @Override
              public boolean onCustomInputClick(Context context, View view, String action) {
                return false;
              }
            };

效果对比

默认
移除后
地理位置按钮默认.png 去除地图功能后的界面resized.png

在输入框上方增加按钮

示例代码

ChatUIConfig chatUIConfig = new ChatUIConfig();
chatUIConfig.chatViewCustom =
        layout -> { 
          // 从ChatView中获取底部消息类型布局自定义
          FrameLayout frameLayout = layout.getChatBodyBottomLayout();
          //效果截图中红色框中的布局视图View
          IMBottomView imBottomView = new IMBottomView(context);
          FrameLayout.LayoutParams layoutParams =
              new FrameLayout.LayoutParams(
                  ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT);
          layoutParams.leftMargin = context.getResources().getDimensionPixelSize(R.dimen.dp_16);
          //把自定义View添加到聊天页面中
          frameLayout.addView(imBottomView, layoutParams);
        };
ChatKitClient.setChatUIConfig(chatUIConfig);

示例代码解读

示例代码中chatUIConfig.chatViewCustom的接口源码如下:

public interface IChatViewCustom {
  void customizeChatLayout(final ChatView layout);
}

ChatView作为会话界面的整体 View 提供了获取该界面中所有 View 的获取方法,具体如下:

方法
返回值 说明
getTitleBar BackTitleBar 获取聊天页面头部TitleBar视图
getChatBodyTopLayout FrameLayout 获取消息列表和头部TitleBar中间的视图布局,默认里面为空
getChatBodyLayout FrameLayout 获取消息列表区块布局,其中该布局内部包含ChatMessageListView消息列表视图
getChatBodyBottomLayout FrameLayout 获取消息列表和底部输入框中间的视图布局,默认为空。可用于上述示例中的场景。
getChatBottomLayout FrameLayout 获取底部视图布局,其中包含输入框视图MessageBottomLayout
getChatViewLayoutBinding ChatViewLayoutBinding 获取整个聊天页面的布局viewBinding
getInputView MessageBottomLayout 获取底部输入框区域的视图
setMessageBackground void 设置聊天列表的背景

效果对比

默认
自定义后
会话界面布局原图_resized.png 输入框上方增加按钮.png

源码导读

界面布局

ChatKit-ui模块的chat_layout_fragment.xml文件包含了整个会话列表的布局配置。通过修改该文件的源码可实现界面元素调整和界面背景修改等自定义操作。该文件的源码概略如下:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">

    //消息界面的UI都封装在ChatView中
    <com.netease.yunxin.kit.chatkit.ui.view.ChatView
        android:id="@+id/chatView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

会话

ChatView为会话 UI 的实现类,ChatView是对RecyclerView的封装,同时提供数据更新接口,具体如下:

方法
入参类型
说明
setItemClickListener IMessageItemClickListener 设置消息的点击事件
setMessageProperties MessageProperties 设置列表点击事件,分为点击和长按
clearMessageList 清理消息列表
addMessageListForward List 在列表头部添加消息
appendMessageList List 在消息列表添加数据
updateMessage ChatMessageBean 更新消息数据,消息发送状态、已读状态更新使用
setMessageProxy IMessageProxy 设置消息行为的实现,包括发送文本消息、图片消息等
setMessageViewHolderFactory IChatFactory 消息构造工程类,具体实现可参考ChatDefaultFactory
getInputView 获取消息界面底部输入视图,可以自行设置底部视图

会话 UI

在会话中存在多种类型的ViewHolder,分别代表不同的消息类型。

ViewHolder
消息类型
说明
ChatTextMessageViewHolder 文本消息 布局文件为chat_message_text_view_holder.xml(多个类型公用),可以在该文件中调整其布局结构
ChatAudioMessageViewHolder 语音消息 布局文件为chat_message_audio_view_holder.xml,可以在该文件中调整其布局结构
ChatImageMessageViewHolder 图片消息 继承ChatThumbBaseViewHolder,其布局文件为chat_message_thumbnail_view_holder.xml,可以在该文件中调整其布局结构
ChatVideoMessageViewHolder 视频消息 继承ChatThumbBaseViewHolder,其布局文件为chat_message_thumbnail_view_holder.xml,可以在该文件中调整其布局结构
ChatNotificationMessageViewHolder 系统通知 布局文件为chat_message_text_view_holder.xml,可以在该文件中调整其布局结构
ChatTipsMessageViewHolder 提示消息 布局文件为chat_message_text_view_holder.xml(多个类型公用)`,可以在该文件中调整其布局结构

其他

  • 会话中消息发送逻辑,在ChatBaseFragment中的IMessageProxy.messageProxy实现。

  • 会话中消息的点击事件,在ChatBaseFragment中的IMessageItemClickListener.itemClickListener实现。

  • 长按消息弹出菜单的事件处理,在ChatBaseFragmentChatPopMenuActionListener.actionListener实现。

  • 消息界面中消息的构造工程,在ChatDefaultFactory实现。

此文档是否对你有帮助?
有帮助
我要吐槽
  • 自定义功能概述
  • UI 元素自定义
  • 界面布局自定义
  • 自定义示例
  • 修改界面标题栏右侧图标
  • 隐藏界面标题栏
  • 修改会话界面背景色
  • 修改消息体背景色
  • 不展示消息长按菜单
  • 去除消息长按菜单的【标记】按钮
  • 在界面底部菜单栏增加按钮
  • 在【更多】区域增加按钮
  • 示例代码
  • 示例代码解读
  • 效果对比
  • 在【更多】区域移除按钮
  • 示例代码
  • 效果对比
  • 在输入框上方增加按钮
  • 示例代码
  • 示例代码解读
  • 效果对比
  • 源码导读
  • 界面布局
  • 会话
  • 会话 UI
  • 其他