Flutter引导提示插件guide_it的使用

在开发Flutter应用时，有时我们需要为用户提供引导提示或教程。guide_it 插件是一个非常方便的工具，可以用来创建和展示引导提示或交互式教程。

使用

该插件使用 GlobalKey 来找到要高亮显示的小部件，并动态创建一个教程覆盖层。可以定义多个顺序的引导项来高亮显示不同的小部件。

请查看 示例 项目以了解如何将此插件集成到您的应用中。

示例代码

以下是使用 guide_it 插件的一个完整示例：

import "package:example/theme.dart";
import "package:flutter/material.dart";
import "package:guide_it/guide_it.dart";

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: "GuideIt example",
      theme: activeTheme,
      home: const MyHomePage(title: "GuideIt example"),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});
  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final GlobalKey _textKey = GlobalKey();
  final GlobalKey _iconKey = GlobalKey();
  final GlobalKey _secondIconKey = GlobalKey();
  final GlobalKey _fabKey = GlobalKey();

  final GuideController _controller = GuideController();
  static const String _guideId = "test";

  [@override](/user/override)
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  List<GuideItem> _guideItems() {
    return [
      GuideItem(
        targetWidgetKey: _textKey,
        child: const Wrap(
          alignment: WrapAlignment.center,
          crossAxisAlignment: WrapCrossAlignment.center,
          spacing: 16,
          children: [
            Icon(Icons.help_rounded), // 帮助图标
            Text("欢迎来到GuideIt示例"), // 提示文本
          ],
        ),
      ),
      GuideItem(
        targetWidgetKey: _iconKey,
        child: const Wrap(
          alignment: WrapAlignment.center,
          crossAxisAlignment: WrapCrossAlignment.center,
          spacing: 16,
          children: [
            Icon(Icons.place_rounded), // 地标图标
            Text("这是第一个图标，点击任何地方继续"), // 提示文本
          ],
        ),
      ),
      GuideItem(
        targetWidgetKey: _secondIconKey,
        child: const Wrap(
          alignment: WrapAlignment.center,
          crossAxisAlignment: WrapCrossAlignment.center,
          spacing: 16,
          children: [
            Icon(Icons.ac_unit_rounded), // 冰箱图标
            Text("这是第二个图标"), // 提示文本
          ],
        ),
      ),
      GuideItem(
        targetWidgetKey: _fabKey,
        displayOptions: (options) => options.copyWith(
          borderRadius: const Radius.circular(12), // 设置边框圆角
          defaultIndicator: GuideIndicator(
            child: Icon(
              Icons.replay_rounded, // 重新开始图标
              size: 32,
              color: Theme.of(context).colorScheme.secondary,
            ),
            adaptRotation: false, // 不旋转指示器
            animationOptions: const GuideAnimationOptions(
              curve: Curves.easeInBack, // 动画曲线
              duration: Duration(milliseconds: 350), // 动画时长
            ),
            size: 32,
          ),
        ),
        child: const Wrap(
          alignment: WrapAlignment.center,
          crossAxisAlignment: WrapCrossAlignment.center,
          spacing: 16,
          children: [
            Text("这是浮动操作按钮，按下它重新播放引导"), // 提示文本
          ],
        ),
      ),
    ];
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Guide(
      guid: _guideId,
      canShow: (guid) => true, // 控制是否显示引导
      controller: _controller,
      displayOptions: GuideDisplayOptions(
        highlightColor: Theme.of(context).colorScheme.tertiary.withOpacity(0.1), // 高亮颜色
        backgroundColor: Theme.of(context).colorScheme.background.withOpacity(0.85), // 背景颜色
        animationOptions: const GuideAnimationOptions(
          animate: true, // 启用动画
          fade: true, // 启用淡入淡出效果
          initialScale: 0.9, // 初始缩放比例
          transitionOffset: 50, // 过渡偏移
          type: AnimationType.translation, // 动画类型
          translationMode: TranslationMode.vertical, // 动画方向
          duration: Duration(milliseconds: 500), // 动画时长
        ),
      ),
      items: _guideItems(), // 引导项列表
      child: Scaffold(
        appBar: AppBar(
          backgroundColor: Theme.of(context).colorScheme.inversePrimary,
          title: Text(widget.title),
        ),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.start,
            children: [
              const SizedBox(height: 64),
              Padding(
                key: _textKey,
                padding: const EdgeInsets.all(8),
                child: const Text("欢迎来到GuideIt"), // 欢迎文本
              ),
              const Divider(height: 32), // 分割线
              Wrap(
                crossAxisAlignment: WrapCrossAlignment.center,
                spacing: 32,
                children: [
                  Icon(
                    key: _iconKey,
                    Icons.place_rounded,
                    size: 48,
                  ),
                  Icon(
                    key: _secondIconKey,
                    Icons.ac_unit_rounded,
                    size: 48,
                  ),
                ],
              ),
            ],
          ),
        ),
        floatingActionButton: FloatingActionButton(
          key: _fabKey,
          onPressed: () {
            _controller.showTutorial(params: ShowGuideParams(id: _guideId, force: true)); // 显示引导
          },
          child: const Icon(Icons.add), // 按钮图标
        ),
      ),
    );
  }
}