Flutter 的 Overlay 机制

Flutter 的 Overlay 机制是一个强大的浮层系统

什么是 Overlay？

想象你的 Flutter 应用是一本书：

• 普通 Widget 就像书页上的文字，按顺序排列，受页面布局限制
• Overlay 就像透明贴纸，可以贴在任何页面的最上层，不受页面布局影响

核心概念

1. Overlay（浮层容器）

// 每个 MaterialApp 都自带一个 Overlay
// 通过 Overlay.of(context) 获取
final overlay = Overlay.of(context);

2. OverlayEntry（浮层条目）

// 创建一个浮层条目
final entry = OverlayEntry(
  builder: (context) => Positioned(
    top: 100,
    left: 50,
    child: Text('我浮在最上层！'),
  ),
);

// 插入到 Overlay 中显示
overlay.insert(entry);

// 移除
entry.remove();

工作原理

┌─────────────────────────────┐
│   MaterialApp               │
│  ┌─────────────────────┐    │
│  │  Scaffold           │    │
│  │  ┌───────────────┐  │    │
│  │  │  AppBar       │  │    │
│  │  └───────────────┘  │    │
│  │  ┌───────────────┐  │    │
│  │  │  Body         │  │    │  ← 普通 Widget 层
│  │  │  (你的页面)   │  │    │
│  │  └───────────────┘  │    │
│  └─────────────────────┘    │
│                              │
│  ┌─────────────────────┐    │
│  │  Overlay Layer      │    │  ← Overlay 浮层
│  │  ┌───────────────┐  │    │
│  │  │  Toast 1      │  │    │
│  │  └───────────────┘  │    │
│  │  ┌───────────────┐  │    │
│  │  │  Dialog       │  │    │
│  │  └───────────────┘  │    │
│  └─────────────────────┘    │
└─────────────────────────────┘

常见应用场景

1. Toast 提示（我们的例子）

Toast.show(context, '操作成功');
// 浮在所有内容之上，不影响页面布局

2. Dialog 对话框

showDialog(context, ...);
// 内部就是用 Overlay 实现的

3. Dropdown 下拉菜单

// 下拉菜单展开时，内容浮在按钮上方

4. Tooltip 工具提示

Tooltip(message: '提示文字');
// 长按时浮层显示提示

为什么用 Overlay？

优势

1. 不受布局限制 - 可以显示在任何位置，不会挤压其他内容
2. 层级最高 - 永远显示在最上层
3. 独立管理 - 可以随时插入/移除，不影响原有 Widget 树
4. 全局访问 - 通过 Overlay.of(context) 在任何地方访问

对比普通 Widget

// ❌ 普通 Widget - 受布局限制
Column(
  children: [
    Text('内容'),
    Container(...), // Toast？会挤压上面的内容
  ],
)

// ✅ Overlay - 浮在上层
// Toast 显示时不影响原有布局

我们的 Toast 实现

static void show(BuildContext context, String message) {
  // 1. 获取 Overlay 容器
  final overlay = Overlay.of(context);
  
  // 2. 创建浮层条目
  final overlayEntry = OverlayEntry(
    builder: (context) => Positioned(  // 使用 Positioned 定位
      bottom: 100,
      left: 20,
      right: 20,
      child: _ToastWidget(...),  // 我们的 Toast Widget
    ),
  );
  
  // 3. 插入到 Overlay 中显示
  overlay.insert(overlayEntry);
  
  // 4. 稍后移除
  Future.delayed(duration, () {
    overlayEntry.remove();
  });
}

关键点

1. Positioned 必须 - Overlay 中的 Widget 必须用 Positioned 包裹来定位
2. 手动管理生命周期 - 需要自己调用 insert() 和 remove()
3. 单例模式 - 我们用 _currentOverlay 确保同时只显示一个 Toast
4. Material 包裹 - 需要 Material Widget 提供主题支持

这就是为什么 Toast 能"浮"在页面上，而不会影响原有布局的原因！