Flutter进阶：用OverlayEntry 实现所有弹窗效果

一、需求来源

最近遇到一个需求：在直播页面弹窗（Sheet 和 Dialog），因为直播页面比较重，根据路由条件做了进入前台推流和退到后台断流的功能。在 Flutter 中 Sheet 和 Dialog 都通过路由拉起,发生了功能冲突。

只能通过 OverlayEntry 来实现 Sheet 和 Dialog 的效果。所以有 NOverlayDialog，支持 Dialog & Sheet & Drawer & Toast。

// SDK 弹窗拉起部分源码
Navigator.of(context, rootNavigator: useRootNavigator).push

二、使用示例

Dialog

NOverlayDialog.show(
  context,
  from: v,//v 是 Alignment 类型参数
  barrierColor: Colors.black12,
  // barrierDismissible: false,
  onBarrier: () {
    DLog.d('NOverlayDialog onBarrier');
  },
  child: GestureDetector(
    onTap: () {
      NOverlayDialog.dismiss();
      DLog.d('NOverlayDialog onBarrier');
    },
    child: Container(
      width: 300,
      height: 300,
      child: buildContent(
        title: v.toString(),
        onTap: () {
          NOverlayDialog.dismiss();
          DLog.d('NOverlayDialog onBarrier');
        },
      ),
    ),
  ),
);

Sheet

NOverlayDialog.sheet(
  context,
  child: buildContent(
    height: 400,
    margin: EdgeInsets.symmetric(horizontal: 30),
    onTap: () {
      NOverlayDialog.dismiss();
    },
  ),
);

Toast

NOverlayDialog.toast(
  context,
  hideBarrier: true,
  from: Alignment.center,
  message: "This is a Toast!",
);

三、源码 NOverlayDialog

//
//  NOverlayDialog.dart
//  flutter_templet_project
//
//  Created by shang on 2026/3/4 18:47.
//  Copyright © 2026/3/4 shang. All rights reserved.
//

import 'package:flutter/material.dart';

/// Dialog & Sheet & Drawer & Toast
class NOverlayDialog {
  NOverlayDialog._();

  static OverlayEntry? _entry;
  static AnimationController? _controller;

  static bool get isShowing => _entry != null;

  /// 隐藏
  static Future<void> dismiss({bool immediately = false}) async {
    if (!isShowing) {
      return;
    }

    final controller = _controller;
    final entry = _entry;
    _controller = null;
    _entry = null;

    if (immediately || controller == null) {
      entry?.remove();
      controller?.dispose();
      return;
    }

    await controller.reverse();
    entry?.remove();
    controller.dispose();
  }

  /// 显示 BottomSheet
  static void show(
    BuildContext context, {
    required Widget child,
    Alignment from = Alignment.bottomCenter,
    Duration duration = const Duration(milliseconds: 300),
    Curve curve = Curves.easeOutCubic,
    bool barrierDismissible = true,
    Color barrierColor = const Color(0x80000000),
    VoidCallback? onBarrier,
    bool hideBarrier = false,
    Duration? autoDismissDuration,
  }) {
    if (isShowing) {
      dismiss(immediately: true);
    }

    final overlay = Overlay.of(context, rootOverlay: true);
    _controller = AnimationController(
      vsync: overlay,
      duration: const Duration(milliseconds: 300),
    );

    final animation = CurvedAnimation(
      parent: _controller!,
      curve: Curves.easeOut,
      reverseCurve: Curves.easeIn,
    );

    Widget content = child;
    // ⭐ 中心弹窗：Fade
    if (from == Alignment.center) {
      content = FadeTransition(
        opacity: animation.drive(
          CurveTween(curve: Curves.easeOut),
        ),
        child: ScaleTransition(
          scale: Tween<double>(begin: 0.9, end: 1.0).animate(animation),
          child: content,
        ),
      );
    }

    // ⭐ 其余方向：Slide
    content = FadeTransition(
      opacity: animation,
      child: SlideTransition(
        position: animation.drive(
          Tween<Offset>(
            begin: Offset(from.x.sign, from.y.sign),
            end: Offset.zero,
          ).chain(
            CurveTween(curve: curve),
          ),
        ),
        child: content,
      ),
    );

    content = Align(
      alignment: from,
      child: content,
    );

    _entry = OverlayEntry(
      builder: (context) {
        if (hideBarrier) {
          return content;
        }

        return Stack(
          children: [
            // ===== Barrier =====
            GestureDetector(
              behavior: HitTestBehavior.opaque,
              onTap: barrierDismissible ? dismiss : onBarrier,
              child: FadeTransition(
                opacity: animation,
                child: Container(
                  color: barrierColor,
                ),
              ),
            ),
            content,
          ],
        );
      },
    );

    overlay.insert(_entry!);
    _controller?.forward();
    if (autoDismissDuration != null) {
      Future.delayed(autoDismissDuration, dismiss);
    }
  }

  /// 显示
  static void sheet(
    BuildContext context, {
    required Widget child,
    Alignment from = Alignment.bottomCenter,
    Duration duration = const Duration(milliseconds: 300),
    Curve curve = Curves.easeOutCubic,
    bool hideBarrier = false,
    Duration? autoDismissDuration,
  }) {
    return show(
      context,
      child: child,
      from: from,
      duration: duration,
      curve: curve,
      hideBarrier: hideBarrier,
      autoDismissDuration: autoDismissDuration,
    );
  }

  /// 显示 BottomSheet
  static void toast(
    BuildContext context, {
    Widget? child,
    String message = "",
    EdgeInsets margin = const EdgeInsets.only(bottom: 34),
    Alignment from = Alignment.center,
    Duration duration = const Duration(milliseconds: 300),
    Curve curve = Curves.easeOutCubic,
    bool hideBarrier = true,
    Duration? autoDismissDuration = const Duration(milliseconds: 2000),
  }) {
    final childDefault = Material(
      color: Colors.black.withOpacity(0.7),
      borderRadius: BorderRadius.all(Radius.circular(8)),
      child: Container(
        padding: EdgeInsets.symmetric(horizontal: 8, vertical: 4),
        child: Text(
          message,
          style: TextStyle(color: Colors.white),
        ),
      ),
    );
    return show(
      context,
      child: Padding(
        padding: margin,
        child: child ?? childDefault,
      ),
      from: from,
      duration: duration,
      curve: curve,
      hideBarrier: hideBarrier,
      autoDismissDuration: autoDismissDuration,
    );
  }
}

最后、总结

1、NOverlayDialog 脱离路由系统，基于 OverlayEntry 实现。

2、NOverlayDialog 核心是动画，from 是视图出现和消失方位。

from：Alignment.topCenter，是顶部下拉弹窗 TopSheet；
from：Alignment.bottomCenter，是底部上拉弹窗 BottomSheet；
from：Alignment.centerLeft | Alignment.centerRight, 是两侧弹窗 Drawer；
from：Alignment.center，是渐变弹窗 Dialog & Toast；

3、已添加进

pub.dev/packages/n_...