1. 添加依赖

在 pubspec.yaml 中添加最新版本（fluttertoast）：

dependencies:
  fluttertoast: ^8.2.11

示例图：

运行 flutter pub get

示例图

---

2. 平台配置

Android

确保 android/app/build.gradle 中启用 AndroidX：

android {
  compileSdkVersion 33
  // ...
  defaultConfig {
    minSdkVersion 21
    targetSdkVersion 33
  }
}

iOS

无需额外配置

---

3. 基础使用方法

显示简单 Toast

import 'package:fluttertoast/fluttertoast.dart';

Fluttertoast.showToast(
  msg: "操作成功",
  toastLength: Toast.LENGTH_SHORT,
  gravity: ToastGravity.BOTTOM,
);

完整参数示例

Fluttertoast.showToast(
  msg: "文件保存至 /Documents 文件夹",
  toastLength: Toast.LENGTH_LONG,  // 显示时长
  gravity: ToastGravity.CENTER,    // 位置：TOP/CENTER/BOTTOM
  backgroundColor: Colors.black54,
  textColor: Colors.white,
  fontSize: 16.0,
  timeInSecForIosWeb: 3,           // iOS/Web 显示时长（秒）
  webBgColor: "#333333",           // Web 背景色
  webPosition: "center",           // Web 位置：left/center/right
);

---

4. 高级配置

自定义样式

Fluttertoast.showToast(
  msg: "网络连接失败",
  backgroundColor: Colors.red[300],
  textColor: Colors.white,
  fontSize: 14.0,
  borderRadius: 20.0,            // 圆角半径
  borderWidth: 2.0,              // 边框宽度
  borderColor: Colors.red[700]!, // 边框颜色
  webShowClose: true,            // Web 显示关闭按钮
  webPosition: "top-center",     // Web 顶部居中
);

渐变背景

Fluttertoast.showToast(
  msg: "高级样式 Toast",
  backgroundColor: Colors.blue,
  backgroundGradient: const LinearGradient(
    colors: [Colors.blueAccent, Colors.lightBlue],
  ),
);

---

5. 封装工具类

class ToastUtil {
  static void showSuccess(String msg) {
    Fluttertoast.showToast(
      msg: msg,
      backgroundColor: Colors.green,
      textColor: Colors.white,
      gravity: ToastGravity.TOP,
    );
  }

  static void showError(String msg) {
    Fluttertoast.showToast(
      msg: msg,
      backgroundColor: Colors.red,
      textColor: Colors.white,
      gravity: ToastGravity.CENTER,
    );
  }

  static void cancelAll() {
    Fluttertoast.cancel();
  }
}

// 使用示例
ToastUtil.showSuccess("保存成功");

---

6.支持平台

• Android
• IOS
• Web (Uses Toastify-JS)

7. 注意事项

常见问题处理

问题现象	解决方案
Android 不显示	检查是否配置 minSdkVersion >= 21
Web 样式异常	使用 webBgColor 替代 backgroundColor
多次触发重叠	调用 Fluttertoast.cancel() 取消旧 Toast

性能优化

// 避免频繁调用
bool _isToastShowing = false;

void safeShowToast(String msg) {
  if (!_isToastShowing) {
    _isToastShowing = true;
    Fluttertoast.showToast(
      msg: msg,
    ).then((_) => _isToastShowing = false);
  }
}

---

8. 替代方案（推荐）

如果遇到兼容性问题，可考虑以下替代库：

dependencies:
  toast: ^2.0.0  # 更轻量的实现
  oktoast: ^3.3.0 # 支持自定义 Widget

---

通过合理使用 fluttertoast，可以快速实现符合 Material Design 规范的提示消息系统。建议根据应用主题统一封装 Toast 样式，避免在业务代码中直接调用原生方法。