简介：TableViewDemo.zip 是一份面向 Qt 开发者的表格控件高阶用法示例，核心演示如何基于 QAbstractItemModel 自定义数据模型，实现表格行的动态添加与删除，并借助代理模型完成多列表头排序和内容过滤。适合已熟悉基础控件、希望深入理解 Model/View 架构并提升界面数据管理能力的读者。压缩包共 22 个文件，以 C++ 源文件和头文件为主，另含界面文件、样式表、图片资源与工程配置，整体仅 18KB，结构紧凑便于逐个模块分析。项目代码覆盖从模型到视图的完整链路：自定义模型实现行插入删除与排序，代理模型支持多列过滤，按钮委托处理单元格交互，主窗口完成组装，同时附带数据文件和样式表，可运行观察效果。通过学习可掌握表头点击排序、多条件筛选以及运行时行增删的完整思路，并熟悉模型与视图的协作方式，直接迁移到实际业务中，是一份理论与实践结合很好的学习模板。截至目前已有 560 人学习下载，适合 Qt 数据展示与交互开发的中级工程师参考。

1. TableViewDemo.zip 在解决什么：一张列表页背后的四个基础能力

TableViewDemo.zip 这类压缩包，在 iOS 开发里几乎是每个初学者都会遇到的第一个「能跑起来的东西」。它表面上是给你看 UITableView 怎么写，实际上是一个最小可运行的列表页工程，把数据源代理、cell 复用、高度计算、刷新交互这四块基础能力一次性摆在你面前。你解压打开，能立刻看到一个列表在模拟器里滚动，然后照着改数据、换 cell，慢慢理解 UIKit 里最核心的这套机制。

这个标题能帮你解决的问题很具体：第一，你不需要从零搭工程，直接改这个 Demo 就能看到效果；第二，它把 iOS 列表开发里最容易错的几个点——复用标识符不一致、高度不准确、刷新后数据错乱——都用一个工程串起来了；第三，它适合两类人，刚学 iOS 的初学者拿来找手感，以及面试前想快速过一遍 TableView 常用写法的熟手。它不是什么神奇框架，它就是 UITableView 的「标准答案参考书」。

2. 先拆开压缩包：TableViewDemo 的工程结构与你最该先读的三个文件

2.1 工程里的标准骨架：AppDelegate、ViewController 与 Main.storyboard 各管什么

解压 TableViewDemo.zip 之后，你会看到一套标准的 iOS 工程结构。不管这个 Demo 是用纯代码还是 storyboard 写的，核心文件都绕不开这几个：AppDelegate 管应用生命周期，ViewController 是你写 UITableView 的地方，Main.storyboard 或者 xib 负责搭界面的初始形态。我一般建议你先打开工程文件列表，按文件体积从大到小看，最大的那个通常是主控制器，它的 .m 或 .swift 文件里就是列表的全部逻辑。

iOS 工程里文件布局有固定套路，TableViewDemo 这类教学工程通常不会把文件拆得很散。你要找的是这个：一个继承自 UITableViewController 或 UIViewController 并遵循 UITableViewDataSource 协议的文件，里面大概率有 numberOfRowsInSection、cellForRowAt 这两个方法。找到它，你就找到了整个 Demo 的命门。

如果你打开后发现工程报错或者找不到文件，先检查两件事：第一，Podfile 存在与否。老一点的 Demo 可能用了 CocoaPods 集成第三方库，需要先执行 pod install；第二，Xcode 版本和工程格式是否匹配。这些细节我在后面避坑章里会展开。

2.2 数据源与代理：UITableView 为什么需要你回答它这三个问题

UITableView 本身不存数据，它像一个「按需索取」的渲染器。你在界面上看到多少行、每一行长什么样、点击之后干什么，都由你通过数据源和代理方法告诉它。这三件事，对应 UITableViewDataSource 里的两个必须实现方法，以及 UITableViewDelegate 里的可选方法。

// 必须实现方法 1：这个表格一共有多少行 override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return dataArray.count } // 必须实现方法 2：每一行显示什么样的 cell override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: "CellID", for: indexPath) cell.textLabel?.text = dataArray[indexPath.row] return cell } // 可选代理方法：用户点击了某一行之后做什么 override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) { tableView.deselectRow(at: indexPath, animated: true) print("点击了第 \(indexPath.row) 行") }

逻辑说明：tableView 渲染每一行时，会先调用 numberOfRowsInSection 问你有多少行，然后逐行调用 cellForRowAt 问你要这一行的 cell。你把数据源数组 dataArray 的下标和表格的行号对应起来，就能保证每行显示正确的内容。didSelectRowAt 里先调 deselectRow 是个好习惯，否则行会一直保持灰色选中状态。

参数说明：复用标识符 "CellID" 必须和你在 storyboard 或代码里注册 cell 时写的标识符完全一致，大小写敏感。dataArray 是你自己维护的数据源，它决定了列表的总行数和内容。indexPath.row 是行号，indexPath.section 是分组号，两组数据时你得用这两个值共同定位数据。

2.3 cell 注册的两种写法与区别：为什么 nil 崩溃总是找上你

写 cell 复用之前，你必须先让表格知道「CellID 这个标识符对应什么 class 或什么 nib」。注册方式有两种，写错一种就崩溃。第一种适合纯代码创建的 cell，第二种适合用 xib 文件创建的 cell。很多初学者分不清两者，把 nib 的 cell 用 class 注册，运行到 cellForRowAt 就报 unexpected nil。

override func viewDidLoad() { super.viewDidLoad() // 写法一：注册纯代码 class tableView.register(CustomTableViewCell.self, forCellReuseIdentifier: "CodeCell") // 写法二：注册 xib 文件 tableView.register(UINib(nibName: "CustomTableViewCell", bundle: nil), forCellReuseIdentifier: "XibCell") }

逻辑说明：第一种写法告诉表格，遇到 "CodeCell" 就直接实例化 CustomTableViewCell 这个类。第二种写法告诉表格，遇到 "XibCell" 就去加载名为 CustomTableViewCell.xib 的界面文件并创建 cell。你在 storyboard 里拖了 Prototype Cell 时不需要手动注册，storyboard 会帮你做好关联，但纯代码工程必须自己调 register 方法。

参数说明：register 必须在 cellForRowAt 被调用之前执行，通常放在 viewDidLoad。nibName 要和 xib 文件名一字不差。如果 cell 是通过 storyboard 的 Prototype Cell 创建的，就不要在代码里重复注册，重复注册以代码优先，storyboard 的 design 会被覆盖。

3. 从静态数据到真实列表：让 TableViewDemo 动起来的三个关键步骤

3.1 把假数据换成真实模型：为什么别再用字典数组硬撑

TableViewDemo 里初始的数据常常是一个存着字符串的数组，或者一批写死的字典。真实项目里这种写法撑不过一个页面，数据一旦要加字段、要排序、要做校验，字典和数组会让你在 cellForRowAt 里写出一长串类型转换代码。我处理这类 Demo 时习惯先建一个模型结构体，把数据源从「不知道里面是什么的数组」变成「类型明确的模型数组」。

// 定义一个模型 struct ItemModel { let title: String let subtitle: String let iconName: String var isSelected: Bool = false } // 数据源变成模型数组 var dataArray: [ItemModel] = [] // 示例网络解析：把 JSON 字典转成模型 func parseJSON(_ json: [[String: Any]]) { dataArray = json.compactMap { dict in guard let title = dict["title"] as? String else { return nil } return ItemModel(title: title, subtitle: dict["subtitle"] as? String ?? "", iconName: dict["icon"] as? String ?? "default") } }

逻辑说明：compactMap 遍历字典数组，只要缺 title 就丢弃这条数据，避免脏数据进入列表。模型的好处是编译器帮你检查字段类型，一旦写错字段名，编译阶段就报错，而不是运行到某一行才崩。

参数说明：dict["title"] as? String 是安全转换，转换失败时 guard 会提前返回 nil。default 值给 subtitle 和 iconName 兜底，这是处理半结构化数据时最常见也最实用的手段。

3.2 自定义 cell 的最小实现：从系统样式切换到自定义样式的正确姿势

系统自带的 cell 样式只有 title、subtitle、image 三个位，真做项目时远远不够。TableViewDemo 进阶一点就会教你新建一个 cell 子类。这里有个常见误区：很多人在 storyboard 里拖了一个 cell，改了几行代码跑起来没有任何变化，原因是他拖的是静态 cell，而不是注册了可复用的自定义 cell。

// 自定义 cell 类 class CustomTableViewCell: UITableViewCell { @IBOutlet weak var titleLabel: UILabel! @IBOutlet weak var subtitleLabel: UILabel! @IBOutlet weak var iconImageView: UIImageView! func configure(with model: ItemModel) { titleLabel.text = model.title subtitleLabel.text = model.subtitle iconImageView.image = UIImage(named: model.iconName) } }

cellForRowAt 里改成这样：

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { guard let cell = tableView.dequeueReusableCell(withIdentifier: "CustomCell", for: indexPath) as? CustomTableViewCell else { return UITableViewCell() } let model = dataArray[indexPath.row] cell.configure(with: model) return cell }

逻辑说明：dequeueReusableCell 返回的是 UITableViewCell 基类，必须 as? 转成 CustomTableViewCell 才能访问 titleLabel 这些 IBOutlet。configure(with:) 是自定义 cell 里最值得养成的习惯，它把「填充数据」和「获取 cell」解耦，后续 cell 里有按钮、有图片加载、有状态切换，你只需要在 configure 里管理。

参数说明：guard let ... else 在类型转换失败时返回一个空 cell，保证程序不崩，但这一步也意味着你得检查 storyboard 里 cell 的 class 是不是已设置为 CustomTableViewCell。忘记设置 class 是这种 crash 的最高频原因，检查顺序永远是：storyboard 的 cell class → 复用标识符 → register 方法。

3.3 刷新列表数据的正确方式：reloadData 与局部刷新的取舍

数据变完之后让列表刷新，入门写法永远是 tableView.reloadData()。这个方法简单粗暴，但它会让整个列表重新渲染，包括滑出屏幕外的 cell。数据量小没问题，数据量大了，滑到一半突然 reload，轻则卡顿重则闪烁，滚动位置被重置。要达到更精细的控制，需要了解这两个方法的差别并学会组合使用。

// 全量刷新 tableView.reloadData() // 局部刷新：只刷新某个分组 tableView.reloadSections(IndexSet(integer: 0), with: .automatic) // 局部刷新：只刷新某几行 tableView.reloadRows(at: [IndexPath(row: 0, section: 0), IndexPath(row: 1, section: 0)], with: .automatic) // 插入一行 tableView.insertRows(at: [IndexPath(row: 0, section: 0)], with: .automatic)

逻辑说明：insertRows 这类局部操作要求调用前和后数据源数组的数量保持一致。你先向 dataArray 里插入了数据，再调 insertRows，如果数量对不上会直接抛异常。reloadSections 和 reloadRows 同理，必须先改数据，再刷新 UI，顺序反了必崩。

参数说明：with 参数控制动画效果。.automatic 是系统推荐的自动动画，还有 .fade、.none、.top 等选项。页面正在编辑模式时，插入和删除尽量别用 .automatic，容易出现 cell 错乱的动画。数据量小用 reloadData 没问题，数据量超过几百条时就该考虑局部刷新了。

4. 高度与滑动体验：TableViewDemo 没写但你必须补上的三个参数

4.1 固定行高与预估行高：从 rowHeight 到 estimatedRowHeight 的差异在哪

很多 TableViewDemo 里的 cell 高度是默认的 44 点，跑起来能看，但离真实需求差得远。iOS 里控制行高的有两个独立参数，rowHeight 决定每行实际高度，estimatedRowHeight 决定初始化时预估值。默认情况下这两个值都是 UITableView.automaticDimension，也就是由 cell 自身约束自动推算，但如果在 Demo 里开了 automaticDimension 却没用 Auto Layout 约束，cell 会被压成 0 高度。

override func viewDidLoad() { super.viewDidLoad() // 方案一：固定行高 tableView.rowHeight = 60.0 // 方案二：自适应行高（cell 用 Auto Layout 撑起来） tableView.rowHeight = UITableView.automaticDimension tableView.estimatedRowHeight = 44.0 }

逻辑说明：方案一的 60.0 强制所有行都是 60 高，适合图文混排不多、结构统一的列表。方案二告诉系统「行高由 cell 的内容决定」，你在 cell 里用 Auto Layout 把约束顶到底部，系统就能算出来真实高度。estimatedRowHeight 只是一个预估，用来给系统计算滚动条长度，不用精确，但别填 0，填了 0 在滑动时会产生大量高度计算开销。

参数说明：固定行高时不要同时设置 estimatedRowHeight，两个值都设时系统以 automaticDimension 表现为准。自适应高度要求 cell.contentView 的约束链必须完整，缺一条边都会导致高度计算失败，具体表现是控制台输出 Unable to simultaneously satisfy constraints。

4.2 动态高度的计算逻辑：contentView 的约束链为什么缺一不可

动态高度的原理一句话讲是「内容多高，cell 就多高」。但系统怎么知道内容多高？它依赖 cell.contentView 里控件的约束链。一个 label 放在 cell 里，必须同时有四个约束：上、左、下、右，或者外加宽度和高度约束，这样才能从顶部推到指定控件，再推到底部，形成一个闭合的「计算回路」。这条链断掉任何一环，系统就找不到底部在哪里。

布局完整的前提是把 label 的上下左右四条边都固定住，例如 label 距离 top 是 8，距离 bottom 是 8。这样「cell 高度 = label 高度 + 上下边距之和」，label 变高时 cell 自动跟着变高。

// 在 cell 里给 label 设置完整约束的示例 let padding: CGFloat = 8.0 contentView.addSubview(titleLabel) titleLabel.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ titleLabel.topAnchor.constraint(equalTo: contentView.topAnchor, constant: padding), titleLabel.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: padding), titleLabel.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -padding), titleLabel.bottomAnchor.constraint(equalTo: contentView.bottomAnchor, constant: -padding) ])

逻辑说明：translatesAutoresizingMaskIntoConstraints 设为 false 是纯代码加约束的前提，不设置的话系统会自动生成一堆你不需要的约束，和你的代码冲突。NSLayoutConstraint.activate 一次激活四条约束，保持简洁。上下左右都定住之后，cell 高度就完全由 titleLabel 的内容高度和 padding 决定。

参数说明：constant 的负号要注意，trailingAnchor 和 bottomAnchor 的 constant 要写负数，表示向内部偏移。如果你把 label 的 numberOfLines 设为 0，它就能自动换行并撑高 cell；设成 1 的情况下，内容再多也只会截断。

4.3 滑动性能的必查项：cellForRowAt 里不能做的事清单

列表一卡，很多人先去怀疑设备性能，其实是 cellForRowAt 里塞了不该塞的操作。这个方法是滚动时被高频调用的，每滚动一屏都会调用数十次，你把耗时操作放进去，卡顿是必然的。需要避开这几个高频耗时点：同步加载本地大图、执行复杂字符串处理、创建大量临时对象、在主线程做网络请求、每次调用时重新计算相同布局参数。

override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { guard let cell = tableView.dequeueReusableCell(withIdentifier: "CustomCell", for: indexPath) as? CustomTableViewCell else { return UITableViewCell() } let model = dataArray[indexPath.row] // 避免：cell.backgroundColor = calculateExpensiveColor(model) // 避免：cell.titleLabel.text = model.title.uppercased().trimmingCharacters(...) // 推荐：预先处理好数据模型 cell.configure(with: model) return cell }

逻辑说明：预处理的思路是——把字符串转换、颜色计算这种固定逻辑放到数据解析阶段处理一次，存到 model 里，cellForRowAt 里只做简单的赋值。图片加载必须异步，先用占位图，图片下载完成后再赋到 imageView 上，这一条是滑动性能最重要的分水岭。

参数说明：cellForRowAt 里只允许做赋值、状态切换、轻量计算。如果你的 cell 里要展示多种不同布局，不要在一个方法里写 if-else 堆代码，应该拆分出多个 cell 类，用不同复用标识符。

5. 排查与避坑：TableView 开发里最常见的 6 个翻车现场

5.1 崩溃：dequeueReusableCell 返回 nil

现象：点击运行，列表一加载就 crash，控制台提示 fatal error: unexpected nil，停留在 dequeueReusableCell 那行。

原因：复用标识符对不上，或者 register 方法没被调用。storyboard 里写了 "CellID"，代码里却用了 "cellID"，或者视图加载的入口是 xib，而 register 写在另一个控制器的 viewDidLoad 里。

解决：统一标识符命名，大小写必须敏感一致。检查单元格在 storyboard 或 xib 的 identifier 属性，检查 register 调用是否在当前控制器的 viewDidLoad 里执行，顺序要保证。最省事的方式是定义常量，比如 let CellIDKey = "CustomCellID"，所有地方都引用这个常量。

5.2 滚动时 cell 内容错乱

现象：列表往下滑再滑回来，有些行的图片变成了别的行的图片，文字重复显示，或者勾选状态串到了其他行。

原因：cell 被复用了。你滑出屏幕的 cell 没有清除旧数据，新行拿到这个 cell 时，某些控件没被重新赋值，就显示上次的内容。典型就是只设置了有数据的 labl，没有处理无数据时要置空的分支。

解决：在 configure 方法里对每个控件都做赋值，包括没数据时也要给空字符串或占位图。涉及状态的要根据 model 字段重新设置，比如 model.isSelected 决定按钮是否选中，不要依赖 cell 当前的残留状态。

5.3 刷新后列表跳动

现象：调用 reloadData 之后，列表滚到了奇怪的位置，或者明明想看第一页，页面却跳到了中部。

原因：reloadData 会重置 contentOffset，滚动条的位置是预估行高算出来的，在真实高度没有加载完之前，系统按预估高度布排，导致位置偏移。另一个常见原因是刷新时数据源数组被整体替换，但界面还停留在 index 指向的旧位置。

解决：做加载更多时，记录当前滚动位置，刷新后恢复。或者用 insertRows 局部追加，而不是全量 reloadData。处理下拉刷新时，在刷新前记录 contentOffset.y，数据回来后配合 scrollToRow 或 setContentOffset 恢复位置。

5.4 刷新时 cell 插入崩溃

现象：insertRows 调用后崩溃，控制台提示 invalid number of rows，Before update 数量的说明。

原因：数据源和 UI 不同步。先改了数据源但没调用 insert，或者先调用 insert 但忘了往数据源里添加数据。系统在动画前会检查数据源数量变化，不一致立即崩溃。

解决：严格按这个顺序来——先修改数据源数组，再调用 tableView 的 insert/delete 方法，两者之间不能穿插其他 UI 操作。最好把数据源写成一个私有方法变更统一入口，所有增删都走它，避免遗漏。

5.5 高德地图 SDK 和 cell 复用冲突

现象：把地图视图放到 cell 里时，地图闪烁、黑屏，或者滑动后地图变成黑块。

原因：地图视图是很重的控件，复用时生命周期没有被正确管理。cell 滑出屏幕时地图没有被暂停或销毁，新 cell 获得旧地图导致渲染异常。

解决：地图进 cell 的方案本身不推荐，需要用的时候谨慎。常规做法是列表里不放真实地图，放静态截图，点击后再进入地图页面。如果非要在 cell 里放，要在 prepareForReuse 里移除旧地图并重新创建实例，但消耗很大。

5.6 Auto Layout 约束冲突刷屏

现象：控制台刷出 Unable to simultaneously satisfy constraints 警告，列表显示错位或者 cell 高度异常。

原因：代码约束和 storyboard 里的约束重复，或者 VFL 布局与 Auto Layout 混用。最常见的是在代码里给 cell 加了约束，storyboard 里也有一套约束，系统同时生效后冲突。

解决：检查 cell 界面是否残留了 storyboard 里的约束，选中后删除。纯代码布局确保全部用 NSLayoutConstraint，不要半途用 autoresizingMask。用 Debug 面板查看冲突的约束描述，找到是哪个控件的哪一对约束互相矛盾。

6. 进阶用法：把静态 Demo 改成可复用组件的三个步骤

6.1 第一步：把数据源和代理抽离成独立类

TableViewDemo 到了这个阶段就不该满足于「能跑」，你要把它变成真正能塞进项目的组件。第一步是把 UITableViewDataSource 和 UITableViewDelegate 的实现从 ViewController 里分离出来，放到一个专门的类里。这样同一个列表逻辑可以被多个页面复用，页面只需要传入数据数组和 cell 配置闭包。

// 通用列表数据源类 final class GenericTableViewDataSource<Model, Cell: UITableViewCell>: NSObject, UITableViewDataSource { var items: [Model] = [] var configureCell: ((Cell, Model) -> Void)? func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return items.count } func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: String(describing: Cell.self), for: indexPath) as! Cell configureCell?(cell, items[indexPath.row]) return cell } }

逻辑说明：这里用了泛型和闭包，数据源类不关心具体 cell 长什么样，只负责「数量对不对、cell 取出来」这类通用逻辑。具体 cell 怎么配置，由外部通过闭包传入。这样你十个页面共用一个数据源类，每个页面只写自己的配置闭包。

参数说明：String(describing: Cell.self) 直接用类名作为复用标识符，避免手工维护字符串。闭包 configureCell 在 cellForRowAt 中调用，这套模式在很多第三方库里能看到，它把最常变化的部分交给调用方。

6.2 第二步：用 Result 类型封装加载状态

列表页永远要处理三种状态：加载中、加载成功、加载失败。我在改 Demo 的时候会顺手加一个状态枚举。这样 controller 里不用散落一堆布尔变量和空数组判断，一个 switch 就管理全部界面。

enum ListLoadState { case loading case loaded([ItemModel]) case failed(String) var isLoaded: Bool { if case .loaded = self { return true } return false } }

用法上，下拉刷新时把 state 置为 .loading，UI 显示 loading 动画；请求回调后根据结果置为 .loaded 或 .failed。controller 里对 state 做 switch 处理，不需要再去判断数据数组是否为空。这套封装让数据状态变得显式化，谁调用都不会用错。

6.3 第三步：验证组件可用的自检习惯

组件做出来之后，不是跑一次模拟器就算完成。我给自己定了一个自检清单，基本每次抽组件都会过一遍：空数据源时显示什么；加载失败时能不能重试；滚动到底部是否重复触发加载；下拉刷新过程中再次下拉是否被拦截；cell 复用后 UI 是否干净。这条清单帮我挡掉过太多线上问题。

做 TableView 相关的活久了会发现，它不难，但细节多到称得上「玄学」。很多问题不走到真机滑动那一步根本暴露不出来，模拟器上永远岁月静好。我那会儿踩得最深的一个坑是把所有 cell 都用了同一个复用标识符，界面又长得完全不同，结果滚动起来行跟行之间互相「串台」，查了一下午才意识到是复用惹的祸。

希望帮到你。

本文还有配套的精品资源，点击获取