跳到主要内容

会话列表页面

会话列表页面展示了当前用户设备上的所有会话。一旦 SDK 的本地消息数据库生成消息,SDK 就会生成会话列表,并按照时间倒序排列,置顶会话会排在最前。

IMKit 提供基于 Activity 类和基于 Fragment 类实现的会话列表页面。

  • 基于 Activity:IMKit SDK 默认提供的会话列表。页面支持一个标题栏和一个会话列表。在 SDK 内部页面需要跳转到会话列表时,将跳转到默认的会话列表 Activity。
  • 基于 Fragment:您可以在应用 Activity 中集成 IMKit 提供的会话列表 Fragment,即自定义会话列表 Activity。注意,您需要将自定义会话列表 Activity 注册到 IMKit SDK 中,以替换 IMKit 默认的会话列表 Activity。

会话列表界面

会话列表页面一般由标题栏和会话列表两部分组成。

提示

IMKit 在默认会话列表页面 Activity(RongConversationListActivity)包含了标题栏的实现。如果基于 Fragment 构建会话列表页面,请自行实现标题栏。

(width=250) (width=250)

标题栏

IMKit 仅在默认会话列表页面 Activity(RongConversationListActivity)实现了标题栏。默认展示「会话列表」。

会话列表

会话列表组件按时间倒序显示所有会话的列表,置顶会话会排在最前。长按会话列表中的会话时显示弹窗菜单。IMKit 默认已实现了置顶会话和删除会话功能。

会话列表的每个项目的视图是在 PrivateConversationProvider.java 和其他展示模板中创建和自定义的。您还可以继承使用 BaseDataProcessor,聚合(折叠)或过滤需要在列表中展示的会话项目。

提示

如果开启了多设备消息同步,在 换新设备登录应用卸载重装 场景下,离线补偿机制仅可获取到最近(默认离线补偿天数为 1 天,最大 7 天)的单聊、群聊会话消息。早于该天数的会话无法通过离线补偿机制获取。因此,离线补偿后的会话列表可能与原设备上或卸载前的会话列表并不一致(您可能会有丢失部分会话的错觉)。

用法

IMKit 提供了 Activity 和 Fragment 来创建会话列表页面。RongConversationListActivity 是默认提供的会话列表页面。您可以根据需要,选择直接使用默认的会话列表页面 Activity,或者继承 RongConversationListActivity,或者使用 ConversationListFragment 构建自定义会话列表 Activity。

IMKit 默认已经实现在会话列表页点击某条会话时,跳转到对应的会话页面。

启动会话列表页面

启动会话列表 Activity 有两种启动方式:通过调用 SDK 内置的 Activity 路由器启动,或通过 intent 跳转。您也可以自定义会话列表页的启动方式,实现从应用的其它 Activity 启动会话列表页面。

使用 RouteUtils

RouteUtils 是 IMKit 内置的 Activity 路由器,封装了 SDK 内部各页面跳转方法,可避免应用程序进行重复的 intent 封装。

提示

如果您构建了自定义的会话列表 Activity,必须先向 RouteUtils 注册自定义 Activity,才能通过这种方式跳转到自定义会话列表 Activity,否则跳转的是 SDK 默认的 RongConversationListActivity

跳转到会话列表 Activity:

RouteUtils.routeToConversationListActivity(context, title);
参数类型说明
contextContextactivity 上下文
titleString会话列表页面标题。如果传空,会显示为默认标题 “会话列表”。

通过 intent 跳转

您可以自己组装 Intent, 使用 Android 默认机制进行跳转。

Intent intent = new Intent(context, MyConversationListActivity.class);
context.startActivity(intent);

继承默认会话页面 Activity

您可以通过继承 RongConversationListActivity 创建自定义会话列表 Activity,实现对会话列表页面的调整。注意,必须向 RouteUtils 注册自定义的会话列表 Activity。注册之后,当 SDK 需要跳转到会话列表时,会跳转到您注册的自定义会话列表 Activity。注册方法在应用生命周期内、主进程中调用一次即可。

RouteUtils.registerActivity(RouteUtils.RongActivityType.ConversationListActivity, MyConversationListActivity.class);

使用 Fragment 构建自定义会话列表 Activity

IMKit 提供的会话列表 Fragment 类名为 ConversationListFragment。为方便应用程序自定义会话列表页面,推荐继承使用会话列表 Fragment 类,构建自定义的会话列表 Activity。注意,自定义会话列表 Activity 需要被注册到 IMKit SDK 中,以替换 IMKit 默认的会话列表 Activity。

  1. 您可以在应用 Activity 中集成 IMKit 提供的会话列表 Fragment。以下示例声明一个新的MyConversationListActivity

    <activity
    android:name=".ui.activity.MyConversationListActivity"
    android:launchMode="singleTop"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateHidden|adjustResize">
    </activity>
  2. 描述 Activity 布局。此处以 activity_conversation_list.xml 为例。

    <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <FrameLayout
    android:id="@+id/container" //此容器用于动态放置 fragment
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
    </LinearLayout>
  3. 继承 IMKit 的 ConversationListFragment 创建子类,例如 AppConversationListFragment。在 MyConversationListActivityonCreate() 方法中使用您自定义的会话列表 Fragment 子类。

    class MyConversationListActivity extends FragmentActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_conversation_list);

    ConversationListFragment conversationListFragment=new AppConversationListFragment();
    FragmentManager manager = getSupportFragmentManager();
    FragmentTransaction transaction = manager.beginTransaction();
    transaction.replace(R.id.container, conversationListFragment);
    transaction.commit();
    }
    }
  4. RouteUtils 注册自定义的会话列表 Activity,以替换 IMKit 默认的会话列表 Activity。方法在应用生命周期内、主进程中注册一次即可。

    RouteUtils.registerActivity(RouteUtils.RongActivityType.ConversationListActivity, MyConversationListActivity.class);
    参数类型说明
    activityTypeRongActivityTypeIMKit 内置的 Activity 类型枚举。此处为 RongActivityType.ConversationListActivity
    classClass<? extends Activity>应用自定义的会话列表 Activity 的类名。

    注册完成后,在 SDK 内部页面需要跳转到会话列表场景时,SDK 会自动跳转到您注册的应用 Activity。

定制化

修改会话头像形状

会话列表中的每个会话项目上均会显示一个头像图标,即会话头像(不是聊天页面内中消息列表中的头像)。单聊会话显示对方用户头像,群聊会话显示群组头像,聚合会话显示默认头像或应用程序主动设置的头像。IMKit 支持通过 IMKit 全局配置单独控制会话列表中的会话头像样式。

会话头像显示默认为矩形,可修改为圆形。头像显示大小默认值为 48dp*48dp。请在 App 初始化之后调用以下代码进行设置:

   RongConfigCenter.featureConfig().setKitImageEngine(new GlideKitImageEngine() {
@Override
public void loadConversationListPortrait(@NonNull Context context, @NonNull String url, @NonNull ImageView imageView, Conversation conversation) {
Glide.with(context).load(url)
.apply(RequestOptions.bitmapTransform(new CircleCrop()))
.into(imageView);
}
});

如需修改聊天页面内消息上显示的头像样式,请转至会话页面

设置默认加载会话条目的数量

IMKit 在加载会话列表时(进入会话列表页面、上拉、下拉),默认从本地加载 100 条会话数据。您可以修改默认加载的会话条目数量。

RongConfigCenter.conversationListConfig().setCountPerPage();
提示

客户端的会话列表是根据本地消息生成的,因此会话列表仅从本地获取。

自定义长按会话的弹窗样式

IMKit 默认在长按会话时显示以下弹窗。您可以在设置会话列表监听器 中描述的 onConversationLongClick() 方法中实现自定义处理逻辑,并返回 true,以修改弹窗样式。

(width=250)

添加自定义头、尾、空布局

提示

IMKit 从 5.1.0 版本开始支持该功能。

IMKit 的 ConversationListFragment 支持在会话列表中添加自定义的头(Header)、尾(Footer)和空(Empty)视图。

  1. 继承 IMKit 的 ConversationListFragment 创建子类。

  2. 在子类中实现 addHeaderView()addFooterView()setEmptyView() 等方法,

  3. 在子类的 onViewCreated() 方法中按需调用自身的 addHeaderVew()addFooterView()setEmptyView() 等方法。

        @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);
    addHeaderView(view);
    addFooterView(view);
    setEmptyView(view);
    }

    /**
    * @param view 自定义列表 header view
    */
    public void addHeaderView(View view) {
    mAdapter.addHeaderView(view);
    }

    /**
    * @param view 自定义列表 footer view
    */
    public void addFooterView(View view) {
    mAdapter.addFootView(view);
    }

    /**
    * @param view 自定义列表 空数据 view
    */
    public void setEmptyView(View view) {
    mAdapter.setEmptyView(view);
    }

    /**
    * @param emptyId 自定义列表 空数据的 LayoutId
    */
    public void setEmptyView(@LayoutRes int emptyId) {
    mAdapter.setEmptyView(emptyId);
    }

是否展示网络连接状态提示

当连接断开或者重连时,SDK 会在会话列表页面与会话页面顶部展示连接状态提示栏。

(width=250)

如果需要在会话列表页面上禁用该提示,您可以在应用 res/values 目录下创建 rc_config.xml 文件,将以下变量的值设为 false 来关闭提示栏。该 XML 配置项属于 IMKit 全局默认配置,会同时禁用会话页面与会话列表页面的连接状态提示栏。

<bool name="rc_is_show_warning_notification">false</bool>

是否清除通知栏通知

IMKit 支持在打开者会话列表页面和会话页面时,清除通知面板的所有通知。IMKit 中此开关默认关闭,即不清除通知。

如果需要在会话列表页面时清除通知,您可以在应用 res/values 目录下创建 rc_config.xml 文件,将以下变量的值设为 true。该 XML 配置项属于 IMKit 全局默认配置,会同时影响会话页面与会话列表页面的默认行为。

<!--进入会话或会话列表界面,是否清除通知栏通知-->
<bool name="rc_wipe_out_notification_message">true</bool>

通过 XML 资源自定义 UI

IMKit 支持更改会话列表与其中会话条目的展示样式。如果默认展示样式不能满足需求,您可以通过修改 XML 资源文件修改背景、字体颜色或调整布局里各组件位置等。

IMKit 资源文件位置说明
rc_conversationlist_fragment.xmlres/layout会话列表的展示样式。它是整个输入框的容器。复制 IMKit 源码文件的全部内容,在应用程序项目下创建 /res/layout 下创建同名文件。
rc_conversationlist_item.xmlres/layout会话列表中的每一条会话(item)的展示样式。复制 IMKit 源码文件的全部内容,在应用程序项目下创建 /res/layout 下创建同名文件。

以上 XML 资源也可从 官网 SDK 下载 页面获取。

提示

修改时不要删除 XML 中的 view,不要修改 ID,否则会导致 SDK 崩溃。

自定义会话条目的展示模板

下表列出了 IMKit 中内置的会话列表项展示模板。如果需要修改会话列表项的展示逻辑,建议您自定义展示模板,并注册使用。

模板类名适用场景
PrivateConversationProvider.java单聊会话的展示模板。
BaseConversationProvider.java会话模板基类,缺省模板,没有匹配到其它模板的会话将以此模板展示。
ConversationListEmptyProvider.java空会话列表展示模板 会话列表没有数据时的展示模板。
  1. 创建 CustomConversationProvider,继承会话模板基类 BaseConversationProvider

  2. 重写 isItemViewType() 和其它需要自定义的方法。

    public class CustomConversationProvider extends BaseConversationProvider {
    @Override
    public boolean isItemViewType(BaseUiConversation item) {
    //根据业务需要,判断 item 是该模板需要处理的会话时,返回 true, 否则返回 false
    //此处以自定义私聊会话模板为例
    return item.mCore.getConversationType().equals(Conversation.ConversationType.PRIVATE);
    }

    @Override
    public ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
    //根据业务需要,自定义处理
    return super.onCreateViewHolder(parent, viewType);
    }

    @Override
    public void bindViewHolder(ViewHolder holder, BaseUiConversation uiConversation, int position, List<BaseUiConversation> list, IViewProviderListener<BaseUiConversation> listener) {
    //根据业务需要,自定义处理
    super.bindViewHolder(holder, uiConversation, position, list, listener);
    }
    }
  3. 注册自定义模板,或替换 SDK 内置模板。

    //获取会话模板管理器
    ProviderManager<BaseUiConversation> providerManager = RongConfigCenter.conversationListConfig().getProviderManager();

    //用自定义模板替换 SDK 原有私聊会话展示模板
    providerManager.replaceProvider(PrivateConversationProvider.class, new CustomConversationProvider());

    //注册一个自定义模板
    providerManager.replaceProvider(new CustomSystemConversationProvider());

其他定制化

  • 删除会话:IMKit 默认在长按会话时显示以下弹窗,实现了删除会话功能。如果已有实现无法满足您的需求,可以使用 IMCenter 提供的删除会话 API。
  • 获取会话: IMKit SDK 已经实现了一整套会话获取和展示逻辑,一般不需要额外调用获取会话相关 API。如果已有实现无法满足您的需求,可以使用 IMLib SDK 中相关 API。
  • 会话草稿: IMKit 中默认已实现了获取会话草稿、删除草稿的功能和页面刷新,您不需要额外调用 API。如果已有实现无法满足您的需求,可以使用 IMKit 和 IMLib 提供的 API。
  • 会话置顶: IMKit 中默认已实现了置顶会话、取消置顶等功能和页面刷新,您不需要额外调用 API。如果已有实现无法满足您的需求,可以使用 IMKit 和 IMLib 提供的 API。
  • 自定义处理会话列表数据:支持按会话类型或自定义规则过滤会话,在会话列表展示过滤后的项目。