新用户第一次打开 App,通常要展示引导页,说明功能亮点或者隐私协议。我之前一直用 PageView 自己手搓,但后来发现有个叫 intro_slider 的插件,专门干这个的,干脆试试。
为什么选 intro_slider
搜了一圈,Flutter 的引导页插件不多,intro_slider 是 Star 最多的。它的特点:
- 纯 Dart 实现,不需要桥接原生,鸿蒙上直接跑
- 内置滑动翻页、跳过按钮、完成按钮,不用自己搭框架
- 支持自定义按钮样式、指示器样式、动画过渡
- 最后更新到 4.x 版本,API 改了但用起来反而更简洁了
我一开始想过用 shared_preferences 存个标记位来控制引导页显示,配合 PageView 做页面切换。但折腾半天发现自己写翻页逻辑、按钮显隐、页面指示器,代码量不小,而且每个项目都要重写一遍,不划算。
自己手搓 PageView 引导页大概要写这些东西:
- PageController 控制翻页
- 监听页面索引变化,控制跳过按钮显隐
- 自己画指示器小圆点
- 最后一页把"下一步"换成"完成"
- 加上动画过渡效果的话更麻烦
算下来没有一百行代码搞不定。而且每个项目都来一遍,烦。干脆用现成的吧。
环境说明
DevEco Studio 6.1.0.830
HarmonyOS NEXT 6.1
Flutter SDK 3.6.2
装包
pubspec.yaml 加一行:
dependencies:
intro_slider: ^4.2.5
然后 flutter pub get,没什么波折,纯 Dart 包不涉及原生编译。
版本 4.x 的 API 变化
这里有个小坑。网上搜 intro_slider 的教程,大部分是 3.x 版本的用法,那时候用的是 Slide 类,传 listSlides 参数。4.x 之后改成了 ContentConfig 和 listContentConfig,方法签名全换了。
我第一次照着旧教程写,编译直接报错:
The named parameter 'listSlides' isn't defined.
查了官方文档才发现 API 重构了。所以用的时候一定要看 pub.dev 上的最新文档,别被旧文章带偏。
3.x 的写法(旧的):
// 旧 API,已弃用
IntroSlider(
slides: [
Slide(
title: '欢迎',
description: 'xxx',
),
],
)
4.x 的写法(当前的):
IntroSlider(
listContentConfig: [
ContentConfig(
title: '欢迎',
description: 'xxx',
),
],
)
另外 4.x 还把按钮回调从 onDonePress 之类的独立参数改到了 ButtonBar 定制里,这个后面再说。
我是怎么搭的
先定义引导页的内容。我做了 4 页,分别介绍欢迎、原生桥接、能力列表、开始体验。
List<ContentConfig> _listContentConfig() {
return [
const ContentConfig(
title: '欢迎使用',
description: '鸿蒙 Flutter 桥接 Demo 合集,展示原生能力无缝调用',
backgroundColor: Color(0xff203152),
styleTitle: TextStyle(
color: Colors.white,
fontSize: 24,
fontWeight: FontWeight.bold,
),
styleDescription: TextStyle(
color: Colors.white70,
fontSize: 16,
),
),
const ContentConfig(
title: '原生桥接',
description: 'MethodChannel 打通 Flutter 和鸿蒙 ArkTS,双向通信零障碍',
backgroundColor: Color(0xff3D5A80),
styleTitle: TextStyle(
color: Colors.white,
fontSize: 24,
fontWeight: FontWeight.bold,
),
styleDescription: TextStyle(
color: Colors.white70,
fontSize: 16,
),
),
const ContentConfig(
title: '能力丰富',
description: 'Toast / 分享 / 剪贴板 / 设备信息 / 震动 / 通知 / 更新检测……',
backgroundColor: Color(0xffEE6C4D),
styleTitle: TextStyle(
color: Colors.white,
fontSize: 24,
fontWeight: FontWeight.bold,
),
styleDescription: TextStyle(
color: Colors.white70,
fontSize: 16,
),
),
const ContentConfig(
title: '开始体验',
description: '点击 Done 进入 Demo 列表,体验各桥接能力',
backgroundColor: Color(0xff293241),
styleTitle: TextStyle(
color: Colors.white,
fontSize: 24,
fontWeight: FontWeight.bold,
),
styleDescription: TextStyle(
color: Colors.white70,
fontSize: 16,
),
),
];
}
每个 ContentConfig 可以配标题、描述、背景色、文字样式。背景色我用了不同的色系,让翻页时有视觉变化感。

ContentConfig 还能塞什么
除了基本的 title 和 description,ContentConfig 还支持传自定义 widget,通过 widget 参数塞进去。比如每页加个图标或者插张图:
ContentConfig(
title: '原生桥接',
description: 'MethodChannel 打通 Flutter 和鸿蒙 ArkTS',
widget: Icon(Icons.bridge, size: 64, color: Colors.white),
backgroundColor: Color(0xff3D5A80),
)
这样布局更灵活,图片、图标、甚至自定义组件都能往里放,不用局限于文字。
按钮定制
默认的按钮是英文的,我用中文替换了:
IntroSlider(
listContentConfig: _listContentConfig(),
onDonePress: () { /* 完成回调 */ },
onSkipPress: () { /* 跳过回调 */ },
renderDoneBtn: const Text('开始使用',
style: TextStyle(color: Colors.white, fontSize: 16)),
renderSkipBtn: const Text('跳过',
style: TextStyle(color: Colors.white70, fontSize: 16)),
renderNextBtn: const Text('下一步',
style: TextStyle(color: Colors.white, fontSize: 16)),
)
renderDoneBtn— 最后一页的完成按钮renderSkipBtn— 跳过按钮,默认显示在前几页renderNextBtn— 下一页按钮
如果你想完全自定义按钮栏,4.x 也支持传 renderButtonBar 自己搭布局。不过我觉得默认的就够用了,不想折腾太多。

页面指示器样式
intro_slider 默认用圆点指示器,可以通过 dotIndicator 和 activeDotIndicator 参数自定义:
IntroSlider(
listContentConfig: _listContentConfig(),
dotIndicator: const DotIndicator(
color: Colors.white38,
size: 8,
),
activeDotIndicator: const DotIndicator(
color: Colors.white,
size: 10,
),
)
DotIndicator 支持配颜色、大小、边距。间距在 spaceBetweenDots 里设。如果你想要横条样式的指示器,可以换成 BarIndicator,或者直接用 indicatorOptions 做更细的控制。
我一开始没注意指示器间距,默认靠得太近,翻页时看着不够明显,调大了两像素舒服多了。
状态管理:引导页只显示一次
引导页的通用逻辑是首次安装显示一次,之后不再显示。我这里用了一个简单的 _showSlider 布尔值控制,实际项目中应该配合 shared_preferences 持久化。
bool _showSlider = true;
@override
Widget build(BuildContext context) {
if (_showSlider) {
return _buildIntroSlider();
}
return _buildMainContent();
}
在 onDonePress 和 onSkipPress 里把 _showSlider 设成 false,引导页消失,展示主内容。
如果要用 shared_preferences 持久化,大概这样:
class _IntroSliderDemoState extends State<IntroSliderDemo> {
bool? _showSlider;
@override
void initState() {
super.initState();
_checkFirstLaunch();
}
Future<void> _checkFirstLaunch() async {
final prefs = await SharedPreferences.getInstance();
final hasSeen = prefs.getBool('has_seen_intro') ?? false;
setState(() => _showSlider = !hasSeen);
}
Future<void> _onIntroComplete() async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('has_seen_intro', true);
setState(() => _showSlider = false);
}
}
这样用户关闭引导页后,下次打开 App 直接进主页,不用再看一遍。
主界面留个"重新查看"入口
引导页结束后,我加了一个按钮可以让用户回看引导页,方便测试也方便用户忘记功能时再瞅一眼:
ElevatedButton.icon(
onPressed: () {
setState(() => _showSlider = true);
},
icon: const Icon(Icons.replay),
label: const Text('重新查看引导页'),
)
实际上线时这个按钮可以藏到关于页面或者设置页里,不用摆在主界面。

引导页的不同使用场景
intro_slider 除了常规的新用户引导,其实还可以用在:
功能介绍页:大版本更新后展示新功能。这个场景下不需要跳过按钮,可以让用户逐页看完。可以用 isShowSkipBtn: false 隐藏跳过。
隐私协议页:首屏展示隐私协议,用户滑动到底才能同意。可以在最后一页加一个"我已阅读并同意"的复选框 widget,通过 widget 参数嵌入。
配置引导页:像语言选择、兴趣标签选择,可以在引导页里嵌入自定义表单 widget,每页一个配置项。
不过我试过在 ContentConfig 的 widget 参数里塞表单组件,布局上需要注意高度自适应的问题,不然键盘弹起来可能把页面挤变形。
踩过的坑
旧 API 和文档不符
intro_slider 从 3.x 升到 4.x 时 API 变动挺大,Slide 变成了 ContentConfig,listSlides 变成了 listContentConfig。我去 pub.dev 看了最新文档才弄清楚。所以新项目尽量用 4.x,旧项目升级要注意兼容。
样式定制有限制
ContentConfig 里的 styleTitle 和 styleDescription 只支持 TextStyle,不支持 StrutStyle 之类的其他文字属性,如果要做很精细的文字排版可能会受限。我一开始想给标题加点字间距,发现不行,得自己在 title 里拼 widget 或者换别的方案。
按钮文字不显示中文
第一次跑的时候,按钮显示的是 "Done" "Skip" "Next",我传了中文 Text widget 进去就好了,这个倒不算坑,就是注意一下默认是英文。
背景色作用范围
ContentConfig 的 backgroundColor 只覆盖内容区域,不是整个页面。如果页面有 SafeArea,上下可能会有白边。解决办法是在 IntroSlider 外面包一层 ColoredBox 或者 Container 设置同样的背景色:
Container(
color: const Color(0xff203152),
child: IntroSlider(...),
)
查了半天文档才发现是这个原因,一开始还以为设置没生效。
页面数量少的时候指示器偏左
我试过只配 2 页引导内容,指示器小圆点会偏左,视觉上不对称。翻了 issue 发现是默认行为,小圆点居左而不是居中。解决办法是自己配 centerDotIndicator 或者用 DotIndicator 的 margin 手动调。
不过我后来觉得 2 页太少,加到 4 页就正常了,也算是曲线救国。
对比一下手写 PageView
最后说个实在的,intro_slider 到底省了多少事。我之前手写引导页大概要写:
- PageController 加 StatefulWidget 生命周期管理
- onPageChanged 监听做按钮显隐逻辑
- Positioned 堆叠指示器
- 最后一页和普通页的按钮文案切换
- 进出动画 Duration 调整
大概 150 行左右,还不包括样式调整。用 intro_slider 之后,内容定义加配置,七八十行搞定,而且按钮交互、指示器、动画都是现成的,不太容易出现翻页卡顿或者动画闪烁的问题。
不过如果你的引导页每页布局差异很大,比如第一页是视频背景、第二页是表单填写,那还是自己用 PageView 吧。intro_slider 适合内容结构统一、以文字和图标为主的场景。
写在最后
引导页不是什么复杂功能,但自己从头写又觉得重复劳动。intro_slider 正好卡在这个"需要但不复杂"的点上,几行代码搞定,省心。
对了,如果要用在正式项目里别忘了处理持久化状态,不然用户每次打开都看到引导页,估计会想删 App。
另外一个小建议:引导页的配图最好用 App 实际截图,不要放占位图。我之前发布时忘了替换占位图,审核被打回来一次,尴尬。
总的来说,intro_slider 是个省心的小工具,该有的功能都有了。










































苏公安网备 32011402010933号