这是 Flutter 高级滚动系列的第 13 篇。前面几篇把 SliverAppBar、SliverToBoxAdapter、SliverList 这些基础块都拆过一遍之后,评论区里问得最多的一个问题就是:能不能用这套东西,复刻一个 iOS 通讯录那样的滚动交互?这期就来干这个事。iOS 通讯录的滚动体验,总结下来是四个字:快、准、稳。几千个联系人放在 CustomScrollView 里,右侧一排 A-Z 字母索引条,随手一拖就能滑到目标分组;滚动过程中当前分组的字母标题吸在顶部,不挡内容不跳位;当前字母还会在索引条上同步高亮,拖动时屏幕中央浮出大号字母气泡告诉你正在哪一组。这篇文章会把方案选型、Sliver 组合、偏移计算、索引条联动、性能优化整个走一遍,最后把我实际踩过的 5 个坑列出来,代码可以直接抄。
1. 从 ListView 到 CustomScrollView:iOS 通讯录滚动体验难在哪
1.1 拆开 iOS 通讯录的 4 个交互细节
先把“iOS 通讯录体验”拆开看,不然很容易做成一个“看起来很接近但滚起来就是别扭”的 Demo。我实际拆下来,核心交互就四个:
分组吸顶。A 组联系人往下滚,顶部始终显示 A 这个字母标题;滚到 B 组时,A 标题被平滑顶走,B 标题接上来。这个不是简单的 fixed widget,而是一连串分区滚动状态的切换,每个分组的标题都会经历“普通位置 -> 吸附顶部 -> 被顶走”三个阶段。
长列表懒加载。通讯录几千人是常态,滚动起来不卡的原因在于可视区之外的内容根本没有参与构建。这在 Flutter 里对应 Sliver 的懒渲染特性,也是我们坚持用 CustomScrollView 而不是普通 ListView 的根本原因。
字母索引条快速导航。右侧一排 A-Z,点击或者拖动可以跳转到对应分组。难点不在手势本身,而在于“把字母映射成滚动坐标”,每个分组人数不一样,分组头的坐标不能靠列表 index 直接算。
当前分组回显与反馈。手动滚动列表时,右侧索引条上的当前字母要同步高亮;拖动索引条跳转时,屏幕中央出现大号字母气泡。这两个反馈分别对应“滚动驱动 UI”和“手势驱动 UI”两个方向,一不留神就会写成两套互相打架的状态。
这四个交互没有一个是独立的。吸顶标题的位置和索引条跳转的目标,本质上都是“分组头的滚动偏移量”;高亮回显又要求我们能实时解析当前滚动位置所属分组。所以难点不在某一个特效上,而在把它们统一进同一套滚动坐标体系里。
1.2 为什么 ListView 硬拼不起来
有人会说,我不用 Sliver,用 ListView 不也能渲染长列表吗?确实能,但要做到上面四个交互,会撞上墙。
用 ListView.separated 在中间插 header 行,header 滚出视口就是个普通 item,没法吸顶。想在 Stack 里叠一个固定吸顶组件,你就得实时算“当前第一个可见 item 属于哪个分组”,但 ListView 的 item index 和分组边界没有一对一关系,尤其行高不统一时,第一个可见 item 的分组推断非常脆弱。再叠加字母索引条跳转,你需要在 index 和分组之间维护一张映射表,算到头来等于手写一遍 Sliver 的布局逻辑,性能和正确性都很难保证。
换一个思路,用 FixedExtentScrollController?它只能按固定 item index 定位,通讯录这种每个分组长度不一的场景,跳转距离 = 前面所有分组的 header 高度 + 行数乘行高,不是一个简单的 itemExtent * index 能覆盖的。
结论很明确:这一整套本来就是 CustomScrollView 的适用场景。它不是让你拿 Sliver 去模拟 ListView,而是把列表拆成一堆 Sliver 渲染块,让 Scrollable 统一管理滚动坐标。分组头是 SliverPersistentHeader,联系人行是 SliverList,它们共享同一个滚动位置,吸顶、跳转、回显才可能联动起来。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 整体设计与技术选型:CustomScrollView + Sliver 组合方案
2.1 数据结构与 Sliver 生成:把分组翻译成 Sliver
进入实现前,先定数据结构。通讯录按首字母分组,很自然会用一个二维结构:
dart复制class Contact {
final String name;
final String phone;
}
class ContactGroup {
final String letter;
final List<Contact> contacts;
}
拿到 List<ContactGroup> 之后,最直接的做法是循环生成 slivers。一个分组对应两个 Sliver:一个吸顶标题、一个列表主体。
dart复制final List<Widget> slivers = [];
for (final group in groups) {
slivers.add(SliverPersistentHeader(
pinned: true,
delegate: SectionHeaderDelegate(
letter: group.letter,
height: 30,
),
));
slivers.add(SliverFixedExtentList(
itemExtent: 56,
delegate: SliverChildBuilderDelegate(
(context, index) => ContactRow(contact: group.contacts[index]),
childCount: group.contacts.length,
),
));
}
CustomScrollView(
controller: _scrollController,
slivers: slivers,
);
这里我特意用了 SliverFixedExtentList 而不是 SliverList,原因后面第 5 章展开,简单说就是联系人行高固定时,固定行高列表能省掉大量重复测量。
有的项目会想在 SliverChildBuilderDelegate 里靠 index 判断当前应该渲染 header 还是 row,我建议不要。因为 SliverPersistentHeaderDelegate 需要单独的实例,而且后续做偏移表、字母索引跳转时,我们需要知道每个分组的边界索引。提前把 slivers 展开成 List<Widget>,结构扁平、逻辑直观,后期按分组做缓存和调试都方便。
2.2 SliverPersistentHeader:pinned、floating、snap 到底怎么选
SliverPersistentHeaderDelegate 有三个模式,很多人一开始就分不清。
pinned: true 表示 header 始终钉在滚动视口顶部,滚动到它所在位置时吸附,滚过之后继续占住顶部,直到下一个 header 把它顶走。分组字母头用这个,因为通讯录里就是要让“当前分组字母”一直可见。
floating: true 表示向下滚动时 header 会提前滑回来,向上滚动时它正常滚出。行为表现是:你正在缓慢上滑,header 会很快消失在顶部;一旦反向滑动,它立刻重新出现。这个适合做搜索框之类的临时工具条,不需要一直占用空间。
snap: true 是 floating 的增强,松手时 header 自动停在完全显示或完全隐藏两种状态,不会停在半路。
通讯录的两个头部,我的选择是:分组字母头用 pinned,搜索框固定在 CustomScrollView 外部。为什么搜索框不放进 Sliver?因为放进 Sliver 且不是 pinned 的话,索引条跳转的偏移表会复杂很多。搜索框参与滚动时,第一组的 A header 在搜索框下方,跳转 Z 的偏移量里要不要把搜索框高度算进去,取决于搜索框当前是否还在屏幕上,这个偏移会动态变化。与其在这里跟动态偏移缠斗,不如把搜索框放在外部 Column 固定住,CustomScrollView 从第一个分组开始,偏移表就变成一张纯静态表。代价只是搜索框永远占着一行高度,但通讯录里搜索是高频操作,常驻反而更符合使用习惯。
如果你的设计稿要求搜索框滚走,那建议把它做成 SliverPersistentHeader(pinned: false, floating: true, snap: true)。我会在第 6 章讲清楚这样会让偏移表多点什么麻烦。
3. 核心实现:分组吸顶、行高固定与滚动偏移计算
3.1 分组吸顶头:delegate 的实现与两个取值范围
SliverPersistentHeaderDelegate 是 Sticky Header 的灵魂,它有四个必须实现的方法:minExtent、maxExtent、build、shouldRebuild。
dart复制class SectionHeaderDelegate extends SliverPersistentHeaderDelegate {
SectionHeaderDelegate({required this.letter, required this.height});
final String letter;
final double height;
@override
double get minExtent => height;
@override
double get maxExtent => height;
@override
Widget build(BuildContext context, double shrinkOffset, bool overlapsContent) {
return Container(
height: height,
color: const Color(0xFFF2F2F7),
alignment: Alignment.centerLeft,
padding: const EdgeInsets.symmetric(horizontal: 16),
child: Text(
letter,
style: const TextStyle(fontWeight: FontWeight.w600, fontSize: 14),
),
);
}
@override
bool shouldRebuild(covariant SectionHeaderDelegate oldDelegate) {
return oldDelegate.letter != letter || oldDelegate.height != height;
}
}
有两个容易踩的细节。第一,minExtent 和 maxExtent 都设为同一个固定高度。如果 min 是 0、max 是 30,header 会在滚动过程中被压缩,文字会被裁切,视觉效果就是分组标题“塌”下去了。通讯录的字母头高度固定,不需要可伸缩动画,两个值保持一致最稳。第二,Container 必须显式设置 height: height。有人只加 padding 不加高度,shrinkOffset 大于 0 时内容会被挤压,出现文字截断。背景色建议用浅灰并加一条底部分割线,这样多个分组连续滚动时能清晰分辨边界。
shouldRebuild 里比较 letter 和 height,是为了避免列表滚动时 delegate 被无意义重建。如果只写 return true,滚动过程中的每一帧都会重新构建所有 header,26 个分组就会产生 26 次额外 build。
3.2 列表主体:SliverList、SliverFixedExtentList 和 prototypeItem 的差别
列表主体有三种写法,性能差异明显。
SliverList 最通用,delegate 里的 builder 会被逐个调用,每个子项都会独立测量尺寸。好处是支持动态高度,坏处是滚动到任意位置时,Sliver 需要从当前分组头开始逐个测量每个 child 的偏移,直到找到可视区起点。数据少没感觉,几千行联系人时会有明显卡顿。
SliverFixedExtentList 要求每个 item 高度固定,代码里通过 itemExtent 声明。它计算偏移不需要测量:滚动偏移除以固定行高,整数除法就能直接定位到可视区起始 index,构建数量被严格限制在可视区加 cacheExtent 范围内。通讯录联系人行高统一,首选这个。
SliverPrototypeExtentList 是折中方案:传一个 prototype item,列表会拿它测量一次,之后所有 item 都沿用这个高度。适合行高固定但你不确定具体数值(比如有副标题、状态标签)的场景。代价是第一次布局多一次测量,后面就和 fixed extent 一样快。
我在 Demo 里用 SliverFixedExtentList(itemExtent: 56)。联系人行是一个 56 高度、头像加两行文字的组件。固定行高这个决定,直接影响了第 3.3 节的偏移表能不能做成完全静态。
3.3 偏移表计算与跳转定位:预计算优先,ensureVisible 兜底
这是整篇文章的核心,也是“索引条跳准”的关键。问题定义很简单:点击字母 Z,列表要滚到 Z 组标题吸附顶部的位置。滚动距离是多少?
因为顶部搜索框固定在外部,CustomScrollView 里就是分组头和联系人的排列。每个分组的布局高度 = header 高度 30 + 联系人数量 * 行高 56。第 i 个分组 header 的滚动偏移 = 它前面所有分组的总高度。
dart复制List<double> buildGroupOffsets(List<ContactGroup> groups) {
final offsets = <double>[0];
double acc = 0;
for (var i = 0; i < groups.length - 1; i++) {
acc += groups[i].contacts.length * 56 + 30;
offsets.add(acc);
}
return offsets;
}
offsets[0] 是 0,也就是列表最顶部,A header 一开始就在顶部。B 组 header 的偏移是 A 组所有人的总高度加上 A header 高度。以此类推,Z 组 header 偏移是前面 25 组的累计高度。这组数据在数据加载完成后算一次,缓存起来,之后滚动、跳转都直接查表。
跳转代码:
dart复制void jumpToGroup(int groupIndex) {
final target = _groupOffsets[groupIndex].clamp(0.0, _scrollController.position.maxScrollExtent);
_scrollController.animateTo(
target,
duration: const Duration(milliseconds: 200),
curve: Curves.easeOutCubic,
);
}
注意 clamp 到 maxScrollExtent。iOS 的 BouncingScrollPhysics 允许 overscroll,但显示上不能越过列表末尾,否则最后一组会弹回来。
那如果业务里行高不固定怎么办?比如联系人姓名下面有时候有两行副标题。这时候静态偏移表会失准,我建议用 Scrollable.ensureVisible 兜底。给每个分组 header 加一个 GlobalKey,跳转时直接滚动到对应 header:
dart复制Future<void> jumpToGroup(GlobalKey key) async {
final ctx = key.currentContext;
if (ctx == null) return;
await Scrollable.ensureVisible(
ctx,
alignment: 0,
duration: const Duration(milliseconds: 200),
curve: Curves.easeOutCubic,
);
}
ensureVisible 会把目标组件对齐到视口顶部,但实测和 pinned header 配合时偶尔偏一个 header 高度,因为 pinned Sliver 的 paint 位置会被吸顶逻辑修正。如果跳转后偏差明显,需要做一次补偿:拿 header 当前的 viewport 偏移,和预期吸附位置比较,再微调一次滚动距离。我的原则是,能用固定行高就优先固定行高,静态偏移表在性能、准确度、可调试性上都吊打动态方案;动态高度属于“除非必要否则不要引入”的复杂度。
4. 字母索引条与滚动联动:从“能看”到“能用”
4.1 索引条布局与手势:26 个字母的命中判断
右侧字母索引条,本质是一个叠加在列表之上的 Column,每个字母宽 24、高 18。用 Positioned 放在 Stack 的右侧。
dart复制class AlphabetIndexBar extends StatelessWidget {
const AlphabetIndexBar({
super.key,
required this.letters,
required this.currentLetter,
required this.onSelect,
});
final List<String> letters;
final String currentLetter;
final ValueChanged<String> onSelect;
@override
Widget build(BuildContext context) {
return GestureDetector(
onPanDown: (d) => _handle(d.localPosition.dy),
onPanUpdate: (d) => _handle(d.localPosition.dy),
child: Container(
padding: const EdgeInsets.symmetric(horizontal: 4, vertical: 4),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
for (final letter in letters)
Container(
width: 24,
height: 18,
alignment: Alignment.center,
child: Text(
letter,
style: TextStyle(
fontSize: 11,
fontWeight: letter == currentLetter ? FontWeight.w700 : FontWeight.w400,
color: letter == currentLetter ? Colors.black : Colors.grey,
),
),
),
],
),
),
);
}
void _handle(double dy) {
final index = (dy / 18).floor().clamp(0, letters.length - 1);
onSelect(letters[index]);
}
}
我解释一下这里几个容易被忽视的细节。一是用 Column(mainAxisSize: MainAxisSize.min) 而不是 ListView,26 个字母总共 468 高,不需要滚动,用 ListView 反而会和父组件抢手势。二是手势用 localPosition.dy,这是相对 Column 左上角的坐标,直接除以每个字母的高度 18 取整就能得到 index,不需要换算屏幕坐标。三是 clamp(0, 25) 防止手指划出边界时越界。
当前字母的选中样式我在 build 里直接比较了 letter == currentLetter,这种写法简单,但滚动时如果父组件频繁 setState,这里会跟着重建。更好的做法在第 4.2 节讲。
4.2 当前字母回显:用 ValueListenableBuilder 代替全树 setState
回显的核心逻辑是:监听滚动偏移,找到当前偏移对应的分组字母。我把“滚动偏移 -> 分组 index”写成一个 O(log n) 的二分查找,因为 26 个组太少,线性遍历就够,用二分更通用。
dart复制int _groupIndexForOffset(double offset, List<double> offsets) {
var low = 0;
var high = offsets.length - 1;
while (low < high) {
final mid = (low + high + 1) >> 1;
if (offsets[mid] <= offset) {
low = mid;
} else {
high = mid - 1;
}
}
return low;
}
然后滚动监听里更新一个 ValueNotifier<String>,索引条和气泡组件用 ValueListenableBuilder 订阅它:
dart复制void _onScroll() {
final offset = _scrollController.offset;
final index = _groupIndexForOffset(offset, _groupOffsets);
if (_currentLetterNotifier.value != groupList[index].letter) {
_currentLetterNotifier.value = groupList[index].letter;
}
}
为什么不用 setState?因为滚动监听在每一帧都会触发,如果用 setState 刷新整棵树,右侧字母条、中央气泡、列表头都会被重建一遍,帧率必然受影响。ValueNotifier 会把刷新范围限制在真正关心这个值的组件里,实测下来对滚动手感影响很小。这是一个很值得推广的习惯:滚动类 UI 反馈,优先用 ValueListenable/Stream,而不是页面级 setState。
需要处理的一个边界:iOS 回弹模式下,offset 可能超过 maxScrollExtent,这时代码里 _groupIndexForOffset 会返回最后一组,正好对应“滑到列表末尾时索引条停在 Z”,符合直觉。但要注意 groupOffsets 必须包含最后一组,并且 offset 表最后一组的偏移通常远小于 maxScrollExtent,因为联系人列表末尾还有留白,不能拿欧米等值硬比。
4.3 中央字母气泡:补齐 iOS 手感的最后一块
光有右侧高亮还不够,iOS 通讯录拖动索引条时,屏幕中央会出现一个大号字母气泡,这是“当前正在哪一组”的最直观反馈。实现上就是 Stack 再叠一层,手势回调里更新气泡内容。
dart复制Stack(
children: [
_buildContactList(),
Positioned(
right: 8,
top: MediaQuery.of(context).size.height / 2 - 234,
child: AlphabetIndexBar(
letters: _letters,
currentLetter: _currentLetterNotifier.value,
onSelect: _onSelectLetter,
),
),
Center(
child: IgnorePointer(
child: AnimatedSwitcher(
duration: const Duration(milliseconds: 100),
child: _previewLetter == null
? const SizedBox.shrink()
: PreviewBubble(letter: _previewLetter!),
),
),
),
],
)
_onSelectLetter 里同时做三件事:更新预览字母、跳转滚动、启动一个 800ms 的定时器自动隐藏气泡。注意气泡外层必须包 IgnorePointer,否则拖动时中央气泡会挡住列表的手势。AnimatedSwitcher 让字母切换时有轻微淡入淡出,iOS 原生的气泡其实没有动画,但加上之后视觉上更跟手,不建议太快。
预览字母和 _currentLetter 是两回事:预览字母在你手指按压索引条期间一直显示,滚动回显的 currentLetter 是列表实际所在分组。两者可以短暂不同步(比如滚动动画还没结束),设计上要接受这个小延迟,不用强行对齐。
5. 长列表性能优化与工程化落地
5.1 固定行高为什么是“性能开关”
我建议所有做通讯录、好友列表、会员列表这种场景的人,一开始就把行高固定下来。SliverFixedExtentList 的布局逻辑是纯算术:已知滚动偏移和 itemExtent,可视区的起始 index 和结束 index 可以直接算出来,不需要逐个调用 child 的布局方法。移动端列表的卡顿大头就在“测量”这一步,固定行高直接把这个成本消掉了。
作为对比,SliverList 遇到 scroll offset 变化时,如果缓存区边缘还未确定的子项,需要重新从上往下测量若干个子项才能定位。当你有 5000 行,每次滚动几十像素都要做这种“重新确认”是很亏的。cacheExtent 默认 250 只能缓解,不能根治。所以即便行高需要后期统一调整,也建议用一个常量管理,不要由每个行组件内部自己决定高度。这样后期改行距,改一处常量,偏移表自动跟着变。
5.2 数据层预计算与最小化重建
性能优化不能只看渲染层。数据侧的最佳实践是:进入页面时一次完成分组、排序、偏移表构建,之后原样复用。
分组不要在 build 里做。_buildGroupOffsets 在 initState 里算一次,存成 final。联系人对象尽量用不可变模型,List.unmodifiable 包一层,避免滚动过程中有人意外改数据引起 rebuild。行组件用 const 构造,能 const 就 const;行内如果有头像,给头像加 RepaintBoundary,避免整个列表区域在滚动时反复重绘。实际项目里我见过一个 800 行的通讯录,只做这三步,Profiler 里帧耗时从 22ms 降到 8ms,滚动后明显跟手。
还有一个隐藏优化点:AlphabetIndexBar 是 26 个字母的小组件,但它的 currentLetter 变化频繁。如果它被某个父组件包着,父组件 rebuild 时它也会跟着 rebuild。解决办法就是第 4.2 节的 ValueListenableBuilder,让字母条只依赖 notifier 而不依赖父组件状态。这类“局部可刷新”的设计,在滚动手感调优里比任何微优化都重要。
6. 实操踩坑记录:这 5 个坑我建议你提前绕开
6.1 索引条跳转后被顶栏遮住
我第一次实现时,顶部搜索框放在 CustomScrollView 的 SliverAppBar 里,偏移表还按“从 CustomScrollView 顶部算起”的方式计算,结果点 Z 跳过去,Z header 被固定搜索框挡掉一截。原因很简单:偏移表是相对 CustomScrollView 视口的坐标,而视口可能被外部固定组件或者 pinned appbar 占用。
解决有两种。如果搜索框固定外部,CustomScrollView 的视口本来就是从搜索框下方开始的,偏移表不需要额外补偿。如果搜索框是 SliverAppBar pinned,偏移表要在每个分组偏移量上统一加 appbar 的当前高度。越是混合布局,越容易栽在这种“坐标系不一致”上。我的经验是:先画清楚“谁占用了顶部空间”,再确定偏移表基准。
6.2 固定行高和真实高度不一致导致内容被挤压
SliverFixedExtentList 会把所有行强制放到 itemExtent 高度。如果行组件实际内容超过这个高度,会出现文字截断或溢出。我踩过的一个坑是:行内用了上下两个 Text,加上头像和内边距,实际总高 58,我设了 56,结果副标题被裁掉。
改动建议:要么统一行高到 58 并同步偏移表,要么改用 SliverPrototypeExtentList 让列表拿 prototype 实测一次。记住一个原则:一旦用了固定行高,所有行都必须严格遵守这个高度,包括内边距、字体行高、分割线。任何一行“偷偷长高”,都会让偏移表从那一行开始全部错位。
6.3 连续拖动触发多个滚动动画导致回摆
索引条拖动时 _onSelectLetter 每触发一次就 animateTo 一次,Flutter 里新的 animateTo 会打断上一个动画。手指快速划过 A 到 Z 时,列表会来回抽搐、最终停在奇怪的位置。
后来改成:拖动手势期间不要 animateTo,用 jumpTo 直接瞬移;手势结束后的那一下再给一个短动画,增强“松手滑到目标”的舒适感。操作上可以加一个 _isDraggingIndex 标志,onPanDown 置 true 用 jumpTo,onPanEnd 置 false 后结合当前字母和距离决定是否补一段动画。这段我在生产项目里验证过,手指按压索引条时列表跟着手走,松手时的线性动画由 180ms 的 easeOut 完成,手感和 iOS 已经非常接近。
6.4 系统 Scrollbar 和自绘索引条打架
iOS 上 Mobile 平台的 Scrollbar 默认不显示,但如果你在 Android 或模拟器上跑,Scaffold 自带 Scrollbar 会出现在右侧。自绘字母索引条又占着右侧,两个 UI 叠在一起,视觉上很乱。
处理方式是:CustomScrollView 不用包 Scrollbar,索引条本身就是滚动反馈;如果产品要求保留系统滚动条(比如在 Android 上更习惯有滚动条),给 Scrollbar 传 thumbVisibility: false,保留拖动功能但隐藏滑块。自绘索引条和系统条二选一即可。
6.5 BouncingScrollPhysics 边缘处字母回显错位
iOS 默认的 BouncingScrollPhysics 允许列表滚到边界后继续回弹。回弹时 offset 会短暂小于 0 或大于 maxScrollExtent。如果 _groupIndexForOffset 不做 clamp,回弹到顶部时 offset 是负数,二分会返回第 0 组,这倒没问题;问题出在回弹到底部,offset 可能比最后一组的偏移表值大得多,此时如果 offset 表里没有覆盖“最后留白区”,高亮会停在倒数第二组。
解决就是前面讲过的 clamp:偏移表的最后一个值故意设为 double.infinity 或者把 maxScrollExtent 作为兜底,让回弹到底部时高亮稳定停在 Z。这个小细节不处理,用户快速滚到列表末尾时会看到索引条高亮突然跳到别的字母,特别破坏质感。
这套方案后来我在几个生产项目里反复用,效果都挺稳。如果你也要在 App 里做字母索引导航,记住一个原则:先定行高,再算偏移,最后才做动画。行高不固定时优先 ensureVisible 方案,但要做好跳转补偿。下一期我打算把搜索框、过滤结果和滚动定位三件事串起来,做一个完整的通讯录搜索体验,到时候见。
