文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>直播与语聊房（含 UI）>视频直播>直播列表>直播列表（iOS）

直播列表（iOS）

最近更新时间：2025-09-18 11:20:02

我的收藏

本页目录：

功能预览

本文对 TUILiveKit 中的直播列表页面进行了详细的介绍，您可以在已有项目中直接参考本文档集成我们开发好的直播列表页面，也可以根据您的需求按照文档中的内容对页面的样式，布局以及功能项进行深度的定制。
双列瀑布流：默认同时预览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, 示例：YourLiveListViewController
extension 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
// 在您的直播瀑布流列表视图控制器中实现，示例：YourLiveListViewController
class 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. 实现自定义数据源代理: LiveListDataSource
extension 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 回调中, 示例：YourLiveListViewController
extension 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)
    }
    
}
双列瀑布流直播列表转场动画
单列瀑布流转场动画







下一步

恭喜您，现在您已经成功集成了 直播列表 功能。接下来，您可以实现主播开播、观众观看等功能，可参考下表：
功能
描述
集成指引
主播开播
实现主播开播全流程功能，包括开播前的准备和开播后的各种互动
主播开播
观众观看
实现观众进入主播的直播间后观看直播，实现观众连麦 、直播间信息、在线观众、弹幕显示等功能
观众观看

常见问题

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

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

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

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

预览直播画面是否收费？

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

中国站
目录