flutter-使用fluttertoast制作丰富的高颜值toast

在移动应用开发中，Toast 是传递轻量信息的核心组件——从操作成功反馈到错误提示，都离不开它的身影。Flutter 原生 Toast 功能简陋（仅支持文本、无样式定制），而 fluttertoast 插件彻底解决了这一痛点：支持自定义样式、位置、动画，甚至能显示图标、长期驻留提示，让 Toast 从“基础工具”升级为“交互增强组件”。本文将从安装到实战，带你掌握 fluttertoast 的全场景用法。

1. 简介

fluttertoast 是 Flutter 生态中最受欢迎的 Toast 增强插件之一，截至 2024 年 5 月，GitHub 星标超 3k，支持 Android、iOS 双平台，核心优势如下：

• ✨ 样式全定制：支持自定义背景色、文本色、字体大小、圆角、边框；
• 📌 灵活定位：可设置 Toast 在屏幕顶部、中部、底部，还能微调偏移量；
• ⏱️ 时长控制：支持“短提示（short）”“长提示（long）”，甚至自定义显示时长；
• 🎨 多媒体支持：可在 Toast 中嵌入图标（Icon），增强视觉辨识度；
• 🚀 无上下文依赖：部分用法无需传入 BuildContext，在全局任意位置均可调用；
• 📱 平台适配：自动适配 Android/iOS 原生风格，也可强制统一跨平台样式。

2. 快速上手

2.1. 安装插件

在 pubspec.yaml 文件中添加依赖，或通过 Flutter 命令行安装：

dependencies:flutter:sdk: flutterfluttertoast: ^8.2.2  # 请使用 pub.dev 最新版本

执行安装命令：

flutter pub get

2.2. 平台特殊配置（可选）

fluttertoast 大部分功能无需额外配置，仅在需要“长期驻留 Toast”（toastLength: Toast.LENGTH_LONG 之外的自定义时长）或“iOS 平台特定样式”时，需添加以下配置：

iOS 配置（info.plist）

若需要支持自定义时长，在 ios/Runner/Info.plist 中添加权限：

<key>NSUserNotificationUsageDescription</key>
<string>需要显示通知以提供 Toast 提示</string>

（注：iOS 10+ 中，自定义时长的 Toast 会以本地通知形式实现，需申请通知权限）

Android 配置（AndroidManifest.xml）

无需额外配置，插件会自动适配 Android 原生 Toast 机制。

3. 核心用法

fluttertoast 的核心 API 是 Fluttertoast.showToast() 静态方法，通过传入不同参数实现多样化效果。下面按“基础 → 样式 → 进阶”的顺序讲解。

3.1. 基础用法

最简单的 Toast 仅需设置文本内容，适用于“操作成功”“参数错误”等基础场景：

import 'package:flutter/material.dart';
import 'package:fluttertoast/fluttertoast.dart';class BasicToastDemo extends StatelessWidget {@overrideWidget build(BuildContext context) {return Scaffold(appBar: AppBar(title: Text("基础 Toast 示例")),body: Center(child: ElevatedButton(onPressed: () {// 显示基础文本 ToastFluttertoast.showToast(msg: "操作成功！", // 提示文本toastLength: Toast.LENGTH_SHORT, // 显示时长：SHORT(2s) / LONG(3.5s)gravity: ToastGravity.BOTTOM, // 显示位置：BOTTOM(默认) / CENTER / TOPtimeInSecForIosWeb: 2, // iOS/Web 平台自定义时长（秒），Android 不生效backgroundColor: Colors.grey[800], // 背景色textColor: Colors.white, // 文本色fontSize: 16.0, // 文本字体大小);},child: Text("显示基础 Toast"),),),);}
}

关键参数说明：

• msg：必传，Toast 显示的文本内容（支持多行文本，用 \n 分隔）；
• toastLength：控制显示时长，仅支持 Toast.LENGTH_SHORT（2 秒）和 Toast.LENGTH_LONG（3.5 秒），若需更长时间，需结合 timeInSecForIosWeb（仅 iOS/Web 生效）；
• gravity：控制显示位置，可选值：ToastGravity.TOP（顶部）、ToastGravity.CENTER（中部）、ToastGravity.BOTTOM（底部，默认）。

3.2. 样式定制

fluttertoast 支持自定义背景、圆角、边框，甚至添加图标，让 Toast 更贴合 App 整体风格。

示例 1：带圆角和边框的 Toast

适用于需要突出显示的提示（如警告、重要通知）：

Fluttertoast.showToast(msg: "警告：请填写完整信息！",toastLength: Toast.LENGTH_SHORT,gravity: ToastGravity.CENTER,backgroundColor: Colors.yellow[50], // 浅黄色背景textColor: Colors.orange[800], // 橙色文本fontSize: 14.0,// 自定义边框border: Border.all(color: Colors.orange[300]!, // 边框颜色width: 1.0, // 边框宽度),borderRadius: 8.0, // 圆角半径
);

示例 2：带图标的 Toast

通过 webShowClose 和 icon 参数添加图标，增强视觉反馈（如成功用 ✅、错误用 ❌）：

Fluttertoast.showToast(msg: "登录成功！",toastLength: Toast.LENGTH_SHORT,gravity: ToastGravity.TOP,backgroundColor: Colors.green[50],textColor: Colors.green[800],fontSize: 16.0,// 添加图标（仅 Android 支持，iOS 需结合自定义视图）icon: Icons.check_circle, // 图标iconColor: Colors.green[600], // 图标颜色// 图标大小（需配合 icon 使用）iconSize: 24.0,
);

示例 3：全屏宽度 Toast（底部通栏）

通过 backgroundColor 和 gravity 实现底部通栏提示，适用于全局通知：

Fluttertoast.showToast(msg: "正在加载数据...",toastLength: Toast.LENGTH_LONG,gravity: ToastGravity.BOTTOM,backgroundColor: Colors.blue[600],textColor: Colors.white,fontSize: 16.0,// 取消圆角，实现通栏效果borderRadius: 0.0,// 调整内边距，让文本居中且有足够空间padding: EdgeInsets.symmetric(vertical: 12.0, horizontal: 16.0),
);

3.3. 进阶用法

场景 1：无上下文调用（全局可用）

fluttertoast 支持在无 BuildContext 的场景（如网络请求回调、全局工具类）中调用，只需确保初始化时传入 context 一次，或使用无上下文模式：

// 全局工具类中定义 Toast 方法
class ToastUtil {static void showSuccess(String msg) {Fluttertoast.showToast(msg: msg,toastLength: Toast.LENGTH_SHORT,gravity: ToastGravity.CENTER,backgroundColor: Colors.green[500],textColor: Colors.white,);}static void showError(String msg) {Fluttertoast.showToast(msg: msg,toastLength: Toast.LENGTH_SHORT,gravity: ToastGravity.CENTER,backgroundColor: Colors.red[500],textColor: Colors.white,);}
}// 在任意地方调用（无需上下文）
ToastUtil.showSuccess("数据提交成功！");
ToastUtil.showError("网络连接失败，请重试");

场景 2：自定义视图（复杂 Toast）

若需要更复杂的 Toast（如带进度条、图片、多控件组合），fluttertoast 支持通过 msgWidget 参数传入自定义 Widget，完全摆脱文本限制：

Fluttertoast.showToast(// 自定义视图：图标 + 文本 + 进度条msgWidget: Container(padding: EdgeInsets.all(12.0),decoration: BoxDecoration(color: Colors.white,borderRadius: BorderRadius.circular(8.0),boxShadow: [BoxShadow(color: Colors.black12,blurRadius: 4.0,offset: Offset(0, 2),)],),child: Column(mainAxisSize: MainAxisSize.min, // 最小化列高度children: [Icon(Icons.download, color: Colors.blue, size: 28.0),SizedBox(height: 8.0),Text("下载进度：60%", style: TextStyle(fontSize: 14.0)),SizedBox(height: 8.0),LinearProgressIndicator(value: 0.6,color: Colors.blue,backgroundColor: Colors.grey[200],borderRadius: BorderRadius.circular(4.0),),],),),toastLength: Toast.LENGTH_LONG,gravity: ToastGravity.CENTER,// 取消默认背景（避免与自定义视图冲突）backgroundColor: Colors.transparent,
);

注意：msgWidget 优先级高于 msg，设置 msgWidget 后，msg 参数会失效；自定义视图需自己控制尺寸，避免过大导致显示异常。

3.4. Toast 关闭与监听

主动关闭 Toast

若需要在 Toast 显示期间主动关闭（如页面跳转时），可调用 Fluttertoast.cancel()：

// 显示 Toast
Fluttertoast.showToast(msg: "正在处理...", toastLength: Toast.LENGTH_LONG);// 3 秒后主动关闭
Future.delayed(Duration(seconds: 3), () {Fluttertoast.cancel();
});

监听 Toast 状态（仅 Android）

通过 onTap 参数监听 Toast 点击事件，实现点击 Toast 跳转页面等交互：

Fluttertoast.showToast(msg: "点击查看详情",toastLength: Toast.LENGTH_LONG,gravity: ToastGravity.CENTER,backgroundColor: Colors.blue[500],textColor: Colors.white,// 点击 Toast 触发的回调onTap: () {print("Toast 被点击了");// 跳转页面（需确保有上下文，或使用全局导航）Navigator.pushNamed(context, "/detail");},
);

4. 跨平台差异与适配技巧

fluttertoast 在 Android 和 iOS 平台的实现机制不同，存在部分差异，需注意适配：

功能点	Android 表现	iOS 表现	适配建议
自定义时长	仅支持 SHORT/LONG，timeInSecForIosWeb 不生效	支持任意时长（通过本地通知实现）	优先使用 SHORT/LONG，iOS 自定义时长需申请通知权限
图标（icon 参数）	支持显示图标	不支持，需通过 msgWidget 自定义	跨平台图标用 msgWidget 实现统一效果
点击事件（onTap）	支持	不支持（本地通知点击需单独处理）	iOS 点击提示建议用本地通知插件配合
背景色/圆角	完全支持自定义	部分样式受系统限制（如圆角最大 16px）	圆角不超过 16px，背景色避免过于鲜艳

适配实战示例：

// 跨平台统一的 Toast 工具方法
void showCrossPlatformToast({required String msg,required BuildContext context,
}) {Fluttertoast.showToast(msg: msg,toastLength: Toast.LENGTH_SHORT,gravity: ToastGravity.BOTTOM,// 适配 iOS 圆角限制borderRadius: 12.0, // 不超过 16px// 区分平台设置背景色backgroundColor: Theme.of(context).platform == TargetPlatform.iOS? Colors.grey[800]: Colors.grey[700],textColor: Colors.white,fontSize: 14.0,// iOS 用 msgWidget 实现图标（Android 用 icon）msgWidget: Theme.of(context).platform == TargetPlatform.iOS? Row(mainAxisSize: MainAxisSize.min,children: [Icon(Icons.info, color: Colors.white, size: 18.0),SizedBox(width: 8.0),Text(msg),],): null,icon: Theme.of(context).platform == TargetPlatform.android? Icons.info: null,);
}

5. 常见问题与解决方案

Q1：iOS 自定义时长 Toast 不显示？

A：需在 info.plist 中添加通知权限（见“平台特殊配置”），且需用户允许通知；若仍不显示，检查是否在后台线程调用，需确保在主线程执行 Fluttertoast.showToast()。

Q2：Toast 被键盘遮挡（底部位置）？

A：通过 webShowClose 或 toastLength 调整，或在键盘弹出时动态改变 Toast 位置：

Fluttertoast.showToast(msg: "请输入手机号",gravity: MediaQuery.of(context).viewInsets.bottom > 0? ToastGravity.CENTER // 键盘弹出时显示在中部: ToastGravity.BOTTOM, // 键盘收起时显示在底部
);

Q3：自定义视图（msgWidget）显示异常？

A：确保 msgWidget 的 mainAxisSize 设为 MainAxisSize.min（避免占满屏幕），且尺寸不超过屏幕宽度的 80%；背景色建议设为不透明，避免与系统背景混合。

6. 总结

fluttertoast 凭借“高定制性、跨平台兼容、无上下文依赖”三大优势，成为 Flutter 项目中 Toast 组件的首选。从基础文本提示到复杂自定义视图，从固定时长到主动关闭，它几乎覆盖了所有 Toast 使用场景。

在实际开发中，建议封装全局 Toast 工具类（如本文中的 ToastUtil），统一 App 内所有 Toast 的样式和行为，既提升开发效率，也保证用户体验一致性。如果需要更复杂的交互（如带按钮的提示），可结合 fluttertoast 与 showDialog 实现，进一步丰富 App 的反馈机制。

想要了解更多细节，可查看 fluttertoast 官方文档，或在 GitHub 仓库提交 issue 获取支持。

---

本次分享就到这儿啦，我是鹏多多，如果您看了觉得有帮助，欢迎评论，关注，点赞，转发，我们下次见~

往期文章

• flutter-获取父容器宽高及设置子元素百分比尺寸的教程
• flutter-本地存储和数据持久化全解析
• vue中ref的详解以及react的ref对比
• css使用aspect-ratio制作4:3和9:16和1:1等等比例布局
• Web前端页面开发阿拉伯语种适配指南
• flutter-使用extended_image操作图片的加载和状态处理以及缓存和下载
• flutter-制作可缩放底部弹出抽屉评论区效果
• flutter-实现Tabs吸顶的PageView效果
• Vue2全家桶+Element搭建的PC端在线音乐网站
• 助你上手Vue3全家桶之Vue3教程
• 超详细！vue组件通信的10种方式
• 超详细！Vuex手把手教程
• 使用nvm管理node.js版本以及更换npm淘宝镜像源
• vue中利用.env文件存储全局环境变量，以及配置vue启动和打包命令

个人主页

• CSDN
• GitHub
• 掘金