Flutter中如何用自定义Widget替代Tooltip的默认字符串消息？

原生Flutter的Tooltip组件仅支持传入字符串类型的message参数，无法直接自定义提示内容的Widget，要实现该需求可以参考以下两种方案：

方案1：自定义实现Tooltip（无第三方依赖） #

通过监听鼠标hover事件结合Overlay组件实现完全自定义的提示逻辑，可自由控制交互逻辑和展示样式：

• 第一步：封装自定义Tooltip组件

import 'package:flutter/material.dart';

class CustomTooltip extends StatefulWidget {
  /// 触发提示的子组件
  final Widget child;
  /// 自定义提示内容，支持传入任意Widget
  final Widget tooltipContent;
  /// hover后展示提示的延迟时长，默认500ms
  final Duration showDelay;
  /// 提示相对子组件的展示偏移
  final Offset offset;

  const CustomTooltip({
    super.key,
    required this.child,
    required this.tooltipContent,
    this.showDelay = const Duration(milliseconds: 500),
    this.offset = const Offset(0, 20),
  });

  @override
  State<CustomTooltip> createState() => _CustomTooltipState();
}

class _CustomTooltipState extends State<CustomTooltip> {
  OverlayEntry? _overlayEntry;
  bool _isHoverTriggered = false;

  @override
  void dispose() {
    _removeTooltip();
    super.dispose();
  }

  void _showTooltip() async {
    _isHoverTriggered = true;
    // 等待延迟时长
    await Future.delayed(widget.showDelay);
    if (!_isHoverTriggered || _overlayEntry != null) return;

    // 获取触发组件的位置
    final renderBox = context.findRenderObject() as RenderBox;
    final childPosition = renderBox.localToGlobal(Offset.zero);

    _overlayEntry = OverlayEntry(
      builder: (context) => Positioned(
        left: childPosition.dx + widget.offset.dx,
        top: childPosition.dy + widget.offset.dy,
        // 加Material避免样式继承问题
        child: Material(
          elevation: 6,
          borderRadius: BorderRadius.circular(6),
          child: widget.tooltipContent,
        ),
      ),
    );
    // 插入Overlay展示提示
    Overlay.of(context).insert(_overlayEntry!);
  }

  void _removeTooltip() {
    _isHoverTriggered = false;
    _overlayEntry?.remove();
    _overlayEntry = null;
  }

  @override
  Widget build(BuildContext context) {
    return MouseRegion(
      onEnter: (_) => _showTooltip(),
      onExit: (_) => _removeTooltip(),
      child: widget.child,
    );
  }
}

• 第二步：调用示例

CustomTooltip(
  tooltipContent: Container(
    padding: const EdgeInsets.all(12),
    width: 220,
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      children: const [
        Text(
          '自定义提示标题',
          style: TextStyle(fontWeight: FontWeight.bold, fontSize: 14),
        ),
        SizedBox(height: 4),
        Text(
          '支持任意Widget组合，可以插入图片、按钮、列表等内容',
          style: TextStyle(fontSize: 12, color: Colors.grey),
        ),
        SizedBox(height: 4),
        Icon(Icons.star, color: Colors.orange, size: 16)
      ],
    ),
  ),
  child: const Icon(Icons.help_outline, size: 20),
)

方案2：修改原生Tooltip源码 #

如果需要保留原生Tooltip的所有交互特性（比如移动端长按触发、自动适配位置避免超出屏幕、跟随主题样式等），可以直接修改Flutter SDK中Tooltip的源码：

• 找到sdk/packages/flutter/lib/src/material/tooltip.dart文件
• 将类定义中final String message;修改为final Widget message;
• 找到Tooltip布局中展示提示内容的Text(message)组件，直接替换为message即可

该方案适配性更强，但需要注意Flutter版本升级后需要重新修改对应文件，适合对交互一致性要求较高的场景使用。

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