即时通信 IM 直播列表（iOS）

一、功能预览

·双列瀑布流：默认同时预览2个直播间的画面。

·单列瀑布流：默认同时预览1个直播间的画面（仅视频直播支持单列预览）。

注意：预览直播间画面时，预览时长都会被计入观众的音视频时长，组件详细计费相关内容请参考 计费说明。

二、步骤1：开通服务

参考 开通服务 文档开通「体验版」或「大规模直播版」套餐。

三、步骤2：代码集成

参考 准备工作 接入 TUILiveKit。

四、步骤3：添加直播列表瀑布流视图

你可以根据需要选择使用单列或双列瀑布流。

Swift// 示例： YourLiveListViewController 代表你直播列表瀑布流的视图控制器class YourLiveListViewController: UIViewController { // 1. 声明 liveListView 作为成员变量 // – style: .doubleColumn // 双列瀑布流 // – style: .singleColumn // 单列瀑布流 // 示例为双列瀑布流，如需单列传入 .singleColumn即可 private let liveListView = LiveListView(style: .doubleColumn)  public override func viewDidLoad() { super.viewDidLoad() // 2. 将 liveListView 添加到视图上 view.addSubview(liveListView) liveListView.snp.makeConstraints { make in make.edges.equalToSuperview() } // 3. 设置列表的点击事件代理 liveListView.itemClickDelegate = self }}

五、步骤4：实现直播列表页到观众观看页的路由跳转

双列瀑布流直播列表 和 单列瀑布流 均会通过 OnItemClickDelegate回调点击事件，你只需在直播列表视图控制器中实现 OnItemClickDelegate 来响应用户的点击事件，并在 onItemClick 中实现跳转进入观众观看页的功能，观众观看页的实现可参考 观众观看:

交互示例：

代码示例：

Swift// 在你的直播瀑布流列表视图控制器中实现 OnItemClickDelegate, 示例：YourLiveListViewControllerextension YourLiveListViewController: OnItemClickDelegate { func onItemClick(liveInfo: LiveInfo, frame: CGRect) { // 1. 实例化你的观众观看视图控制器 let audienceVC = YourAudienceViewController(roomId: liveInfo.roomId) audienceVC.modalPresentationStyle = .fullScreen // 2. 跳转到你的观众观看视图控制器 present(audienceVC, animated: false) } }

六、步骤5：直播列表的页面跳转交互优化

为了让你在页面跳转过程中获得更加完整与流畅的体验，结合 iOS 页面路由的系统特性，LiveListView 组件提供了 refreshLiveList 和 onRouteToNextPage 方法，方便你仅通过简单的一行代码调用，就能优化直播列表展示与视频流播放体验。具体优化方式如下：

Swift// 在你的直播瀑布流列表视图控制器中实现，示例：YourLiveListViewControllerclass YourLiveListViewController: UIViewController { override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) // refreshLiveList: 在viewDidAppear时调用此方法，以确保每次回到当前页面都能拿到最新的列表 liveListView.refreshLiveList() } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) // onRouteToNextPage: 在viewWillDisappear时调用此方法，当你进入别的页面时停止当前直播列表页播放的视频流 liveListView.onRouteToNextPage() }}

七、自定义你的界面布局

TUILiveKit 提供了灵活的接口定制直播列表瀑布流组件，你可以根据业务需求自定义数据源和列表项样式。

八、自定义数据源

如果你的后台有单独的直播列表数据，可以通过实现 LiveListDataSource 接口来自定义数据源，而不使用组件默认的列表数据。

Swift// 示例：YourLiveListViewController 代表你直播列表瀑布流的视图控制器class YourLiveListViewController: UIViewController { private let liveListView: LiveListView = LiveListView(style: .doubleColumn)  public override func viewDidLoad() { super.viewDidLoad() view.addSubview(liveListView) liveListView.snp.makeConstraints { make in make.edges.equalToSuperview() } liveListView.itemClickDelegate = self // 1. 设置自定义数据源代理 liveListView.dataSource = self }}// 2. 实现自定义数据源代理: LiveListDataSourceextension YourLiveListViewController: LiveListDataSource { public func fetchLiveList(cursor: String, onSuccess: @escaping LiveListBlock, onError: @escaping TUIErrorBlock) { // 3. 对接自己的业务后台，按照下面的格式返回数据给UI组件 var liveInfoList: [LiveInfo] = [] var liveInfo = LiveInfo() liveInfo.roomId = "live_123456" liveInfo.name = "live_123456" liveInfoList.append(liveInfo) let cursor = "aabbccdd" onSuccess(cursor, liveInfoList) }}

九、自定义挂件

瀑布流列表项底部默认显示视频流画面或直播封面。如果你需要自定义列表项顶部的 UI 元素（例如主播头像、直播标题等），可以通过实现 LiveListViewAdapter 接口来完成。

Swift// 示例：YourLiveListViewController 代表你直播列表瀑布流的视图控制器class YourLiveListViewController: UIViewController { private let liveListView: LiveListView = LiveListView(style: .doubleColumn)  public override func viewDidLoad() { super.viewDidLoad() view.addSubview(liveListView) liveListView.snp.makeConstraints { make in make.edges.equalToSuperview() } liveListView.itemClickDelegate = self liveListView.dataSource = self // 1. 设置自定义挂件代理 liveListView.adapter = self }}// 2. 实现自定义挂件代理extension YourLiveListViewController: LiveListViewAdapter { public func createLiveInfoView(info: LiveInfo) -> UIView { // 自定义挂件view return YourCustomView(liveInfo: info) } public func updateLiveInfoView(view: UIView, info: LiveInfo) { if let infoView = view as? YourCustomView { // 更新挂件view中绑定的数据 infoView.updateView(liveInfo: info) } }}

十、自定义转场动画

在双列瀑布流直播列表和单列瀑布流中跳转到观众观看页，为了转场效果更好，往往需要自定义转场动画。 TUILiveKit 在 GitHub 仓库开源了直播转场动画 LiveTransitioningDelegate ，你只需设置 audienceVC.transitioningDelegate 即可实现跟 TUILiveKit 一样的转场动画：

Swift// 在你的直播瀑布流列表视图控制器中的 OnItemClickDelegate 回调中, 示例：YourLiveListViewControllerextension YourLiveListViewController: OnItemClickDelegate { func onItemClick(liveInfo: LiveInfo, frame: CGRect) { let audienceVC = YourAudienceViewController(roomId: liveInfo.roomId) audienceVC.modalPresentationStyle = .fullScreen // 设置过渡动画代理 audienceVC.transitioningDelegate = LiveTransitioningDelegate(originFrame: frame) present(audienceVC, animated: false) } }

十一、下一步

恭喜你，现在你已经成功集成了 直播列表 功能。接下来，你可以根据你的业务场景实现主播开播、观众观看等功能

视频直播场景：

语聊房场景：

十二、集成直播列表功能后页面没有任何直播怎么办？

如果你看到空白页面，需要检查你是否已完成 登录步骤。为了测试该功能，你可以使用两台设备：一台设备用于开播，另一台设备在直播列表页面，就能拉取到已开播的直播间。

十三、单列瀑布流和双列瀑布流有什么区别？

单列瀑布流一次预览一个直播间画面，而双列瀑布流则同时预览两个直播间画面。你可以根据自己的设计需求选择合适的布局。

十四、预览直播画面是否收费？

是的，预览直播间画面时长会计入观众的音视频时长，这部分是需要付费的。详细的 计费说明 可以参考文档中的相关内容。

十五、我使用了自定义数据源 (LiveListDataSource)，但列表不显示/不刷新怎么办？

请确保你正确实现了 LiveListDataSource 接口。重点检查以下几点：

·检查 fetchLiveList 方法是否被正确调用。

·确保在获取数据后（无论成功或失败）都调用了 callback.onSuccess 或 callback.onFailure。

·检查你的业务后台接口是否返回了正确的数据格式。