文档开发者中心
我的

给鸿蒙 Flutter App 加引导页,intro_slider 够用了

浏览6.1W+发布于2026-06-30 15:48河南
本文章最后由 在人间耕耘 于 2026-07-05 10:10 编辑

新用户第一次打开 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 是个省心的小工具,该有的功能都有了。

收藏
1
回复
5
分享
全部评论
authorIcon
匿名用户
复刻一下
回复于2026-07-01 05:04广东
authorIcon
匿名用户
666
回复于2026-07-01 04:57广东
authorIcon
寻常老百姓
点赞
回复于2026-07-01 04:24青海
authorIcon
匿名用户
赞
回复于2026-07-01 02:58浙江
authorIcon
lorin
感谢分享
回复于2026-07-01 02:42广东
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
为什么选 intro_slider
环境说明
装包
版本 4.x 的 API 变化
我是怎么搭的
ContentConfig 还能塞什么
按钮定制
页面指示器样式
状态管理:引导页只显示一次
主界面留个"重新查看"入口
引导页的不同使用场景
踩过的坑
对比一下手写 PageView
写在最后
了解社区公约,与您携手共创和谐专业的开发者社区。