Flutter for OpenHarmony 实战之基础组件：第三十四篇 Tooltip 与 Overlay — 智能提示与全局悬浮层

Flutter for OpenHarmony 实战之基础组件：第三十四篇 Tooltip 与 Overlay — 智能提示与全局悬浮层

前言

在追求极致用户体验的鸿蒙应用开发中，我们不仅要处理好页面内的常规布局，还要应对那些“跳出常规流程”的 UI 需求。例如：用户长按图标时显示的文字解释（Tooltip），或者是覆盖在所有页面之上的全局悬浮球、自定义下拉列表（Overlay）。

在 Flutter for OpenHarmony 平台上，Tooltip 提供了原生的无障碍支持和气泡提示，而 Overlay 则是所有弹窗、路由、提示的底层支柱。本文将带大家深度掌握这两个组件，解锁构建复杂弹窗与悬浮层的高阶技能。

一、Tooltip：轻量级文字提示

Tooltip 用于为图标或小按钮提供额外的文字说明，通常由长按（移动端）或悬停（桌面端）触发。

1.1 基础用法

Tooltip(
message: '点击搜索',
child: IconButton(
icon: const Icon(Icons.search),
onPressed: () {},
),
)

1.2 高级定制：控制气泡样式

💡 提示：我们可以调整气泡的颜色、高度和动画持续时间。

Tooltip(
message: '设置中心',
padding: const EdgeInsets.all(12),
margin: const EdgeInsets.symmetric(horizontal: 20),
decoration: BoxDecoration(
color: Colors.blue[800],
borderRadius: BorderRadius.circular(8),
),
textStyle: const TextStyle(color: Colors.white, fontSize: 14),
showDuration: const Duration(seconds: 2), // 弹出后维持显示的时间
waitDuration: const Duration(milliseconds: 500), // 触发延迟
child: const Icon(Icons.settings),
)

二、Overlay：打破布局限制的悬浮层

Overlay 是一个可以包含多个 OverlayEntry 的 Stack。它不属于任何具体的页面，而是独立存在于 Navigator 顶层。

2.1 OverlayEntry 的核心机制

OverlayEntry 本质上是一个悬浮的 Widget 片段。

late OverlayEntry _overlayEntry;

void _showFloatingLayer(BuildContext context) {
_overlayEntry = OverlayEntry(
builder: (context) => Positioned(
top: 100,
right: 20,
child: Material(
elevation: 10,
borderRadius: BorderRadius.circular(50),
child: Container(
width: 50, height: 50,
color: Colors.blueAccent,
child: const Icon(Icons.help_center, color: Colors.white),
),
),
),
);

// 将 entry 插入到当前上下文所属的 Overlay 中
Overlay.of(context).insert(_overlayEntry);
}

2.2 移除悬浮层

⚠️ 注意：OverlayEntry 不会自动消失，必须手动移除。

void _removeLayer() {
_overlayEntry.remove();
}

三、实战：构建自定义下拉菜单弹窗

使用 Overlay 可以完美解决 DropdownButton 样式受限的问题。

void _toggleMenu(BuildContext context, GlobalKey buttonKey) {
// 1. 获取按钮在屏幕中的位置
final RenderBox renderBox = buttonKey.currentContext!.findRenderObject() as RenderBox;
final offset = renderBox.localToGlobal(Offset.zero);

_overlayEntry = OverlayEntry(
builder: (context) => Stack(
children: [
// 背景透明遮罩，点击消失
GestureDetector(onTap: () => _overlayEntry.remove()),
Positioned(
left: offset.dx,
top: offset.dy + renderBox.size.height,
child: _buildDropDownMenu(),
)
],
),
);
Overlay.of(context).insert(_overlayEntry);
}

四、OpenHarmony 平台适配建议

4.1 窗口层级管理 (Overlay 的深度)

在鸿蒙系统上，如果有多个 OverlayEntry，需要明确它们在 Overlay 中的层级。后插入的会覆盖先插入的。

✅ 推荐方案： 对于需要永久悬浮的内容（如全局公告），确保在页面跳转（Push/Pop）时，其 Entry 依然能被正确引用或优雅销毁。

4.2 触感与动画反馈

由于 Overlay 弹出通常带有一定的突兀感。

💡 调优建议： 配合 CompositedTransformTarget 和 CompositedTransformFollower 让 Overlay 组件能自动跟随底层组件移动/旋转，避免位置错位。并在显示时触发鸿蒙系统的 HapticFeedback。

4.3 屏蔽 Android 物理返回键的影响

在鸿蒙设备上点击边缘返回手势时。

✅ 最佳实践： 如果 Overlay 代表一个自定义弹窗，建议配合 PopScope 监听返回事件，在关闭页面前先检查并移除活着的 OverlayEntry。

五、完整示例代码

以下代码实现了一个“点击图标弹出 Tooltip”以及“点击按钮生成全屏悬浮组件”的综合示例。

import 'package:flutter/material.dart';

void main() => runApp(const MaterialApp(home: OverlayDemoPage()));

class OverlayDemoPage extends StatefulWidget {
const OverlayDemoPage({super.key});

@override
State<OverlayDemoPage> createState() => _OverlayDemoPageState();
}

class _OverlayDemoPageState extends State<OverlayDemoPage> {
OverlayEntry? _entry;

void _showOverlay() {
if (_entry != null) return;

_entry = OverlayEntry(
builder: (context) => Positioned(
bottom: 100,
left: MediaQuery.of(context).size.width / 2 – 60,
child: Material(
color: Colors.transparent,
child: Container(
padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
decoration: BoxDecoration(
color: Colors.black87,
borderRadius: BorderRadius.circular(30),
),
child: Row(
children: [
const Icon(Icons.flash_on, color: Colors.yellow, size: 20),
const SizedBox(width: 8),
const Text("悬浮提示已激活", style: TextStyle(color: Colors.white)),
const SizedBox(width: 12),
GestureDetector(
onTap: _hideOverlay,
child: const Icon(Icons.close, color: Colors.white, size: 16),
)
],
),
),
),
),
);

Overlay.of(context).insert(_entry!);
}

void _hideOverlay() {
_entry?.remove();
_entry = null;
}

@override
void dispose() {
_hideOverlay(); // 页面销毁前必须显式移除
super.dispose();
}

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('OHOS 提示与悬浮层实战')),
body: Center(
child: Column(
mainAxisAlignment: MainValue.center,
children: [
const Tooltip(
message: "这是一个长按可见的 Tooltip",
child: Icon(Icons.info_outline, size: 48, color: Colors.blue),
),
const SizedBox(height: 40),
ElevatedButton(
onPressed: _showOverlay,
child: const Text("弹出全局叠加层 (Overlay)"),
),
],
),
),
);
}
}

六、总结

在 Flutter for OpenHarmony 开发中，掌握 Tooltip 和 Overlay 是迈向高级 UI 开发的分水岭。

通过对这两者的灵活运用，你可以让你的鸿蒙应用在细节处充满惊喜。

📦 完整代码已上传至 AtomGit：flutter_ohos_examples

🌐 欢迎加入开源鸿蒙跨平台社区：开源鸿蒙跨平台开发者社区