记录一篇 Flutter 学习日记——PageView 加 Indicator 做引导页。这个组合几乎每个做客户端的开发者都会碰到尤其是新人入职第一周大概率会被安排把引导页做了这种需求。对于 Flutter 新手来说它也是绕过不去的第一个带点交互的练手项目逻辑不复杂但涉及滑动监听、状态管理、动画过渡、页面生命周期甚至首次启动的存储判断一套做下来基本就把入门期最常用的几个能力点串起来了。这篇文章我不会只贴代码而是把思路、原理、踩坑、优化方向都写清楚。无论你是刚接触 Flutter 的初学者还是带新人的老手我希望这篇日记里记录的细节能让你少走几步弯路。1. 引导页需求分析与整体设计思路1.1 引导页在 App 里的地位以及常见的三种形态很多产品经理会把引导页当作新用户的第一印象来做设计上极其讲究但落到开发头上它其实就是一个横向翻页的容器。先别急着写代码先把引导页的形态搞清楚。我见到的引导页大概分三类功能亮点展示型每页一张图、一句主文案、一句副文案交代我是谁、我能干嘛。大多数工具类 App 选这种干净、克制3 到 4 页结束。品牌故事型类似故事板用大图和节奏感强的文案带出调性适合偏内容或品牌向的产品。权限说明型逐页引导用户开启通知、定位、相册权限合规压力大的场景常用。无论哪种形态交互骨架是同一个左右滑动切换页面底部或顶部有一组指示器Indicator最后一页露出立即体验 / 开始使用之类的入口按钮。1.2 为什么引导页要用 PageView而不是横向 ListView新手最容易问的问题之一既然只是几个页面横着滑为什么不能用 ListView 加 scrollDirection: Axis.horizontal能用但属于能用和好用的差别。PageView 的定位就是多页面的翻页容器它在设计上专门为整页切换这一场景做了优化自带整页吸附效果。PageView 的 pageSnapping 默认开启松手后自动对齐到最近的整页不会出现停在半页的尴尬情况。提供 PageController可以编程式控制跳页。跳转到指定页、翻到下一页、带动画回首页全靠它。有 onPageChanged 回调页面切换完成后能拿到当前页码这是 Indicator 同步的命脉。对相邻页面的预加载和缓存策略更成熟尤其是后续要做无限轮播或嵌套滚动时PageView 的扩展性远好于 ListView。ListView 横向滚动适合一长条内容滑来滑去比如横向标签列表、商品推荐栏而 PageView 适合固定几页、逐页切换、每页一屏的场景。引导页正好落在这个场景里。1.3 指示器方案选型静态圆点、动态伸缩圆点、进度条、数字式指示器是引导页的点睛之笔方案很多开发前最好和设计对一下想要哪种免得返工。我列个对比表方案实现难度视觉质感适用场景静态圆点最低一般胜在简单需求急、页数少、对质感要求不高的场景动态伸缩圆点中好过渡自然当前页突出绝大多数产品默认选择强烈推荐横线进度条低简洁但和产品调性匹配度看设计工具型 App、偏简洁风格数字式1/3极低弱但有特殊的克制感极简设计或页面底部已有较多元素时我后面给的代码示例会直接从动态伸缩圆点这个方案入手。理由是它比纯静态圆点只多了一个 AnimatedContainer 的成本但视觉效果直接提升一个档次。2. 核心细节解析PageView 与 Indicator 的原理拆解2.1 PageController 的几个关键参数以及它们各自干什么PageController 是整个 PageView 的控制中枢给 PageView 传 controller 之后你就可以通过它操作翻页。几个高频参数一定要吃透initialPage初始化时显示第几页默认 0。keepPage默认 true作用是保存当前页面位置。比如引导页做到第 3 页用户切后台再回来一般还是停留在第 3 页。如果你希望每次进来都从第 1 页开始那就把 keepPage 设为 false。viewportFraction这个参数很值得玩味。默认 1 表示每页填满整个视口改成 0.8 的话当前页会露出左右相邻页的一部分边缘形成卡片叠放的效果。做那种偏 iOS 风格的卡片引导页时这个参数就派上用场了。PageController(viewportFraction: 0.85) 配合 Padding可以做出 DaisyUI 风格的交错卡片效果引导页不一定要千篇一律这个思路可以留给后续优化。再补充一个对新手比较关键的逻辑PageController 只是控制去哪一页但它本身不通知你当前在第几页。想知道当前页码必须靠 PageView 的 onPageChanged 回调。明白了这一点你就理解了为什么很多人写引导页时Indicator 死活不同步——因为只写了 controller没写 onPageChanged。2.2 onPageChanged 的触发机制和 setState 的联动时机onPageChanged 回调的签名是 ValueChanged 页面切换动画走完、当前页码确定后会回调一次。有一个细节值得注意onPageChanged 不会在拖动过程中不断触发它只在翻页完成后触发。也就是说用户滑动到一半停在半页位置指示器不会跟着动松手后吸附到某一页onPageChanged 才把最终页码告诉你。所以你直接用 onPageChanged 里的 index 去 setState得到的指示器是跳变式更新的。这也是动态圆点指示器为什么用 AnimatedContainer 的原因——外部索引是跳变的但圆点的尺寸和颜色变化可以靠动画过渡平滑一下弥补跳变造成的生硬感。具体写法我后面会给出完整代码。这里先记住一个结论指示器的当前页状态只依赖 onPageChanged 回调里的 index。不要自作聪明去监听 ScrollController 算偏移量除非你要做滑动跟手式的复杂指示器那是另一个量级的活。2.3 指示器为什么要让当前页和其余页有明显差异指示器存在的意义是让用户一眼就知道自己在第几页、一共几页、往前还是往后。这三点缺一个用户就会迷路。所以指示器设计的第一原则是当前状态突出。实现上常见两种颜色变化当前页圆点用主题色其余页用灰色。最基础、代码最少。尺寸/形状变化当前页圆点拉长成胶囊形其余页保持小圆点。代码略多但视觉引导更强。第二种方案在视觉上更贵是有原因的人眼对形状和大小的识别比对颜色的识别更快拉长当前页圆点用户余光就能判断当前位置不需要仔细去分辨颜色差异。另外补充一个细节指示器圆点数量的变化不要做动态增删。哪怕只有 2 页也建议先用固定数量的圆点显示通过改变当前圆点样式来切换状态。动态增删圆点会导致布局抖动得不偿失。3. 实操过程从零实现一个完整引导页3.1 项目准备与页面结构规划先新建一个 Flutter 项目这一步没什么好说的。引导页本身不需要额外的第三方库核心全是 Flutter 自带的 Widget。不过如果你要做到应用首次启动显示引导页之后不再显示就需要引入 shared_preferences 这个存储插件来做本地标记。我放在进阶优化部分讲基础版本先不引入。页面结构我建议这样组织一个 StatefulWidget 作为引导页容器。在 build 里用一个 Stack 叠放三层最底层是 PageView中间是底部信息区指示器 按钮最顶层可以放一个跳过按钮。PageView 的 children 用一组自定义的 GuideItem 数据模型来生成方便后续增删页面。之所以用 Stack而不是把 PageView 塞进 Column是因为 PageView 需要撑满全屏做滑动区域而指示器、按钮是叠在页面内容之上的浮层。用 Stack 最直观也不容易出现布局冲突。3.2 数据模型与页面 Item 组件引导页的内容无非是图片、标题、副标题、背景颜色或背景图所以先定义一个简单的数据模型class GuideItem { final String imagePath; final String title; final String subtitle; final Color bgColor; const GuideItem({ required this.imagePath, required this.title, required this.subtitle, required this.bgColor, }); }接着定义一个页面子组件 GuideItemView它只负责渲染单页内容class GuideItemView extends StatelessWidget { final GuideItem item; const GuideItemView({super.key, required this.item}); override Widget build(BuildContext context) { return Container( color: item.bgColor, child: SafeArea( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ // 实际项目中这里建议用 Image.asset 或 Image.network Container( width: 200, height: 200, color: Colors.white.withOpacity(0.3), child: const Icon(Icons.image_outlined, size: 80, color: Colors.white), ), const SizedBox(height: 40), Text( item.title, style: const TextStyle( fontSize: 28, fontWeight: FontWeight.bold, color: Colors.white, ), ), const SizedBox(height: 16), Padding( padding: const EdgeInsets.symmetric(horizontal: 32), child: Text( item.subtitle, textAlign: TextAlign.center, style: TextStyle( fontSize: 16, height: 1.5, color: Colors.white.withOpacity(0.85), ), ), ), ], ), ), ); } }这个组件划分的意义在于引导页容器只需要关心有几个页面、当前页码、如何切换单页的长什么样完全解耦。后面你要把单页改成带 Lottie 动画、带视频、带插画都只改 GuideItemView容器一行不用动。3.3 PageView 核心代码实现接下来是容器核心。我先给出一个最朴素的版本这个版本已经能实现滑动翻页 指示器跟随class GuidePage extends StatefulWidget { const GuidePage({super.key}); override StateGuidePage createState() _GuidePageState(); } class _GuidePageState extends StateGuidePage { final PageController _pageController PageController(); int _currentIndex 0; final ListGuideItem _items [ GuideItem( imagePath: assets/guide1.png, title: 欢迎使用某某应用, subtitle: 这是一段副标题文案简单介绍产品亮点。, bgColor: const Color(0xFF4A90D9), ), GuideItem( imagePath: assets/guide2.png, title: 快速上手, subtitle: 简洁的操作流程三步完成核心任务。, bgColor: const Color(0xFF5D5FEF), ), GuideItem( imagePath: assets/guide3.png, title: 一切尽在掌握, subtitle: 重要信息一目了然不错过每一个细节。, bgColor: const Color(0xFF50B8C0), ), ]; override void dispose() { _pageController.dispose(); super.dispose(); } override Widget build(BuildContext context) { return Scaffold( body: Stack( children: [ PageView.builder( controller: _pageController, itemCount: _items.length, onPageChanged: (index) { setState(() { _currentIndex index; }); }, itemBuilder: (context, index) { return GuideItemView(item: _items[index]); }, ), // 底部的指示器和按钮 Positioned( left: 0, right: 0, bottom: 80, child: Column( children: [ _buildIndicator(), const SizedBox(height: 32), _buildBottomButton(), ], ), ), // 右上角跳过按钮 Positioned( top: MediaQuery.of(context).padding.top 16, right: 24, child: GestureDetector( onTap: () { // 跳转首页逻辑先留空 }, child: const Text( 跳过, style: TextStyle(color: Colors.white, fontSize: 16), ), ), ), ], ), ); } }这里有几个地方展开说一下。PageView.builder 和 PageView(children: [...]) 的区别数据量小时两者没有本质差别但 builder 是懒加载的只有页面真正需要显示时才构建。引导页虽然只有三四页但养成用 builder 的习惯是好的后面遇到长列表场景你会感谢这个肌肉记忆。dispose 里释放 PageController这个一定要写。控制器的生命周期和页面绑定不释放会在开发者工具里看到内存泄漏警告。跳过按钮放在 Positioned MediaQuery padding 的处理方式是为了适配 iPhone 的刘海屏和 Android 的状态栏。用 SafeArea 包裹是一种更优雅的方案但 SafeArea 在某些自定义背景色的页面里可能出现顶部空白带颜色不一致的问题这就是为什么我保留了 MediaQuery 手动取 padding 的写法。3.4 静态指示器先跑通再升级成动态指示器指示器最初我建议先写静态的因为逻辑简单、容易排查问题Widget _buildIndicator() { return Row( mainAxisAlignment: MainAxisAlignment.center, children: List.generate(_items.length, (index) { bool isActive index _currentIndex; return AnimatedContainer( duration: const Duration(milliseconds: 300), curve: Curves.easeInOut, margin: const EdgeInsets.symmetric(horizontal: 4), width: isActive ? 24 : 8, height: 8, decoration: BoxDecoration( color: isActive ? Colors.white : Colors.white.withOpacity(0.5), borderRadius: BorderRadius.circular(4), ), ); }), ); }是的你看到的已经是 AnimatedContainer 版本而静态圆点和它的唯一区别就是去掉 duration 和 curve再把宽高写死成 8、8。第一次写的时候先用静态的跑通然后再把 AnimatedContainer 换上你会更清楚动画加在哪个属性上。动画生效的本质是AnimatedContainer 在 width 从 8 变成 24 时自动补齐中间过渡帧持续 300 毫秒。颜色同理。这里有一个细节AnimatedContainer 的动画只在属性变化时触发。如果你当前页的圆点宽度一直是 24那么从第 0 页滑到第 1 页第 0 页的圆点从 24 变回 8第 1 页的圆点从 8 变成 24两个圆点各自执行动画视觉上就形成了滑块从左滚到右的连贯效果。3.5 最后一页的立即体验按钮引导页最后一页通常会有一个主行动按钮CTA。实现逻辑不复杂根据 _currentIndex _items.length - 1 判断是否显示。但直接判断会导致一个体验问题按钮在最后一页突然出现。更好的做法是加一个淡入淡出动画让按钮从透明渐变出现。最简单的实现是 Opacity AnimatedOpacityWidget _buildBottomButton() { bool isLastPage _currentIndex _items.length - 1; return AnimatedOpacity( duration: const Duration(milliseconds: 300), opacity: isLastPage ? 1 : 0, child: IgnorePointer( ignoring: !isLastPage, child: ElevatedButton( onPressed: () { // 跳转首页 }, style: ElevatedButton.styleFrom( backgroundColor: Colors.white, foregroundColor: const Color(0xFF4A90D9), padding: const EdgeInsets.symmetric(horizontal: 40, vertical: 14), shape: RoundedRectangleBorder( borderRadius: BorderRadius.circular(24), ), ), child: const Text(立即体验, style: TextStyle(fontSize: 16)), ), ), ); }这里 IgnorePointer 的用途必须重点讲一下。如果不加它即使用 AnimatedOpacity 把按钮的透明度降到了 0按钮仍然占据布局空间、仍然能接收点击。用户在前几页时虽然看不到按钮但如果在按钮位置乱点可能就触发了不该有的跳转。IgnorePointer 可以把不可见和不可交互绑定起来。同样的道理也可以用在跳过按钮上。如果产品要求第 1 页不允许跳过那我们就把跳过按钮的透明度也做成跟随页码变化。到这里一个基础版引导页已经能跑了。但距离生产可用还差临门一脚首次启动判定、封装复用、适配问题。我们继续往后看。4. 进阶优化让引导页更接近生产级4.1 接入 shared_preferences 做首次启动判定现实中几乎没有 App 会每次启动都展示引导页所以你需要一个本地标记位记录用户是否已经看过引导页。我用的方案是 shared_preferences一个非常轻量的本地 key-value 存储插件。核心代码就两步// 判断是否首次启动 Futurebool isFirstLaunch() async { SharedPreferences prefs await SharedPreferences.getInstance(); bool isFirst prefs.getBool(already_launched) ?? true; return isFirst; } // 标记已启动 Futurevoid markLaunched() async { SharedPreferences prefs await SharedPreferences.getInstance(); await prefs.setBool(already_launched, false); }在 App 入口处根据这个标记决定是进入引导页还是直接进入首页void main() { WidgetsFlutterBinding.ensureInitialized(); runApp(const MyApp()); } class MyApp extends StatelessWidget { override Widget build(BuildContext context) { return MaterialApp( home: const SplashPage(), ); } }SplashPage 负责在启动时做异步判断。我建议用 FutureBuilder 或者一个 StatefulWidget 的 initState 里做这个活class SplashPage extends StatefulWidget { const SplashPage({super.key}); override StateSplashPage createState() _SplashPageState(); } class _SplashPageState extends StateSplashPage { override void initState() { super.initState(); _checkFirstLaunch(); } Futurevoid _checkFirstLaunch() async { SharedPreferences prefs await SharedPreferences.getInstance(); bool isFirst prefs.getBool(already_launched) ?? true; if (!mounted) return; if (isFirst) { await prefs.setBool(already_launched, false); Navigator.pushReplacement( context, MaterialPageRoute(builder: (context) const GuidePage()), ); } else { Navigator.pushReplacement( context, MaterialPageRoute(builder: (context) const HomePage()), ); } } override Widget build(BuildContext context) { return const Scaffold( body: Center(child: CircularProgressIndicator()), ); } }两个细节值得注意Navigator.pushReplacement 而不是 push是为了把 SplashPage 从栈里移除避免用户按返回键退回启动页。同理引导页跳首页也应该用 pushReplacement。异步回调里一定要做 mounted 检查。因为 await 之后的上下文可能已经不是原来的页面了直接使用 context 会触发 Flutter 的 lint 警告表现是在异步函数中使用了 BuildContext。4.2 把引导页封装成可复用组件你可能会遇到第二种需求不同产品线的引导页 UI 完全不一样但交互逻辑一致。这时最省事的做法是做个引导容器组件接收外部传入的页面列表和完成回调class GuideScaffold extends StatefulWidget { final ListWidget pages; final VoidCallback onFinished; final Widget Function(BuildContext context)? skipBuilder; const GuideScaffold({ super.key, required this.pages, required this.onFinished, this.skipBuilder, }); override StateGuideScaffold createState() _GuideScaffoldState(); }容器内部负责 PageView、指示器、按钮、动画外部只需往里塞页面组件相当于把骨架和内容彻底分离。这样做的好处是以后换个风格的项目页面组件直接换交互逻辑不用重写。不过我提醒一句封装要有度。引导页这种轻量场景过度设计反而让新人看不懂。我的建议是先按本文 3.3 节的写法写一个具体页面跑通之后你觉得确实需要复用再抽 GuideScaffold。4.3 横竖屏适配与安全区域引导页通常限制竖屏但如果产品没锁方向你需要考虑横屏的情况。竖屏假设下GuideItemView 里的 Column 用 MainAxisAlignment.center 就挺稳妥。但横屏后屏幕高度变小内容容易溢出报RenderFlex overflowed的错。最粗暴的解法是在单页内容外包一层 SingleChildScrollView这样无论屏幕多矮用户都可以上下滚动看全内容。如果你用的是 Stack 布局还要注意 bottom 定位的指示器区域。横屏时底部空间变小把指示器固定在 bottom: 80 可能出现按钮被裁切的问题。我一般建议把指示器和按钮放进 SafeArea 里再给一个 minimum 的 bottom 距离。还有一个画龙点睛的细节横屏时 PageView 默认的 viewportFraction 为 1 是没问题的但如果你设置了卡片效果比如 0.85横屏时相邻页露出的部分过多可能影响视觉重心需要专门处理。5. 常见问题与排查技巧实录5.1 指示器不更新或者乱跳现象滑动到第 2 页指示器还停在第一个圆点。排查步骤检查 onPageChanged 有没有被调用。可以在回调里加个 print(page changed: $index)如果滑动后打印了说明回调正常。检查 onPageChanged 里是否调用了 setState。没有 setStateUI 不会重新构建自然不更新。检查 _currentIndex 是否真的变成了 index。注意别写反成 index _currentIndex这种低级错误最容易在敲代码时手滑。如果指示器乱跳多半是圆点的 key 没有稳定标识。当 List.generate 里的圆点数量不变时不明显一旦后续改成动态增删乱跳就出现了。解决方法是给圆点加 ValueKey(dot_$index)让 Flutter 在 diff 时能准确识别每个圆点。5.2 PageView 左右滑不动三个常见原因PageView 外面套了横向滑动的父组件比如水平 ListView 或 SingleChildScrollView滑动冲突。给 PageView 包一层时注意横向滚动手势会互相竞争。最简单的规避方式主容器用 Column/Stack不要用横向滚动容器。width 被限制成 0 或非常小。检查 PageView 是否在 Column 里没有展开宽度。Column 默认是交叉轴居中的PageView 需要占满宽度得在 Column 里用 SizedBox 指定宽高或者干脆用 Stack 全屏定位。PageView 本身没有撑满可用区域。它需要一个确定的视口尺寸如果父容器高度不明确渲染会异常。用 Expanded 或明确的高度都能解决。5.3 最后一页的按钮点不了原因往往是按钮被某个 Widget 遮住了。Stack 的层级是后写的在上面如果你把底部的 Column 写在 PageView 之前按钮就会被 PageView 盖住。还有一种隐蔽情况按钮确实在最上层但被 IgnorePointer 拦截了。检查一下 AnimatedOpacity 的 opacity 是否真的为 1以及 IgnorePointer 的 ignoring 是否误设为 true。我再分享一个调试技巧在 Stack 里临时给各个子组件加不同的背景色一眼就能看出谁盖谁。排查完再把颜色去掉比肉眼盯着代码猜测快得多。5.4 从首页返回时又弹回引导页这是路由栈的问题。典型场景引导页跳首页用了 Navigator.push首页按返回键又回到引导页。解法就是前面提到的跳转时必须用 pushReplacement把引导页从栈中移除。如果你有更复杂的路由配置比如用命名路由也要确保引导页登台后不留在历史栈里。5.5 页面滑动动画被中断导致指示器停滞PageView 默认的吸附动画时长很短如果用户快速滑了几页onPageChanged 的触达时机可能让指示器动画显得滞后。一个补救方案给 AnimatedContainer 的 duration 设置 250ms 到 350ms 之间同时在 onPageChanged 里加一个 if (index 0 index _items.length) 的边界判断。这样可以防止极端情况下 index 越界导致数组访问异常。5.6 性能与构建优化图片别用大图直接用新手最容易踩的坑是在引导页里直接塞 1080p 甚至更高分辨率的大图。三个页面每个 3MB启动时全部加载轻则白屏重则掉帧卡顿。生产级的处理方式图片压缩。WebP 格式优先单张控制在 200KB 以内。使用 precacheImage 在进入引导页之前预加载第一页图片避免首帧空白。如果用的是网络图记得配置缓存策略别每次都从头拉。我在实际项目里测过同样一套引导页优化前后首帧渲染时间差距甚至能到一倍。图片体积这个点设计提图时就要盯好别等上线了再来优化。写在最后的一点体会Flutter 的引导页说难不难说简单也不简单。难的地方不在 PageView 和 Indicator 本身而在你要以产品思维去理解一个入口页面——用户第一次打开 App 的几秒钟页面滑得顺不顺、指示器跟不跟手、按钮时机对不对都会直接影响他对产品质感的第一判断。我个人做这个功能的心得是先把交互层级拆开页面、控制器、指示器、按钮各司其职再用最小代码把链路跑通最后再加动画和存储逻辑。不要一上来就把 AnimatedContainer、shared_preferences、路由跳转全糊在一坨代码里那样出了问题反而特别难排查。最后分享一个小习惯我会在实现完引导页之后把 PageView 的源码翻出来看一眼重点看 PageController 的 animateToPage 和 onPageChanged 是在什么时机调起来的。Flutter 这种组件即文档的框架源码就是最好的学习资料。看完之后你对 PageView 的掌控感和上手其他滑动物件的能力都会上一个台阶。 
长河君 · 2026/10/18 17:07:14 · 阅读 1.2k Flutter引导页开发实战：PageView与Indicator核心原理与踩坑记录
记录一篇 Flutter 学习日记——PageView 加 Indicator 做引导页。这个组合几乎每个做客户端的开发者都会碰到尤其是新人入职第一周大概率会被安排把引导页做了这种需求。对于 Flutter 新手来说它也是绕过不去的第一个带点交互的练手项目逻辑不复杂但涉及滑动监听、状态管理、动画过渡、页面生命周期甚至首次启动的存储判断一套做下来基本就把入门期最常用的几个能力点串起来了。这篇文章我不会只贴代码而是把思路、原理、踩坑、优化方向都写清楚。无论你是刚接触 Flutter 的初学者还是带新人的老手我希望这篇日记里记录的细节能让你少走几步弯路。1. 引导页需求分析与整体设计思路1.1 引导页在 App 里的地位以及常见的三种形态很多产品经理会把引导页当作新用户的第一印象来做设计上极其讲究但落到开发头上它其实就是一个横向翻页的容器。先别急着写代码先把引导页的形态搞清楚。我见到的引导页大概分三类功能亮点展示型每页一张图、一句主文案、一句副文案交代我是谁、我能干嘛。大多数工具类 App 选这种干净、克制3 到 4 页结束。品牌故事型类似故事板用大图和节奏感强的文案带出调性适合偏内容或品牌向的产品。权限说明型逐页引导用户开启通知、定位、相册权限合规压力大的场景常用。无论哪种形态交互骨架是同一个左右滑动切换页面底部或顶部有一组指示器Indicator最后一页露出立即体验 / 开始使用之类的入口按钮。1.2 为什么引导页要用 PageView而不是横向 ListView新手最容易问的问题之一既然只是几个页面横着滑为什么不能用 ListView 加 scrollDirection: Axis.horizontal能用但属于能用和好用的差别。PageView 的定位就是多页面的翻页容器它在设计上专门为整页切换这一场景做了优化自带整页吸附效果。PageView 的 pageSnapping 默认开启松手后自动对齐到最近的整页不会出现停在半页的尴尬情况。提供 PageController可以编程式控制跳页。跳转到指定页、翻到下一页、带动画回首页全靠它。有 onPageChanged 回调页面切换完成后能拿到当前页码这是 Indicator 同步的命脉。对相邻页面的预加载和缓存策略更成熟尤其是后续要做无限轮播或嵌套滚动时PageView 的扩展性远好于 ListView。ListView 横向滚动适合一长条内容滑来滑去比如横向标签列表、商品推荐栏而 PageView 适合固定几页、逐页切换、每页一屏的场景。引导页正好落在这个场景里。1.3 指示器方案选型静态圆点、动态伸缩圆点、进度条、数字式指示器是引导页的点睛之笔方案很多开发前最好和设计对一下想要哪种免得返工。我列个对比表方案实现难度视觉质感适用场景静态圆点最低一般胜在简单需求急、页数少、对质感要求不高的场景动态伸缩圆点中好过渡自然当前页突出绝大多数产品默认选择强烈推荐横线进度条低简洁但和产品调性匹配度看设计工具型 App、偏简洁风格数字式1/3极低弱但有特殊的克制感极简设计或页面底部已有较多元素时我后面给的代码示例会直接从动态伸缩圆点这个方案入手。理由是它比纯静态圆点只多了一个 AnimatedContainer 的成本但视觉效果直接提升一个档次。2. 核心细节解析PageView 与 Indicator 的原理拆解2.1 PageController 的几个关键参数以及它们各自干什么PageController 是整个 PageView 的控制中枢给 PageView 传 controller 之后你就可以通过它操作翻页。几个高频参数一定要吃透initialPage初始化时显示第几页默认 0。keepPage默认 true作用是保存当前页面位置。比如引导页做到第 3 页用户切后台再回来一般还是停留在第 3 页。如果你希望每次进来都从第 1 页开始那就把 keepPage 设为 false。viewportFraction这个参数很值得玩味。默认 1 表示每页填满整个视口改成 0.8 的话当前页会露出左右相邻页的一部分边缘形成卡片叠放的效果。做那种偏 iOS 风格的卡片引导页时这个参数就派上用场了。PageController(viewportFraction: 0.85) 配合 Padding可以做出 DaisyUI 风格的交错卡片效果引导页不一定要千篇一律这个思路可以留给后续优化。再补充一个对新手比较关键的逻辑PageController 只是控制去哪一页但它本身不通知你当前在第几页。想知道当前页码必须靠 PageView 的 onPageChanged 回调。明白了这一点你就理解了为什么很多人写引导页时Indicator 死活不同步——因为只写了 controller没写 onPageChanged。2.2 onPageChanged 的触发机制和 setState 的联动时机onPageChanged 回调的签名是 ValueChanged 页面切换动画走完、当前页码确定后会回调一次。有一个细节值得注意onPageChanged 不会在拖动过程中不断触发它只在翻页完成后触发。也就是说用户滑动到一半停在半页位置指示器不会跟着动松手后吸附到某一页onPageChanged 才把最终页码告诉你。所以你直接用 onPageChanged 里的 index 去 setState得到的指示器是跳变式更新的。这也是动态圆点指示器为什么用 AnimatedContainer 的原因——外部索引是跳变的但圆点的尺寸和颜色变化可以靠动画过渡平滑一下弥补跳变造成的生硬感。具体写法我后面会给出完整代码。这里先记住一个结论指示器的当前页状态只依赖 onPageChanged 回调里的 index。不要自作聪明去监听 ScrollController 算偏移量除非你要做滑动跟手式的复杂指示器那是另一个量级的活。2.3 指示器为什么要让当前页和其余页有明显差异指示器存在的意义是让用户一眼就知道自己在第几页、一共几页、往前还是往后。这三点缺一个用户就会迷路。所以指示器设计的第一原则是当前状态突出。实现上常见两种颜色变化当前页圆点用主题色其余页用灰色。最基础、代码最少。尺寸/形状变化当前页圆点拉长成胶囊形其余页保持小圆点。代码略多但视觉引导更强。第二种方案在视觉上更贵是有原因的人眼对形状和大小的识别比对颜色的识别更快拉长当前页圆点用户余光就能判断当前位置不需要仔细去分辨颜色差异。另外补充一个细节指示器圆点数量的变化不要做动态增删。哪怕只有 2 页也建议先用固定数量的圆点显示通过改变当前圆点样式来切换状态。动态增删圆点会导致布局抖动得不偿失。3. 实操过程从零实现一个完整引导页3.1 项目准备与页面结构规划先新建一个 Flutter 项目这一步没什么好说的。引导页本身不需要额外的第三方库核心全是 Flutter 自带的 Widget。不过如果你要做到应用首次启动显示引导页之后不再显示就需要引入 shared_preferences 这个存储插件来做本地标记。我放在进阶优化部分讲基础版本先不引入。页面结构我建议这样组织一个 StatefulWidget 作为引导页容器。在 build 里用一个 Stack 叠放三层最底层是 PageView中间是底部信息区指示器 按钮最顶层可以放一个跳过按钮。PageView 的 children 用一组自定义的 GuideItem 数据模型来生成方便后续增删页面。之所以用 Stack而不是把 PageView 塞进 Column是因为 PageView 需要撑满全屏做滑动区域而指示器、按钮是叠在页面内容之上的浮层。用 Stack 最直观也不容易出现布局冲突。3.2 数据模型与页面 Item 组件引导页的内容无非是图片、标题、副标题、背景颜色或背景图所以先定义一个简单的数据模型class GuideItem { final String imagePath; final String title; final String subtitle; final Color bgColor; const GuideItem({ required this.imagePath, required this.title, required this.subtitle, required this.bgColor, }); }接着定义一个页面子组件 GuideItemView它只负责渲染单页内容class GuideItemView extends StatelessWidget { final GuideItem item; const GuideItemView({super.key, required this.item}); override Widget build(BuildContext context) { return Container( color: item.bgColor, child: SafeArea( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ // 实际项目中这里建议用 Image.asset 或 Image.network Container( width: 200, height: 200, color: Colors.white.withOpacity(0.3), child: const Icon(Icons.image_outlined, size: 80, color: Colors.white), ), const SizedBox(height: 40), Text( item.title, style: const TextStyle( fontSize: 28, fontWeight: FontWeight.bold, color: Colors.white, ), ), const SizedBox(height: 16), Padding( padding: const EdgeInsets.symmetric(horizontal: 32), child: Text( item.subtitle, textAlign: TextAlign.center, style: TextStyle( fontSize: 16, height: 1.5, color: Colors.white.withOpacity(0.85), ), ), ), ], ), ), ); } }这个组件划分的意义在于引导页容器只需要关心有几个页面、当前页码、如何切换单页的长什么样完全解耦。后面你要把单页改成带 Lottie 动画、带视频、带插画都只改 GuideItemView容器一行不用动。3.3 PageView 核心代码实现接下来是容器核心。我先给出一个最朴素的版本这个版本已经能实现滑动翻页 指示器跟随class GuidePage extends StatefulWidget { const GuidePage({super.key}); override StateGuidePage createState() _GuidePageState(); } class _GuidePageState extends StateGuidePage { final PageController _pageController PageController(); int _currentIndex 0; final ListGuideItem _items [ GuideItem( imagePath: assets/guide1.png, title: 欢迎使用某某应用, subtitle: 这是一段副标题文案简单介绍产品亮点。, bgColor: const Color(0xFF4A90D9), ), GuideItem( imagePath: assets/guide2.png, title: 快速上手, subtitle: 简洁的操作流程三步完成核心任务。, bgColor: const Color(0xFF5D5FEF), ), GuideItem( imagePath: assets/guide3.png, title: 一切尽在掌握, subtitle: 重要信息一目了然不错过每一个细节。, bgColor: const Color(0xFF50B8C0), ), ]; override void dispose() { _pageController.dispose(); super.dispose(); } override Widget build(BuildContext context) { return Scaffold( body: Stack( children: [ PageView.builder( controller: _pageController, itemCount: _items.length, onPageChanged: (index) { setState(() { _currentIndex index; }); }, itemBuilder: (context, index) { return GuideItemView(item: _items[index]); }, ), // 底部的指示器和按钮 Positioned( left: 0, right: 0, bottom: 80, child: Column( children: [ _buildIndicator(), const SizedBox(height: 32), _buildBottomButton(), ], ), ), // 右上角跳过按钮 Positioned( top: MediaQuery.of(context).padding.top 16, right: 24, child: GestureDetector( onTap: () { // 跳转首页逻辑先留空 }, child: const Text( 跳过, style: TextStyle(color: Colors.white, fontSize: 16), ), ), ), ], ), ); } }这里有几个地方展开说一下。PageView.builder 和 PageView(children: [...]) 的区别数据量小时两者没有本质差别但 builder 是懒加载的只有页面真正需要显示时才构建。引导页虽然只有三四页但养成用 builder 的习惯是好的后面遇到长列表场景你会感谢这个肌肉记忆。dispose 里释放 PageController这个一定要写。控制器的生命周期和页面绑定不释放会在开发者工具里看到内存泄漏警告。跳过按钮放在 Positioned MediaQuery padding 的处理方式是为了适配 iPhone 的刘海屏和 Android 的状态栏。用 SafeArea 包裹是一种更优雅的方案但 SafeArea 在某些自定义背景色的页面里可能出现顶部空白带颜色不一致的问题这就是为什么我保留了 MediaQuery 手动取 padding 的写法。3.4 静态指示器先跑通再升级成动态指示器指示器最初我建议先写静态的因为逻辑简单、容易排查问题Widget _buildIndicator() { return Row( mainAxisAlignment: MainAxisAlignment.center, children: List.generate(_items.length, (index) { bool isActive index _currentIndex; return AnimatedContainer( duration: const Duration(milliseconds: 300), curve: Curves.easeInOut, margin: const EdgeInsets.symmetric(horizontal: 4), width: isActive ? 24 : 8, height: 8, decoration: BoxDecoration( color: isActive ? Colors.white : Colors.white.withOpacity(0.5), borderRadius: BorderRadius.circular(4), ), ); }), ); }是的你看到的已经是 AnimatedContainer 版本而静态圆点和它的唯一区别就是去掉 duration 和 curve再把宽高写死成 8、8。第一次写的时候先用静态的跑通然后再把 AnimatedContainer 换上你会更清楚动画加在哪个属性上。动画生效的本质是AnimatedContainer 在 width 从 8 变成 24 时自动补齐中间过渡帧持续 300 毫秒。颜色同理。这里有一个细节AnimatedContainer 的动画只在属性变化时触发。如果你当前页的圆点宽度一直是 24那么从第 0 页滑到第 1 页第 0 页的圆点从 24 变回 8第 1 页的圆点从 8 变成 24两个圆点各自执行动画视觉上就形成了滑块从左滚到右的连贯效果。3.5 最后一页的立即体验按钮引导页最后一页通常会有一个主行动按钮CTA。实现逻辑不复杂根据 _currentIndex _items.length - 1 判断是否显示。但直接判断会导致一个体验问题按钮在最后一页突然出现。更好的做法是加一个淡入淡出动画让按钮从透明渐变出现。最简单的实现是 Opacity AnimatedOpacityWidget _buildBottomButton() { bool isLastPage _currentIndex _items.length - 1; return AnimatedOpacity( duration: const Duration(milliseconds: 300), opacity: isLastPage ? 1 : 0, child: IgnorePointer( ignoring: !isLastPage, child: ElevatedButton( onPressed: () { // 跳转首页 }, style: ElevatedButton.styleFrom( backgroundColor: Colors.white, foregroundColor: const Color(0xFF4A90D9), padding: const EdgeInsets.symmetric(horizontal: 40, vertical: 14), shape: RoundedRectangleBorder( borderRadius: BorderRadius.circular(24), ), ), child: const Text(立即体验, style: TextStyle(fontSize: 16)), ), ), ); }这里 IgnorePointer 的用途必须重点讲一下。如果不加它即使用 AnimatedOpacity 把按钮的透明度降到了 0按钮仍然占据布局空间、仍然能接收点击。用户在前几页时虽然看不到按钮但如果在按钮位置乱点可能就触发了不该有的跳转。IgnorePointer 可以把不可见和不可交互绑定起来。同样的道理也可以用在跳过按钮上。如果产品要求第 1 页不允许跳过那我们就把跳过按钮的透明度也做成跟随页码变化。到这里一个基础版引导页已经能跑了。但距离生产可用还差临门一脚首次启动判定、封装复用、适配问题。我们继续往后看。4. 进阶优化让引导页更接近生产级4.1 接入 shared_preferences 做首次启动判定现实中几乎没有 App 会每次启动都展示引导页所以你需要一个本地标记位记录用户是否已经看过引导页。我用的方案是 shared_preferences一个非常轻量的本地 key-value 存储插件。核心代码就两步// 判断是否首次启动 Futurebool isFirstLaunch() async { SharedPreferences prefs await SharedPreferences.getInstance(); bool isFirst prefs.getBool(already_launched) ?? true; return isFirst; } // 标记已启动 Futurevoid markLaunched() async { SharedPreferences prefs await SharedPreferences.getInstance(); await prefs.setBool(already_launched, false); }在 App 入口处根据这个标记决定是进入引导页还是直接进入首页void main() { WidgetsFlutterBinding.ensureInitialized(); runApp(const MyApp()); } class MyApp extends StatelessWidget { override Widget build(BuildContext context) { return MaterialApp( home: const SplashPage(), ); } }SplashPage 负责在启动时做异步判断。我建议用 FutureBuilder 或者一个 StatefulWidget 的 initState 里做这个活class SplashPage extends StatefulWidget { const SplashPage({super.key}); override StateSplashPage createState() _SplashPageState(); } class _SplashPageState extends StateSplashPage { override void initState() { super.initState(); _checkFirstLaunch(); } Futurevoid _checkFirstLaunch() async { SharedPreferences prefs await SharedPreferences.getInstance(); bool isFirst prefs.getBool(already_launched) ?? true; if (!mounted) return; if (isFirst) { await prefs.setBool(already_launched, false); Navigator.pushReplacement( context, MaterialPageRoute(builder: (context) const GuidePage()), ); } else { Navigator.pushReplacement( context, MaterialPageRoute(builder: (context) const HomePage()), ); } } override Widget build(BuildContext context) { return const Scaffold( body: Center(child: CircularProgressIndicator()), ); } }两个细节值得注意Navigator.pushReplacement 而不是 push是为了把 SplashPage 从栈里移除避免用户按返回键退回启动页。同理引导页跳首页也应该用 pushReplacement。异步回调里一定要做 mounted 检查。因为 await 之后的上下文可能已经不是原来的页面了直接使用 context 会触发 Flutter 的 lint 警告表现是在异步函数中使用了 BuildContext。4.2 把引导页封装成可复用组件你可能会遇到第二种需求不同产品线的引导页 UI 完全不一样但交互逻辑一致。这时最省事的做法是做个引导容器组件接收外部传入的页面列表和完成回调class GuideScaffold extends StatefulWidget { final ListWidget pages; final VoidCallback onFinished; final Widget Function(BuildContext context)? skipBuilder; const GuideScaffold({ super.key, required this.pages, required this.onFinished, this.skipBuilder, }); override StateGuideScaffold createState() _GuideScaffoldState(); }容器内部负责 PageView、指示器、按钮、动画外部只需往里塞页面组件相当于把骨架和内容彻底分离。这样做的好处是以后换个风格的项目页面组件直接换交互逻辑不用重写。不过我提醒一句封装要有度。引导页这种轻量场景过度设计反而让新人看不懂。我的建议是先按本文 3.3 节的写法写一个具体页面跑通之后你觉得确实需要复用再抽 GuideScaffold。4.3 横竖屏适配与安全区域引导页通常限制竖屏但如果产品没锁方向你需要考虑横屏的情况。竖屏假设下GuideItemView 里的 Column 用 MainAxisAlignment.center 就挺稳妥。但横屏后屏幕高度变小内容容易溢出报RenderFlex overflowed的错。最粗暴的解法是在单页内容外包一层 SingleChildScrollView这样无论屏幕多矮用户都可以上下滚动看全内容。如果你用的是 Stack 布局还要注意 bottom 定位的指示器区域。横屏时底部空间变小把指示器固定在 bottom: 80 可能出现按钮被裁切的问题。我一般建议把指示器和按钮放进 SafeArea 里再给一个 minimum 的 bottom 距离。还有一个画龙点睛的细节横屏时 PageView 默认的 viewportFraction 为 1 是没问题的但如果你设置了卡片效果比如 0.85横屏时相邻页露出的部分过多可能影响视觉重心需要专门处理。5. 常见问题与排查技巧实录5.1 指示器不更新或者乱跳现象滑动到第 2 页指示器还停在第一个圆点。排查步骤检查 onPageChanged 有没有被调用。可以在回调里加个 print(page changed: $index)如果滑动后打印了说明回调正常。检查 onPageChanged 里是否调用了 setState。没有 setStateUI 不会重新构建自然不更新。检查 _currentIndex 是否真的变成了 index。注意别写反成 index _currentIndex这种低级错误最容易在敲代码时手滑。如果指示器乱跳多半是圆点的 key 没有稳定标识。当 List.generate 里的圆点数量不变时不明显一旦后续改成动态增删乱跳就出现了。解决方法是给圆点加 ValueKey(dot_$index)让 Flutter 在 diff 时能准确识别每个圆点。5.2 PageView 左右滑不动三个常见原因PageView 外面套了横向滑动的父组件比如水平 ListView 或 SingleChildScrollView滑动冲突。给 PageView 包一层时注意横向滚动手势会互相竞争。最简单的规避方式主容器用 Column/Stack不要用横向滚动容器。width 被限制成 0 或非常小。检查 PageView 是否在 Column 里没有展开宽度。Column 默认是交叉轴居中的PageView 需要占满宽度得在 Column 里用 SizedBox 指定宽高或者干脆用 Stack 全屏定位。PageView 本身没有撑满可用区域。它需要一个确定的视口尺寸如果父容器高度不明确渲染会异常。用 Expanded 或明确的高度都能解决。5.3 最后一页的按钮点不了原因往往是按钮被某个 Widget 遮住了。Stack 的层级是后写的在上面如果你把底部的 Column 写在 PageView 之前按钮就会被 PageView 盖住。还有一种隐蔽情况按钮确实在最上层但被 IgnorePointer 拦截了。检查一下 AnimatedOpacity 的 opacity 是否真的为 1以及 IgnorePointer 的 ignoring 是否误设为 true。我再分享一个调试技巧在 Stack 里临时给各个子组件加不同的背景色一眼就能看出谁盖谁。排查完再把颜色去掉比肉眼盯着代码猜测快得多。5.4 从首页返回时又弹回引导页这是路由栈的问题。典型场景引导页跳首页用了 Navigator.push首页按返回键又回到引导页。解法就是前面提到的跳转时必须用 pushReplacement把引导页从栈中移除。如果你有更复杂的路由配置比如用命名路由也要确保引导页登台后不留在历史栈里。5.5 页面滑动动画被中断导致指示器停滞PageView 默认的吸附动画时长很短如果用户快速滑了几页onPageChanged 的触达时机可能让指示器动画显得滞后。一个补救方案给 AnimatedContainer 的 duration 设置 250ms 到 350ms 之间同时在 onPageChanged 里加一个 if (index 0 index _items.length) 的边界判断。这样可以防止极端情况下 index 越界导致数组访问异常。5.6 性能与构建优化图片别用大图直接用新手最容易踩的坑是在引导页里直接塞 1080p 甚至更高分辨率的大图。三个页面每个 3MB启动时全部加载轻则白屏重则掉帧卡顿。生产级的处理方式图片压缩。WebP 格式优先单张控制在 200KB 以内。使用 precacheImage 在进入引导页之前预加载第一页图片避免首帧空白。如果用的是网络图记得配置缓存策略别每次都从头拉。我在实际项目里测过同样一套引导页优化前后首帧渲染时间差距甚至能到一倍。图片体积这个点设计提图时就要盯好别等上线了再来优化。写在最后的一点体会Flutter 的引导页说难不难说简单也不简单。难的地方不在 PageView 和 Indicator 本身而在你要以产品思维去理解一个入口页面——用户第一次打开 App 的几秒钟页面滑得顺不顺、指示器跟不跟手、按钮时机对不对都会直接影响他对产品质感的第一判断。我个人做这个功能的心得是先把交互层级拆开页面、控制器、指示器、按钮各司其职再用最小代码把链路跑通最后再加动画和存储逻辑。不要一上来就把 AnimatedContainer、shared_preferences、路由跳转全糊在一坨代码里那样出了问题反而特别难排查。最后分享一个小习惯我会在实现完引导页之后把 PageView 的源码翻出来看一眼重点看 PageController 的 animateToPage 和 onPageChanged 是在什么时机调起来的。Flutter 这种组件即文档的框架源码就是最好的学习资料。看完之后你对 PageView 的掌控感和上手其他滑动物件的能力都会上一个台阶。