# 自定义会话列表界面 协作中台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` 中定义的各种属性达到个性化样式配置。 #### 代码示例 ::: code-group ```Swift [Swift] // 修改会话列表Cell标题文字颜色。 KIM.chatModule.chatListConfig.chatTitleColor = UIColor.black // 修改会话列表Cell标题文字大小。 KIM.chatModule.chatListConfig.chatTitleFont = UIFont.systemFont(ofSize: 17) ``` ```Objective-C [Objective-C] // 修改会话列表Cell标题文字颜色。 KIM.chatModule.chatListConfig.chatTitleColor = [UIColor blackColor]; // 修改会话列表Cell标题文字大小。 KIM.chatModule.chatListConfig.chatTitleFont = [UIFont systemFontOfSize:17]; ``` ::: ### 自定义标题栏 会话列表标题栏默认展示了未读消息状态及右侧搜索、加号按钮。可通过实现`KIMChatListViewControllerDelegate`的 `configTitleView` 、`onClickedSearchButton`、`onClickedAddButton`等协议方法来自定义标题栏的展示及点击事件。 #### 代码示例 ::: code-group ```Swift [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` 等协议方法来自定义加号弹窗面板菜单项及点击事件。 #### 代码示例 ::: code-group ```Swift [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` 协议方法拦截会话列表点击事件。 #### 代码示例 ::: code-group ```Swift [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` 方法自定义会话列表左滑事件。
#### 代码示例 ::: code-group ```Swift [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会话列表默认提供了网络异常提示条的展示。 如果想要自定义顶部提示条，可以通过以下方法： #### 代码示例 1. 隐藏默认的顶部网络异常提示条。 ::: code-group ```Swift [Swift] KIM.chatModule.chatListConfig.isEnabledChatListNetworkTips = false ``` ::: 2. 实现`KIMChatListViewControllerDelegate`的 `customTopView` 或 `chatListHeaderView` 方法。 ::: code-group ```Swift [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会话列表支持插入自定义会话。 插入自定义会话，可以通过以下方法： #### 代码示例 1. 修改会话数据，如对会话列表数据进行插入，删除，调整排序等操作。 ::: code-group ```Swift [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 } } ``` ::: 2. 绘制自定义会话Cell。 ::: code-group ```Swift [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 } } ``` ::: 3. 必要时刷新会话列表数据，用于插入的自定义会话数据需要异步请求的场景。 ::: code-group ```Swift [Swift] class CustomChatListViewController: KIMChatListViewController, KIMChatListViewControllerDelegate {     override func viewDidLoad() {     super.viewDidLoad()             // 模拟网络请求。     DispatchQueue.main.asyncAfter(deadline: .now() + 3) {             // 刷新界面数据     self.reloadDataSource()     }     }   } ``` ::: ## 全局替换视图控制器 如果子类化会话列表视图控制器后，希望SDK内部入口在初始化会话列表页面时都使用子类类型，可以通过设置会话列表视图控制器的子类类型`chatListViewControllerType`来达到效果。 ### 代码示例 ::: code-group ```Swift [Swift] KIM.chatModule.chatListViewControllerType = CustomChatListViewController.self ``` :::