Flutter对齐提示插件aligned_tooltip的使用

aligned_tooltip 是一个Flutter插件，提供了比标准 Tooltip 更灵活的提示功能。它允许你设置任意内容，并且可以适应垂直和水平布局。以下是关于如何使用该插件的详细介绍。

快速开始

要使用 aligned_tooltip 插件，你需要在你的项目中添加依赖项。在 pubspec.yaml 文件中添加以下代码：

dependencies:
  aligned_tooltip: ^latest_version # 替换为最新版本号

然后运行 flutter pub get 来安装依赖。

基本用法

AlignedTooltip 需要两个参数：直接子组件（child）和提示内容（content）。下面是一个简单的例子：

import 'package:flutter/material.dart';
import 'package:aligned_tooltip/aligned_tooltip.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Aligned Tooltip Example')),
        body: Center(
          child: AlignedTooltip(
            child: Material(
              color: Colors.grey.shade800,
              shape: const CircleBorder(),
              elevation: 4.0,
              child: const Padding(
                padding: EdgeInsets.all(8.0),
                child: Icon(Icons.add, color: Colors.white),
              ),
            ),
            content: const Padding(
              padding: EdgeInsets.all(8.0),
              child: Text(
                '这是一个示例提示文本。',
              ),
            ),
          ),
        ),
      ),
    );
  }
}

使用控制器管理状态

如果你想更精确地控制提示框的状态，你可以创建一个 AlignedController 实例并将其传递给构造函数：

final tooltipController = AlignedController();

@override
void initState() {
  super.initState();
  // 程序化显示提示框，延迟2秒后显示
  Future.delayed(const Duration(seconds: 2), () {
    tooltipController.showTooltip(immediately: false);
  });

  tooltipController.addListener(() {
    // 打印提示框的状态
    print('controller: ${tooltipController.value}');
  });
}

@override
Widget build(BuildContext context) {
  return AlignedTooltip(
    controller: tooltipController,
    child: Material(
      color: Colors.grey.shade800,
      shape: const CircleBorder(),
      elevation: 4.0,
      child: const Padding(
        padding: EdgeInsets.all(8.0),
        child: Icon(Icons.add, color: Colors.white),
      ),
    ),
    content: const Padding(
      padding: EdgeInsets.all(8.0),
      child: Text(
        '这是一个由控制器管理的提示文本。',
      ),
    ),
  );
}

自定义提示框行为

模态提示框

你可以通过设置 isModal 属性来定义提示框的行为。模态提示框仅通过点击子组件打开，并通过点击背景区域关闭。非模态提示框则会在悬停时自动显示和隐藏。

AlignedTooltip(
  isModal: true,
  child: ...,
  content: ...,
)

自定义尾部

如果你想要自定义提示框的尾部（即对话框气泡上的小箭头），你可以传递自己的 tailBuilder 函数：

Path customTailBuilder(Offset tip, Offset point2, Offset point3) {
  return Path()
    ..moveTo(tip.dx, tip.dy)
    ..lineTo(point2.dx, point2.dy)
    ..lineTo(point3.dx, point3.dy)
    ..close();
}

AlignedTooltip(
  tailBuilder: customTailBuilder,
  child: ...,
  content: ...,
)

在列表视图中使用

提示框可以在列表中跟随目标滚动。为了更好地考虑可用空间，你可以传递一个 ScrollController 给 just_the_tooltip：

ListView.builder(
  controller: scrollController,
  itemCount: 30,
  itemBuilder: (context, index) {
    if (index == 15) {
      return AlignedTooltipEntry(
        scrollController: scrollController,
        child: ...,
        content: ...,
      );
    }
    return ListTile(title: Text('Item $index'));
  },
)

非覆盖式提示框

对于需要作为 widget 树一部分而不是覆盖层的提示框，你可以使用 AlignedTooltipEntry：

Scaffold(
  appBar: AppBar(title: Text('It goes under me')),
  body: AlignedTooltipArea(
    builder: (context, tooltip, scrim) {
      return Stack(
        fit: StackFit.passthrough,
        children: [
          ListView.builder(
            itemCount: 30,
            itemBuilder: (context, index) {
              if (index == 15) {
                return AlignedTooltipEntry(
                  tailLength: 10.0,
                  preferredDirection: AxisDirection.down,
                  isModal: true,
                  margin: EdgeInsets.all(20.0),
                  child: Material(
                    color: Colors.blue,
                    shape: CircleBorder(),
                    elevation: 4.0,
                    child: Padding(
                      padding: EdgeInsets.all(8.0),
                      child: Icon(Icons.touch_app, color: Colors.white),
                    ),
                  ),
                  content: Column(
                    mainAxisSize: MainAxisSize.min,
                    children: [
                      Container(
                        height: 120,
                        color: Colors.blue,
                        width: double.infinity,
                      ),
                      SizedBox(height: 8),
                      Text(
                        'Quia ducimus eius magni voluptatibus ut veniam ducimus. Ullam ab qui voluptatibus quos est in. Maiores eos ab magni tempora praesentium libero. Voluptate architecto rerum vel sapiente ducimus aut cumque quibusdam. Consequatur illo et quos vel cupiditate quis dolores at.',
                      ),
                    ],
                  ),
                );
              }
              return ListTile(title: Text('Item $index'));
            },
          ),
          scrim,
          tooltip,
        ],
      );
    },
  ),
);

通过以上介绍，你应该能够很好地理解和使用 aligned_tooltip 插件了。如果有任何问题或建议，欢迎提交 issue 或者 PR。