IM UIKit 通讯录模块（contactkit-ui）提供通讯录界面的 UI 自定义配置项目，助您快速实现该界面的 UI 个性化定制。您也可以直接修改该界面的布局文件自定义 UI 风格。

请确保在加载通讯录界面之前完成该界面的 UI 自定义，加载的对象包括ContactFragment的 Activity 和您的 Application。

自定义功能概述

UI 元素自定义

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

您可通过ContactKit-ui的ContactUIConfig属性所提供的个性化配置项修改该界面 UI 元素的样式，具体如下：

属性	类型	说明
showTitleBar	boolean	是否展示标题栏，具体自定义示例请参见下文的隐藏界面标题栏
showTitleBarRightIcon	boolean	是否展示标题栏的最右侧图标
showTitleBarRight2Icon	boolean	是否展示标题栏的次最右侧图标，具体自定义示例请参见下文的修改界面标题栏字体颜色和图标
titleBarRightRes	int	标题栏的最右侧图标的 ID
titleBarRight2Res	int	标题栏的次最右侧图标的 ID
title	String	标题栏文案
titleColor	int	标题栏字体颜色，具体自定义示例请参见下文的修改界面标题栏字体颜色和图标
showHeader	int	是否在通讯录界面显示头部模块，具体自定义示例请参见下文的隐藏头部模块
headerData	List<ContactEntranceBean>	头部模块的数据，如果不为空，则覆盖已有数据
contactAttrs	ContactListViewAttrs	通讯录好友列表中 UI 属性设置，包括好友昵称的字体、好友头像、索引字体、颜色等，具体自定义示例请参见下文的修改通讯录列表字体颜色
itemClickListeners	SparseArray<IContactClickListener>	好友列表的点击事件，由于列表中包含多种类型数据，所以采用 SparseArray，KEY 值即为类型，当前通讯录中包含的类型为IViewTypeConstant.CONTACT_ACTION_ENTER(值为1)和IViewTypeConstant.CONTACT_FRIEND(值为1)类型，具体配置示例请参见下文的修改头部模块
viewHolderFactory	IContactFactory	通讯录好友列表 ViewHolder 构造器，用于列表中ViewHolder的创建和绑定，可参考默认实现的ContactDefaultFactory
customLayout	IContactViewLayout	通讯录好友列表界面个性化配置，在该接口中会返回

界面布局自定义

除了界面的 UI 元素，您也可对界面的布局进行自定义，通讯录界面的默认布局如下图所示。

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

属性	类型	说明
TitleBar	BackTitleBar	通讯录列表界面标题视图，可通过ContactLayout的getTitleBar()来获取视图进行样式修改
BodyTopLayout	FrameLayout	好友列表上方的小块视图，可通过ContactLayout的getBodyTopLayout()来获取视图进行样式修改。该视图用于在通讯录列表和顶部界面标题中间增加新的 UI 元素。具体自定义示例请参见下文的在头部模块增加提示消息
BodyLayout	FrameLayout	通讯录界面的主题视图，可通过ContactLayout的getBodyLayout()来获取视图进行样式修改。该视图布局中包含ContactListView通讯录好友列表视图
BottomLayout	FrameLayout	通讯录好友列表下方的小块视图，可通过ContactLayout的getBottomLayout()来获取视图进行样式修改。该视图用于在通讯录列表底部增加新的 UI 元素
ContactListView	ContactListView	通讯录好友列表视图，可通过ContactLayout的getContactListView()来获取视图进行样式修改

在会话界面（即聊天界面），上述界面元素都可以通过ContactLayout提供的相应接口获取。ContactLayout的获取可参考上述的ContactUIConfig:customLayout来获取整个界面视图。示例代码可参考在头部模块增加提示消息。

自定义示例

隐藏界面标题栏

• 示例代码如下：

  //1、创建个性化定制对象
  ContactUIConfig contactUIConfig = new ContactUIConfig();
  //2、设置TitleBar不可见
  contactUIConfig.showTitleBar = false;
  //3、将自定义事件设置到ContactKitClient即可
  ContactKitClient.setContactUIConfig(contactUIConfig);
  

  除此之外，还可以隐藏标题栏中的最右侧图标题和次最右侧按钮。详见上文的个性化配置项列表。

• 效果对比

  默认	自定义后

修改界面标题栏字体颜色和图标

• 示例代码

  //1、创建个性化定制对象
  ContactUIConfig contactUIConfig = new ContactUIConfig();
  //2、设置TitleBar标题字体颜色和右侧按钮图标
  contactUIConfig.titleColor = Color.parseColor("#337EFF");
  contactUIConfig.titleBarRight2Res = R.drawable.ic_about;
  //3、设置右侧第二个按钮点击事件
  contactUIConfig.titleBarRight2Click = new View.OnClickListener() {
      @Override
      public void onClick(View v) {
            
      }
  };
  //4、将自定义事件设置到ContactKitClient即可
  ContactKitClient.setContactUIConfig(contactUIConfig);
  

  除此之外，还可以设置标题栏的右侧第一个按钮图标和点击事件。详见上文的个性化配置项列表。

• 效果对比

  默认	自定义后

隐藏头部模块

• 示例代码

  //1、创建个性化定制对象
  ContactUIConfig contactUIConfig = new ContactUIConfig();
  //2、设置列表头部不可见
  contactUIConfig.showHeader = false;
  //3、将自定义事件设置到ContactKitClient即可
  ContactKitClient.setContactUIConfig(contactUIConfig);
  

• 效果对比

  默认	自定义后

修改头部模块

在好友列表头部模块添加您自定义的入口和点击事件，即可自定义其展示内容。

• 示例代码

  //1、创建个性化定制对象
  ContactUIConfig contactUIConfig = new ContactUIConfig();
  //2、设置列表头部数据和点击事件
  List<ContactEntranceBean> header = new ArrayList<>();
  ContactEntranceBean firstHeader = new ContactEntranceBean(R.drawable.ic_about,"第一个头部站位");
  header.add(firstHeader);
  contactUIConfig.headerData = header;
  contactUIConfig.itemClickListeners.append(IViewTypeConstant.CONTACT_ACTION_ENTER, new IContactClickListener() {
        @Override
        public void onClick(int position, BaseContactBean data) {
            Toast.makeText(context,"第一个头部站位点击",Toast.LENGTH_LONG).show();
        }
  });
  //3、将自定义事件设置到ContactKitClient即可
  ContactKitClient.setContactUIConfig(contactUIConfig);
  

• 效果对比

  默认	自定义后

修改通讯录列表字体颜色

• 示例代码

  //1、创建个性化定制对象
  ContactUIConfig contactUIConfig = new ContactUIConfig();
  //2、设置列表中字体颜色
  contactUIConfig.contactAttrs = new ContactListViewAttrs();
  contactUIConfig.contactAttrs.setNameTextColor( Color.parseColor("#337EFF"));
  //3、将自定义事件设置到ContactKitClient即可
  ContactKitClient.setContactUIConfig(contactUIConfig);
  
  

  除此之外，还可以修改字体大小，索引的字体颜色和字体大小，头像圆角大小，分割小颜色，是否展示索引等，详见上文的个性化配置项列表。

• 效果对比

  默认	自定义后

在头部模块增加提示消息

• 示例代码

  //1、创建个性化定制对象
  ContactUIConfig contactUIConfig = new ContactUIConfig();
  //2、在列表界面头部增加自己的View
  contactUIConfig.customLayout =
  new IContactViewLayout() {
      @Override
      public void customizeContactLayout(ContactLayout layout) {
          FrameLayout topLayout = layout.getBodyTopLayout();
          TextView contentTv = new TextView(topLayout.getContext());
          contentTv.setText("【温馨提示】欢迎使用运行IM，在使用过程中如果遇到什么问题，请及时与我们联系。");
          contentTv.setTextColor(Color.parseColor("#333333"));
          contentTv.setBackgroundColor(Color.parseColor("#FFF8DC"));
          contentTv.setPadding(8,8,8,8);
          FrameLayout.LayoutParams layoutParams = new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,150);
          layoutParams.setMargins(16,12,16,12);
          topLayout.addView(contentTv,layoutParams);
        }
      };
  //3、将自定义事件设置到ContactKitClient即可
  ContactKitClient.setContactUIConfig(contactUIConfig);
  

• 效果对比

  默认	自定义后

源码导读

界面布局

在Contact-ui模块中，整个会话列表的布局配置在contact_fragment.xml中，可修改该文件源码实现界面元素调整和界面背景修改等自定义配置。

该文件中的源码概略如下：

<?xml version="1.0" encoding="utf-8"?>

<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    //头部区块，当前包括Titlebar和分割线
    <LinearLayout android:id="@+id/contact_header_layout"
        android:layout_width="match_parent"
        android:layout_height="@dimen/dimen_55_dp"
        android:orientation="vertical"
        app:layout_constraintTop_toTopOf="parent"
        tools:ignore="MissingConstraints">

        <com.netease.yunxin.kit.common.ui.widgets.TitleBarView
            android:id="@+id/contact_title_layout"
            android:layout_width="match_parent"
            android:layout_height="@dimen/dimen_52_dp"
            app:head_title="@string/contact_title"
            app:head_title_color="@color/title_color"/>

        <View
            android:layout_width="match_parent"
            android:layout_height="@dimen/dimen_1_dp"
            android:background="@color/color_e9eff5"
            android:alpha="0.6"
            tools:ignore="MissingConstraints" />

    </LinearLayout>

    //内容区块，列表的形式，ContactListView对RecycleView进行封装，提供多中数据操作接口
    <FrameLayout android:id="@+id/contact_body_layout"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        app:layout_constraintVertical_weight="1"
        app:layout_constraintTop_toBottomOf="@+id/contact_header_layout"
        app:layout_constraintBottom_toTopOf="@+id/contact_bottom_layout">
        <com.netease.yunxin.kit.contactkit.ui.view.ContactListView
            android:id="@+id/contact_listview"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            app:head_img_visible="gone"
            app:head_title="@string/contact_title"
            app:head_title_color="@color/title_color"/>

    </FrameLayout>

    //底部区块，暂时没有使用
    <LinearLayout android:id="@+id/contact_bottom_layout"
        android:layout_width="match_parent"
        android:layout_height="48dp"
        android:orientation="horizontal"
        tools:ignore="MissingConstraints"
        android:visibility="gone"
        app:layout_constraintBottom_toBottomOf="parent">

    </LinearLayout>

</androidx.constraintlayout.widget.ConstraintLayout>

通讯录列表

ContactListView为通讯录列表的实现类，ContactListView是对RecyclerView和ContactAdapter的封装，同时提供数据更新接口，具体如下:

方法	入参类型	说明
setViewHolderFactory	IContactFactory	设置RecyclerView的ViewHolder构造器
setViewConfig	ContactListViewAttrs	设置列表的 UI 个性化配置
showIndexBar	boolean	设置列表是否展示右侧字母索引
addFriendData	List<ContactFriendBean>	添加好友数据，添加到已有数据之后，以 account 为唯一值
removeFriendData	List<ContactFriendBean>	移除好友数据，以 account 为唯一值
updateFriendData	List<ContactFriendBean>	更新好友数据，以 account 为唯一值

通讯录界面UI

• 在通讯录列表中存在两种类型的ViewHolder，即ContactViewHolder和EntranceViewHolder。
  • ContactViewHolder代表好友，其布局文件为friend_contact_view_holder.xml，可以在该文件中调整其布局结构。
  • EntranceViewHolder代表通讯录头部模块，其布局文件为friend_contact_view_holder.xml，可以在该文件中调整其布局结构。
• 调用ViewHolder中的initViewBinding方法和onBind方法可分别实现布局的初始化和数据绑定。