Flutter CustomPainter无法重绘求助：教程遮罩切换失效

核心问题分析 #

1. OverlayEntry未触发强制重建：OverlayEntry独立于当前Widget树的build流程，仅通过setState更新状态不会自动触发其重建，导致CustomPainter无法接收到新的参数。
2. 布局边界获取时机错误：切换高亮目标时，直接获取GlobalKey对应的RenderBox边界可能发生在Widget布局完成前，拿到的是无效的零尺寸Rect，导致遮罩绘制为空。
3. DartPad渲染优化限制：DartPad对Overlay与CustomPainter的组合存在初始化时机问题，首次绘制时上下文未完全就绪，导致遮罩不渲染。

分步解决方法 #

1. 强制OverlayEntry重建 #

状态更新后必须调用markNeedsBuild()，通知OverlayEntry重新构建内容：

void _nextStep() {
  if (currentStep >= widget.targetKeys.length - 1) {
    _overlayEntry?.remove();
    _overlayEntry = null;
    return;
  }
  setState(() => currentStep++);
  // 关键：触发OverlayEntry重建
  _overlayEntry?.markNeedsBuild();
  _updateHoleRect();
}

2. 延迟获取目标Widget边界 #

使用WidgetsBinding.instance.addPostFrameCallback等待布局完成后再获取边界，确保拿到有效尺寸：

void _updateHoleRect() {
  WidgetsBinding.instance.addPostFrameCallback((_) {
    final renderBox = widget.targetKeys[currentStep].currentContext?.findRenderObject() as RenderBox?;
    if (renderBox == null) return;
    setState(() {
      _holeRect = renderBox.localToGlobal(Offset.zero) & renderBox.size;
    });
    _overlayEntry?.markNeedsBuild();
  });
}

3. 修正CustomPainter重绘逻辑 #

确保shouldRepaint严格对比关键参数（镂空区域Rect），避免无效重绘或漏重绘：

class HolePainter extends CustomPainter {
  final Rect holeRect;

  HolePainter(this.holeRect);

  @override
  void paint(Canvas canvas, Size size) {
    final maskPaint = Paint()..color = Colors.black.withOpacity(0.7);
    // 绘制全屏遮罩
    canvas.drawRect(Offset.zero & size, maskPaint);
    // 裁切镂空区域
    canvas.save();
    canvas.clipRect(holeRect, clipOp: ClipOp.difference);
    canvas.drawRect(Offset.zero & size, maskPaint);
    canvas.restore();
  }

  @override
  bool shouldRepaint(HolePainter oldDelegate) => oldDelegate.holeRect != holeRect;
}

4. 修正OverlayEntry初始化时机 #

在initState中延迟初始化OverlayEntry，确保上下文就绪：

@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    _overlayEntry = _createOverlayEntry();
    Overlay.of(context).insert(_overlayEntry!);
    _updateHoleRect();
  });
}

5. DartPad适配方案 #

DartPad中需确保OverlayEntry的内容依赖动态状态，可通过Builder包裹CustomPaint：

OverlayEntry _createOverlayEntry() {
  return OverlayEntry(
    builder: (context) {
      return GestureDetector(
        onTap: _nextStep,
        child: Builder(
          builder: (context) => Positioned.fill(
            child: CustomPaint(painter: HolePainter(_holeRect)),
          ),
        ),
      );
    },
  );
}

完整修复后的核心代码 #

class TutorialOverlay extends StatefulWidget {
  final List<GlobalKey> targetKeys;
  final Widget child;

  const TutorialOverlay({super.key, required this.targetKeys, required this.child});

  @override
  State<TutorialOverlay> createState() => _TutorialOverlayState();
}

class _TutorialOverlayState extends State<TutorialOverlay> {
  int currentStep = 0;
  Rect _holeRect = Rect.zero;
  OverlayEntry? _overlayEntry;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      _overlayEntry = _createOverlayEntry();
      Overlay.of(context).insert(_overlayEntry!);
      _updateHoleRect();
    });
  }

  void _updateHoleRect() {
    WidgetsBinding.instance.addPostFrameCallback((_) {
      final renderBox = widget.targetKeys[currentStep].currentContext?.findRenderObject() as RenderBox?;
      if (renderBox == null) return;
      setState(() {
        _holeRect = renderBox.localToGlobal(Offset.zero) & renderBox.size;
      });
      _overlayEntry?.markNeedsBuild();
    });
  }

  void _nextStep() {
    if (currentStep >= widget.targetKeys.length - 1) {
      _overlayEntry?.remove();
      _overlayEntry = null;
      return;
    }
    setState(() => currentStep++);
    _updateHoleRect();
  }

  OverlayEntry _createOverlayEntry() {
    return OverlayEntry(
      builder: (context) {
        return GestureDetector(
          onTap: _nextStep,
          child: Positioned.fill(
            child: CustomPaint(painter: HolePainter(_holeRect)),
          ),
        );
      },
    );
  }

  @override
  Widget build(BuildContext context) => widget.child;

  @override
  void dispose() {
    _overlayEntry?.remove();
    super.dispose();
  }
}

class HolePainter extends CustomPainter {
  final Rect holeRect;

  HolePainter(this.holeRect);

  @override
  void paint(Canvas canvas, Size size) {
    final maskPaint = Paint()..color = Colors.black.withOpacity(0.7);
    canvas.drawRect(Offset.zero & size, maskPaint);
    canvas.save();
    canvas.clipRect(holeRect, clipOp: ClipOp.difference);
    canvas.drawRect(Offset.zero & size, maskPaint);
    canvas.restore();
  }

  @override
  bool shouldRepaint(HolePainter oldDelegate) => oldDelegate.holeRect != holeRect;
}

关键注意事项 #

• 永远在布局完成后获取目标Widget的边界，避免拿到未初始化的零尺寸。
• OverlayEntry不属于常规Widget树，状态更新后必须手动调用markNeedsBuild()触发重建。
• CustomPainter的shouldRepaint是重绘的核心开关，必须准确对比关键参数。

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