Flutter 如何实现应用首次启动时展示新手引导功能

核心逻辑 #

整个功能分为两个核心模块：

• 本地持久化存储引导完成状态，每次启动优先读取该状态判断是否需要展示引导
• 引导页步骤切换交互，用户完成全部引导或主动跳过后，更新存储状态

1. 引入持久化存储依赖 #

使用官方维护的shared_preferences库实现状态持久化，首先在pubspec.yaml中添加依赖：

dependencies:
  flutter:
    sdk: flutter
  shared_preferences: ^2.2.2

执行flutter pub get完成依赖安装。

2. 启动时路由判断 #

在应用初始化阶段读取存储的引导完成状态，直接决定初始路由：

void main() async {
  // 确保初始化完成再执行异步操作
  WidgetsFlutterBinding.ensureInitialized();
  final SharedPreferences prefs = await SharedPreferences.getInstance();
  // 读取状态，未查到值时默认是未完成引导
  final bool hasCompletedGuide = prefs.getBool('hasCompletedGuide') ?? false;
  runApp(
    MaterialApp(
      initialRoute: hasCompletedGuide ? '/home' : '/guide',
      routes: {
        '/home': (context) => const HomePage(),
        '/guide': (context) => const GuidePage(),
      },
    )
  );
}

3. 引导页实现 #

引导页使用PageView组件实现多步骤切换，底部配置下一步、完成、跳过按钮：

class GuidePage extends StatefulWidget {
  const GuidePage({super.key});

  @override
  State<GuidePage> createState() => _GuidePageState();
}

class _GuidePageState extends State<GuidePage> {
  final PageController _pageController = PageController();
  // 引导页总页数
  final int _totalPage = 3;
  int _currentPage = 0;

  // 标记引导完成，跳转首页
  void _completeGuide() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setBool('hasCompletedGuide', true);
    if (mounted) {
      Navigator.pushReplacementNamed(context, '/home');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: PageView(
        controller: _pageController,
        onPageChanged: (index) => setState(() => _currentPage = index),
        children: const [
          // 替换为你自己的引导页内容组件
          GuideItem(title: "功能1", desc: "功能1介绍"),
          GuideItem(title: "功能2", desc: "功能2介绍"),
          GuideItem(title: "功能3", desc: "功能3介绍"),
        ],
      ),
      bottomNavigationBar: Padding(
        padding: const EdgeInsets.all(16),
        child: Row(
          mainAxisAlignment: MainAxisAlignment.spaceBetween,
          children: [
            // 跳过按钮，非最后一步显示
            if (_currentPage != _totalPage -1)
              TextButton(onPressed: _completeGuide, child: const Text("跳过")),
            // 页码指示器
            Row(
              children: List.generate(_totalPage, (index) => Container(
                margin: const EdgeInsets.symmetric(horizontal: 4),
                width: _currentPage == index ? 20 : 8,
                height: 8,
                decoration: BoxDecoration(
                  color: _currentPage == index ? Colors.blue : Colors.grey,
                  borderRadius: BorderRadius.circular(4)
                ),
              )),
            ),
            // 下一步/完成按钮
            TextButton(
              onPressed: () {
                if (_currentPage == _totalPage -1) {
                  _completeGuide();
                } else {
                  _pageController.nextPage(duration: const Duration(milliseconds: 300), curve: Curves.ease);
                }
              },
              child: Text(_currentPage == _totalPage -1 ? "完成" : "下一步"),
            )
          ],
        ),
      ),
    );
  }
}

可选优化点 #

• 若应用大版本更新后需要重新展示引导，可将存储key加上版本号，例如hasCompletedGuide_v2，版本迭代后修改key即可重新触发引导
• 可给PageView添加自定义切换动画，优化引导页过渡体验
• 引导页内容支持图片、视频等富媒体展示，按需调整GuideItem组件即可

内容的提问来源于stack exchange，提问作者Wasiq Hussain