Flutter ShowcaseView跨页面引导：点击遮罩无法推进问题及解决

问题 #

在Flutter应用中使用ShowcaseView包实现引导tour时，遇到一个问题：多数步骤里点击目标区域外的遮罩（overlay）可正常推进引导，但当步骤需要跳转到不同页面（比如切换标签页、推送新路由）时，点击遮罩无法触发导航，导致引导停滞。

现象总结 #

• 同一页面内的引导步骤，点击目标区域外的遮罩可正确推进引导流程
• 涉及页面导航的步骤，遮罩的点击事件未被触发，无法执行导航逻辑
• 尝试过使用onTargetClick回调、用GestureDetector包裹页面拦截点击，但仅点击引导目标时有效，遮罩激活状态下无法捕获遮罩区域的点击
• 期望实现一致的交互体验：点击遮罩任意位置（不仅是“下一步”按钮）都能推进跨页面引导
• 该问题在MacOS和Chrome平台均能复现

解决方案 #

最初的临时方案是禁用Showcase的overlay交互，强制用户点击“下一步”按钮推进，但体验不够流畅。后续经库作者建议，使用onBarrierClick回调方案，无需依赖按钮即可实现点击遮罩触发导航，体验更自然。

核心代码示例 #

onBarrierClick: () async {
  onDestinationSelected(1); // 执行页面导航操作，比如切换到指定标签页
  await Future.delayed(const Duration(milliseconds: 300)); // 延迟等待页面切换完成，避免引导步骤异常
},

完整自定义导航栏示例代码 #

import 'package:flutter/material.dart';
import 'package:showcaseview/showcaseview.dart';

class CustomNavigationBar extends StatelessWidget {
  final int currentIndex;
  final ValueChanged<int> onDestinationSelected;
  final GlobalKey headerTooltip;
  final GlobalKey homeTabTooltip;
  final GlobalKey notificationsTabTooltip;
  final GlobalKey messagesTabTooltip;

  const CustomNavigationBar({
    super.key,
    required this.currentIndex,
    required this.onDestinationSelected,
    required this.headerTooltip,
    required this.homeTabTooltip,
    required this.notificationsTabTooltip,
    required this.messagesTabTooltip,
  });

  @override
  Widget build(BuildContext context) {
    return NavigationBar(
      onDestinationSelected: onDestinationSelected,
      selectedIndex: currentIndex,
      indicatorColor: Colors.amber,
      destinations: [
        Showcase(
          key: homeTabTooltip,
          description: "Home tooltip",
          tooltipActions: [
            TooltipActionButton(
              backgroundColor: Colors.white,
              type: TooltipDefaultActionType.previous,
              padding: const EdgeInsets.symmetric(vertical: 4),
              textStyle: const TextStyle(color: Colors.pinkAccent),
            ),
            TooltipActionButton(
              type: TooltipDefaultActionType.next,
              backgroundColor: Colors.white,
              textStyle: const TextStyle(color: Colors.pinkAccent),
            ),
          ],
          child: NavigationDestination(
            selectedIcon: KeyedSubtree(
              key: GlobalKey(),
              child: const Icon(Icons.home),
            ),
            icon: KeyedSubtree(
              key: GlobalKey(),
              child: const Icon(Icons.home_outlined),
            ),
            label: 'Home',
          ),
        ),
        Showcase(
          key: notificationsTabTooltip,
          description: "Notification tooltip",
          tooltipActions: [
            TooltipActionButton(
              backgroundColor: Colors.white,
              type: TooltipDefaultActionType.previous,
              padding: const EdgeInsets.symmetric(vertical: 4),
              textStyle: const TextStyle(color: Colors.pinkAccent),
            ),
            TooltipActionButton(
              type: TooltipDefaultActionType.next,
              backgroundColor: Colors.white,
              textStyle: const TextStyle(color: Colors.pinkAccent),
            ),
          ],
          child: NavigationDestination(
            icon: KeyedSubtree(
              key: GlobalKey(),
              child: const Icon(Icons.notifications),
            ),
            label: 'Notifications',
          ),
        ),
        Showcase(
          key: messagesTabTooltip,
          description: "Messages tooltip",
          // 新增此回调解决问题
          onBarrierClick: () async {
            // 执行页面导航
            onDestinationSelected(1);
            await Future.delayed(const Duration(milliseconds: 300));
          },
          tooltipActions: [
            TooltipActionButton(
              backgroundColor: Colors.white,
              type: TooltipDefaultActionType.previous,
              padding: const EdgeInsets.symmetric(vertical: 4),
              textStyle: const TextStyle(color: Colors.pinkAccent),
            ),
            TooltipActionButton(
              type: TooltipDefaultActionType.next,
              backgroundColor: Colors.white,
              textStyle: const TextStyle(color: Colors.pinkAccent),
              onTap: () async {
                debugPrint("Tooltip next button tapped");
                onDestinationSelected(1);
                await Future.delayed(const Duration(milliseconds: 300));
                ShowCaseWidget.of(context).next();
              },
            ),
          ],
          child: NavigationDestination(
            icon: KeyedSubtree(
              key: GlobalKey(),
              child: const Icon(Icons.message),
            ),
            label: 'Messages',
          ),
        ),
      ],
    );
  }
}

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