iOS15下Grouped/InsetGrouped样式UITableView设置sectionHeaderTopPadding无效怎么解决

API 探路者

2026-10-1

该现象是否属于系统Bug

这不属于系统Bug。这是iOS 15对UITableView默认布局规范的正式调整：苹果为plain样式的列表新增了sectionHeaderTopPadding属性控制分区头顶部的默认留白，而该属性从设计层面就仅对UITableView.Style.plain样式生效。你遇到的分组样式顶部间隙，是UITableView.Style.grouped/InsetGrouped自带的默认tableHeaderView占位+第一组分区头默认高度共同导致的，属于系统预期行为。

分组样式去除顶部异常间隙的解决方案

按适配成本从低到高，可选择以下方案：

方案1：单页面快速适配
仅需在列表初始化时添加基础配置，再配合代理实现即可：
首先清空默认占位的tableHeaderView：

tableView.tableHeaderView = UIView(frame: CGRect(x: 0, y: 0, width: 0, height: CGFloat.leastNormalMagnitude))

然后实现分区头高度代理，按需调整第一组的分区头高度：

// 按需返回分区头高度
func tableView(_ tableView: UITableView, heightForHeaderInSection section: Int) -> CGFloat {
    // 不需要第一组顶部留白且无自定义分区头就返回极小值，有自定义分区头的话返回自定义高度即可，其他分区按需返回自定义间隔高度
    return section == 0 ? CGFloat.leastNormalMagnitude : 10
}
// 配套返回空的分区头视图，避免高度设置不生效
func tableView(_ tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? {
    return UIView()
}

方案2：全局统一适配
如果项目中存在大量分组列表需要统一调整，可以通过Runtime Method Swizzle HookUITableView的初始化方法，默认插入上述tableHeaderView的配置，减少重复代码。
方案3：替换布局方案
如果你的项目最低支持版本为iOS13+，可以替换为UICollectionViewCompositionalLayout实现分组布局，所有间距的可控性远高于原生UITableView的分组样式，后续系统版本迭代的适配成本也更低。