自定义会话列表界面

协作中台SDK 支持会话列表界面的自定义。可以通过配置接口、实现自定义协议两种方式来对会话列表进行自定义。

配置方式

可以通过配置方式完成会话列表界面的样式自定义，会话列表界面配置定义在 KIMChatListConfig 类中。

接口定义

KIMChatListConfig ：

属性	类型	说明
isEnabledChatListNetworkTips	Bool	会话列表网络异常提示视图是否显示, 默认为true。
isEnabledChatListMultiGroup	Bool	是否开启会话分组模式，默认为true。
popupMenuCellBackgroundColor	UIColor	加号按钮弹窗cell背景颜色。
chatBackgroundColor	UIColor	会话列表Cell - 默认背景色。
chatStickiedColor	UIColor	会话列表Cell - 置顶背景色。
chatSelectedBackgroundColor	UIColor	会话列表Cell - 选中背景色。
chatTimeFont	UIFont	会话列表Cell - 时间文本大小/字体样式。
chatTimeColor	UIColor	会话列表Cell - 时间文本颜色。
chatTimeFormatter	(_ time: Int64) -> String	会话列表Cell - 会话时间格式。
chatTitleFont	UIFont	会话列表Cell - 标题文字大小/标题字体样式。
chatTitleColor	UIColor	会话列表Cell - 标题字体颜色。
chatContentFont	UIFont	会话列表Cell - 摘要 - 文字大小/摘要字体样式。
chatContentColor	UIColor	会话列表Cell - 摘要 - 字体颜色。
chatUnreadBadgeBackgroundColor	UIColor	会话列表Cell - 未读数标记 - 背景颜色。
chatUnreadBadgeTextColor	UIColor	会话列表Cell - 未读数标记 - 文字颜色。
chatSeparatorColor	UIColor	会话列表Cell - 底部分割线颜色。
chatSeparatorLeadingPadding	Float	会话列表Cell - 底部分割线左侧间距。
chatSeparatorTrailingPadding	Float	会话列表Cell - 底部分割线右侧间距。

协议方式

可以通过设置会话列表视图控制器的页面代理并实现相关协议方法来完成会话列表界面的自定义，自定义协议定义在 KIMChatListViewControllerDelegate 中。

接口定义

KIMChatListViewControllerDelegate :

方法	参数	返回值	说明
customTopView(_: )	• controller: KIMChatListViewController 会话列表视图控制器。	UIView 自定义顶部视图。	自定义会话列表顶部视图。可通过实现该方法自定义会话列表顶部视图，返回的自定义视图会固定在会话列表顶部与导航栏底部之间，不随会话列表滚动。
chatListHeaderView(_: )	• controller: KIMChatListViewController 会话列表视图控制器。	UIView 自定义 headerView。	自定义会话列表 headerView。可通过实现该方法自定义会话列表顶部视图，返回的自定义视图会被添加到会话列表的顶部并跟随列表滚动。
chatListViewController(_:configTitleView:)	• controller: KIMChatListViewController 会话列表视图控制器。 • titleView: KIMChatTitleView 标题视图。	Void	配置会话列表导航栏标题视图。可实现该方法，通过 `titleView` 参数获取导航栏标题视图控件，对标题视图控件进行配置，如修改标题样式、添加左右侧按钮等。
chatListViewController(_:updateTitleView:)	• controller: KIMChatListViewController 会话列表视图控制器。 • titleView: KIMChatTitleView 标题视图。	Void	更新会话列表导航栏标题视图。SDK 内部会更新 titleView ，比如更新标题，修改样式等，如果客户需要拦截自行处理这些更新事件，则可以实现该方法覆盖内部的修改，与 configTitleView 不同，此方法会调用多次。
chatListViewController(_:onClickedAddButton:defaultHandler:)	• controller: KIMChatListViewController 会话列表视图控制器。 • button: UIButton 标题栏加号按钮。 • defaultHandler: () -> Void 默认点击处理，调用该闭包执行SDK内部默认点击行为。	Void	标题栏加号按钮点击事件拦截。点击标题栏加号按钮后会调用该方法，可以实现该方法拦截加号按钮点击事件，执行自定义操作。如果需要执行SDK内部默认点击行为，可以调用 `defaultHandler` 闭包实现。
chatListViewController(_:onClickedSearchButton:defaultHandler:)	• controller: KIMChatListViewController 会话列表视图控制器。 • button: UIButton 标题栏搜索按钮。 • defaultHandler: () -> Void 默认点击处理，调用该闭包执行SDK内部默认点击行为。	Void	标题栏搜索按钮点击事件拦截。点击标题栏搜索按钮后会调用该方法，可以实现该方法拦截搜索按钮点击事件，执行自定义操作。如果需要执行SDK内部默认点击行为，可以调用 `defaultHandler` 闭包实现。
chatListViewController(_:updatePopupItems:)	• controller: KIMChatListViewController 会话列表视图控制器。 • items: [KIMPopoverItem] 加号弹窗面板默认数据源。	[KIMPopoverItem] 修改后的加号弹窗面板数据源。	更新会话列表加号弹窗面板数据源。弹窗面板界面数据刷新时会调用该方法，可实现该方法对弹窗面板数据进行二次加工，`items` 为弹窗面板列表默认数据，可基于默认 `items` 进行改造，如修改排序、插入、删除元素，返回新的 `KIMPopoverItem` 数组。
chatListViewController(_:onClickedPopupItem:index:defaultHandler:)	• controller: KIMChatListViewController 会话列表视图控制器。 • item: KIMPopoverItem 被点击的item。 • index: Int 被点击item所在的索引。 • defaultHandler: () -> Void 默认点击处理，调用该闭包执行SDK内部默认点击行为。	Void	加号弹窗面板item点击事件拦截。点击弹窗面板的某个item时会调用该方法，可以实现该方法拦截点击事件，执行自定义操作。如果需要执行SDK内部默认点击行为，可以调用 `defaultHandler` 闭包实现。
chatListViewController(_:configTableView:)	• controller: KIMChatListViewController 会话列表视图控制器。 • tableView: UITableView 会话列表tableView。	Void	配置会话列表tableView。可以通过实现该方法对 tableView 进行配置，如修改会话列表 tableView 背景颜色。
chatListViewController(_:updateChatList:)	• controller: KIMChatListViewController 会话列表视图控制器。 • chats: [KIMChatContext] 会话列表默认数据源。	[KIMChatContext] 修改后的会话列表数据源。	更新会话列表数据源。会话列表界面数据刷新时会调用该方法，可实现该方法对会话列表数据进行二次加工，`chats` 为会话列表默认数据，可基于默认 `chats` 进行改造，如修改排序、插入、删除元素，返回新的 `KIMChatContext` 数组。
chatListViewController(_:tableView:cellForRowAt:chat:)	• controller: KIMChatListViewController 会话列表视图控制器。 • tableView: UITableView 会话列表tableView。 • indexPath: IndexPath cell 索引。 • chat: KIMChatContext 会话数据。	UITableViewCell？自定义cell。	返回自定义会话列表cell。实现该方法返回自定义cell，一般用于会话列表插入自定义cell的场景，可实现 `chatListViewController(_ controller: KIMChatListViewController, updateChatList chats: [KIMChatContext]) -> [KIMChatContext]`方法插入自定义数据，然后在该方法中根据插入的自定义数据返回自定义的cell，如果需要让自定义cell的UI样式跟SDK默认提供的会话列表样式保持一致，可以使用 `KIMChatListCell`视图控件。
chatListViewController(_:tableView: trailingSwipeActionsConfigurationForRowAt: chat:defaultActionsConfiguration:)	• controller: KIMChatListViewController 会话列表视图控制器。 • tableView: UITableView 会话列表tableView。 • indexPath: IndexPath cell 索引。 • chat: KIMChatContext 会话数据。 • defaultActionsConfiguration: UISwipeActionsConfiguration? 默认侧滑事件配置。	UISwipeActionsConfiguration? 修改后的侧滑事件配置，返回nil时不响应侧滑操作。	自定义会话列表cell侧滑事件。实现该方法返回自定义侧滑事件配置，`defaultActionsConfiguration` 为默认侧滑配置，你可以基于默认配置进行修改，比如新增或删除`UIContextualAction`。当返回nil时不响应侧滑操作。
chatListViewController(_:didSelectAt:chat:defaultHandler:)	• controller: KIMChatListViewController 会话列表视图控制器。 • indexPath: IndexPath 点击cell所在的 indexPath。 • chat: KIMChatContext 会话数据。 • defaultHandler: () -> Void 默认点击处理，调用该闭包执行SDK内部默认点击行为。	Void	会话列表cell点击事件拦截。点击会话列表cell后会调用该方法，可以实现该方法拦截会话列表cell点击事件，执行自定义操作。如果需要执行SDK内部默认点击行为，可以调用 `defaultHandler` 闭包实现。

自定义示例

样式配置

会话列表样式配置需要在会话列表加载之前进行，可以通过修改 KIMChatListConfig 中定义的各种属性达到个性化样式配置。

代码示例

SwiftObjective-C

Swift

// 修改会话列表Cell标题文字颜色。
KIM.chatModule.chatListConfig.chatTitleColor = UIColor.black
// 修改会话列表Cell标题文字大小。
KIM.chatModule.chatListConfig.chatTitleFont = UIFont.systemFont(ofSize: 17)

Objective-C

// 修改会话列表Cell标题文字颜色。
KIM.chatModule.chatListConfig.chatTitleColor = [UIColor blackColor];
// 修改会话列表Cell标题文字大小。
KIM.chatModule.chatListConfig.chatTitleFont = [UIFont systemFontOfSize:17];

自定义标题栏

会话列表标题栏默认展示了未读消息状态及右侧搜索、加号按钮。可通过实现KIMChatListViewControllerDelegate的 configTitleView 、onClickedSearchButton、onClickedAddButton等协议方法来自定义标题栏的展示及点击事件。

代码示例

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。

    // 配置会话列表导航栏标题视图。
    func chatListViewController(_ controller: KIMChatListViewController, configTitleView titleView: KIMChatTitleView) {
        // 隐藏标题栏返回按钮
        titleView.setBackButton(hide: true)
        // 设置返回按钮点击事件
        titleView.setBackButtonAction {
            // 返回按钮事件回调
        }
        // 设置标题栏标题展示位置
        titleView.position = .center
        // 设置标题栏标题颜色
        titleView.titleAttributes = [ .foregroundColor: UIColor.white, .font: UIFont.boldSystemFont(ofSize: 16)]
        // 设置导航栏背景色
        titleView.navigaitonBarBackgroundColor = .init(hex: "#582263")
        // 设置导航栏返回按钮的图标颜色
        titleView.backButton.tintColor = .white

        // 设置默认按钮（搜索、更多）的图标颜色
        var rightViews = titleView.rightViews
        for view in rightViews {
            view.tintColor = .white
        }
        // 实现导航栏右侧新增按钮/视图
        rightViews.insert(customView(), at: 0)
        // 设置到导航栏的右侧
        titleView.setRightItems(rightViews)
    }

    func chatListViewController(_ controller: KIMChatListViewController, updateTitleView titleView: KIMChatTitleView) {
        // 此处拦截标题栏更新，可自定义标题栏内容
        print("当前的标题: \(titleView.titleLabel.text ?? "")")

            // 设置返回按钮的图标颜色
        titleView.backButton.tintColor = .white
        titleView.backButton.setImage(titleView.backButton.image(for: .normal)?.withRenderingMode(.alwaysTemplate), for: .normal)
    }
    
    // 标题栏搜索按钮点击事件拦截。
    func chatListViewController(_ controller: KIMChatListViewController, onClickedSearchButton button: UIButton, defaultHandler: @escaping () -> Void) {
        // 实现自定义事件，如果需要执行默认事件操作，可以执行 defaultHandler()
        // defaultHandler()
    }

    // 标题栏加号按钮点击事件拦截。
    func chatListViewController(_ controller: KIMChatListViewController, onClickedAddButton button: UIButton, defaultHandler: @escaping () -> Void) {
        // 实现自定义事件，如果需要执行默认事件操作，可以执行 defaultHandler()
        // defaultHandler()
    }
}

自定义加号弹窗面板

会话列表标题栏右上角加号弹窗面板默认展示了”发起群聊“和”通讯录“菜单，可通过实现KIMChatListViewControllerDelegate的 updatePopupItems 、onClickedPopupItem 等协议方法来自定义加号弹窗面板菜单项及点击事件。

代码示例

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。
    
    // 更新会话列表加号弹窗面板数据源
    func chatListViewController(_ controller: KIMChatListViewController, updatePopupItems items: [KIMPopoverItem]) -> [KIMPopoverItem] {
        // 自定义气泡视图数据源
        var addDataSource = [
            KIMPopoverItem(title: KIMPopoverItem.kPopoverTitleCustom1, image: UIImage(named: "demo_custom_button_addmenu")),
            KIMPopoverItem(title: KIMPopoverItem.kPopoverTitleCustom2, image: UIImage(named: "demo_custom_button_addmenu"))
        ]
        addDataSource.append(contentsOf: items)
        return addDataSource
    }

    // 加号弹窗面板item点击事件拦截
    func chatListViewController(_ controller: KIMChatListViewController, onClickedPopupItem item: KIMPopoverItem, index: Int, defaultHandler: @escaping () -> Void) {
        if item.title == KIMPopoverItem.kPopoverTitleCustom1 {
            // 处理事件1
        } else if item.title == KIMPopoverItem.kPopoverTitleCustom2 {
            // 处理事件2
        } else {
            // 其他内部按钮执行默认事件。
            defaultHandler()
        }
    }
}

拦截会话列表点击事件

可通过实现KIMChatListViewControllerDelegate的 didSelectAt 协议方法拦截会话列表点击事件。

代码示例

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。
    
    // 会话列表点击事件拦截。
    func chatListViewController(_ controller: KIMChatListViewController, didSelectAt indexPath: IndexPath, chat: KIMChatContext, defaultHandler: @escaping () -> Void) {
        if let customData = chat.customData as? CustomItem {
            // 拦截点击事件
            KIMHud.showMessage("点击事件被拦截", inView: self.view)
        } else {
            // 其他情况走内部默认流程。
            defaultHandler()
        }
    }
}

拦截会话列表左滑事件

会话列表 cell 左滑数据通过 UISwipeActionsConfiguration 生成，通过实现KIMChatListViewControllerDelegate的 trailingSwipeActionsConfigurationForRowAt 方法自定义会话列表左滑事件。

代码示例

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。
    
    // 会话列表侧滑事件拦截。
    func chatListViewController(_ controller: KIMChatListViewController, 
                                tableView: UITableView,
                                trailingSwipeActionsConfigurationForRowAt indexPath: IndexPath,
                                chat: KIMChatContext,
                                defaultActionsConfiguration: UISwipeActionsConfiguration?) -> UISwipeActionsConfiguration? {
        if chat.customData is CustomItem {
            let action = UIContextualAction(style: .destructive, title: "自定义1") { _, _, callback in
                KIMHud.showMessage("测滑事件被拦截", inView: self.view)
                callback(true)
            }
            return UISwipeActionsConfiguration(actions: [action])
        } else {
            // 返回默认事件。
            return defaultActionsConfiguration
        }
    }
}

自定义顶部提示条

SDK会话列表默认提供了网络异常提示条的展示。

如果想要自定义顶部提示条，可以通过以下方法：

代码示例

隐藏默认的顶部网络异常提示条。

Swift

KIM.chatModule.chatListConfig.isEnabledChatListNetworkTips = false

实现KIMChatListViewControllerDelegate的 customTopView 或 chatListHeaderView 方法。

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。
    
    /// 自定义会话列表顶部视图，返回的自定义视图会固定在会话列表顶部与导航栏底部之间，不随会话列表滚动。
    func customTopView(_ controller: KIMChatListViewController) -> UIView {
        return customView()
    }
    
    /// 自定义会话列表 headerView。返回的自定义视图会被添加到会话列表的顶部并跟随列表滚动。
    func chatListHeaderView(_ controller: KIMChatListViewController) -> UIView {
        return customView()
    }
}

插入自定义会话

SDK会话列表支持插入自定义会话。

插入自定义会话，可以通过以下方法：

代码示例

修改会话数据，如对会话列表数据进行插入，删除，调整排序等操作。

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。
    
    // 会话列表界面数据刷新时会调用该方法，可实现该方法对会话列表数据进行二次加工，`chats` 为会话列表默认数据，可基于默认 `chats` 进行改造，如修改排序、插入、删除元素，返回新的 `KIMChatContext` 数组。
    func chatListViewController(_ controller: KIMChatListViewController, updateChatList chats: [KIMChatContext]) -> [KIMChatContext]{
        var dataSource = chats
        // 插入自定义数据示例：
        dataSource.insert(contentsOf: customDatas.map({ .init(customData: $0) }), at: 0)
        // 调整已有会话顺序示例如：【团队广场】
        if let teamSquare = dataSource.filter({ $0.boxInfo?.type == KIMBoxType.subscription.rawValue }).first {
            dataSource.removeAll(where: {
                $0.boxInfo?.type == KIMBoxType.subscription.rawValue
            })
            dataSource.insert(teamSquare, at: 0)
        }
        return dataSource
    }
}

绘制自定义会话Cell。

Swift

// 1. 继承自会话列表视图控制器。
class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {

   // 2. 重写初始化方法，设置页面自定义协议代理。
   required init() {
        super.init()
        // 设置页面定制化协议代理。
        self.delegate = self
    }

    // 3.实现 KIMChatListViewControllerDelegate 相关协议方法。

    // 注册cell
    func chatListViewController(_ controller: KIMChatListViewController, configTableView tableView: UITableView) {
        tableView.register(KIMChatListCell.self, forCellReuseIdentifier: String(describing: "\(KIMChatListCell.self)"))
    }    

   // 返回自定义cell。
   func chatListViewController(_ controller: KIMChatListViewController, tableView: UITableView, cellForRowAt indexPath: IndexPath, chat: KIMChatContext) -> UITableViewCell? {
        // 渲染自定义数据。可以使用SDK提供的已有列表控件 `KIMChatListCell` 或者完全自定义 UITableViewCell
        if let customData = chat.customData as? CustomItem {
            let cell = tableView.dequeueReusableCell(withIdentifier: String(describing: "\(KIMChatListCell.self)"), for: indexPath) as! KIMChatListCell
            cell.configureCell(cellState: .init(badgeCount: customData.unreadCount,
                                                avatarURLs: [],
                                                avatarLocal: customData.image,
                                                chatTitle: customData.title,
                                                contentText: NSAttributedString(string: customData.content, attributes: [.foregroundColor: UIColor.d_textTertiary]),
                                                timeText: customData.timeText,
                                                isUndisturbViewVisible: false,
                                                isStickied: false, tagViews: []))
            return cell
        }
        return nil
    }
}

必要时刷新会话列表数据，用于插入的自定义会话数据需要异步请求的场景。

Swift

class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // 模拟网络请求。
        DispatchQueue.main.asyncAfter(deadline: .now() + 3) {
            // 刷新界面数据
            self.reloadDataSource()
        }
    }   
}

全局替换视图控制器

如果子类化会话列表视图控制器后，希望SDK内部入口在初始化会话列表页面时都使用子类类型，可以通过设置会话列表视图控制器的子类类型chatListViewControllerType来达到效果。

代码示例

Swift

KIM.chatModule.chatListViewControllerType = CustomChatListViewController.self

会话列表界面

消息列表界面

会话数据接口

消息数据接口

会话列表界面

消息列表界面

会话数据接口

消息数据接口

自定义会话列表界面 ​

配置方式 ​

接口定义 ​

协议方式 ​

接口定义 ​

自定义示例 ​

样式配置 ​

代码示例 ​

自定义标题栏 ​

代码示例 ​

自定义加号弹窗面板 ​

代码示例 ​

拦截会话列表点击事件 ​

代码示例 ​

拦截会话列表左滑事件 ​

代码示例 ​

自定义顶部提示条 ​

代码示例 ​

插入自定义会话 ​

代码示例 ​

全局替换视图控制器 ​

代码示例 ​

自定义会话列表界面

配置方式

接口定义

协议方式

接口定义

自定义示例

样式配置

代码示例

自定义标题栏

代码示例

自定义加号弹窗面板

代码示例

拦截会话列表点击事件

代码示例

拦截会话列表左滑事件

代码示例

自定义顶部提示条

代码示例

插入自定义会话

代码示例

全局替换视图控制器

代码示例