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

文章目录

• [1. 简介](#1. 简介)
• [2. 快速上手](#2. 快速上手)
• • [2.1. 安装插件](#2.1. 安装插件)
  • [2.2. 平台特殊配置（可选）](#2.2. 平台特殊配置（可选）)
  • • [iOS 配置（info.plist）](#iOS 配置（info.plist）)
    • [Android 配置（AndroidManifest.xml）](#Android 配置（AndroidManifest.xml）)
• [3. 核心用法](#3. 核心用法)
• • [3.1. 基础用法](#3.1. 基础用法)
  • [3.2. 样式定制](#3.2. 样式定制)
  • • [示例 1：带圆角和边框的 Toast](#示例 1：带圆角和边框的 Toast)
    • [示例 2：带图标的 Toast](#示例 2：带图标的 Toast)
    • [示例 3：全屏宽度 Toast（底部通栏）](#示例 3：全屏宽度 Toast（底部通栏）)
  • [3.3. 进阶用法](#3.3. 进阶用法)
  • • [场景 1：无上下文调用（全局可用）](#场景 1：无上下文调用（全局可用）)
    • [场景 2：自定义视图（复杂 Toast）](#场景 2：自定义视图（复杂 Toast）)
  • [3.4. Toast 关闭与监听](#3.4. Toast 关闭与监听)
  • • [主动关闭 Toast](#主动关闭 Toast)
    • [监听 Toast 状态（仅 Android）](#监听 Toast 状态（仅 Android）)
• [4. 跨平台差异与适配技巧](#4. 跨平台差异与适配技巧)
• [5. 常见问题与解决方案](#5. 常见问题与解决方案)
• • [Q1：iOS 自定义时长 Toast 不显示？](#Q1：iOS 自定义时长 Toast 不显示？)
  • [Q2：Toast 被键盘遮挡（底部位置）？](#Q2：Toast 被键盘遮挡（底部位置）？)
  • Q3：自定义视图（msgWidget）显示异常？
• [6. 总结](#6. 总结)

在移动应用开发中，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: flutter
  fluttertoast: ^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 {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("基础 Toast 示例")),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // 显示基础文本 Toast
            Fluttertoast.showToast(
              msg: "操作成功！", // 提示文本
              toastLength: Toast.LENGTH_SHORT, // 显示时长：SHORT(2s) / LONG(3.5s)
              gravity: ToastGravity.BOTTOM, // 显示位置：BOTTOM(默认) / CENTER / TOP
              timeInSecForIosWeb: 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
• 掘金