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. 常见问题与解决方案)
  • [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 命令行安装:

yaml 复制代码
dependencies:
  flutter:
    sdk: flutter
  fluttertoast: ^8.2.2  # 请使用 pub.dev 最新版本

执行安装命令:

bash 复制代码
flutter pub get

2.2. 平台特殊配置(可选)

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

iOS 配置(info.plist)

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

xml 复制代码
<key>NSUserNotificationUsageDescription</key>
<string>需要显示通知以提供 Toast 提示</string>

(注:iOS 10+ 中,自定义时长的 Toast 会以本地通知形式实现,需申请通知权限)

Android 配置(AndroidManifest.xml)

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

3. 核心用法

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

3.1. 基础用法

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

dart 复制代码
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

适用于需要突出显示的提示(如警告、重要通知):

dart 复制代码
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

通过 webShowCloseicon 参数添加图标,增强视觉反馈(如成功用 ✅、错误用 ❌):

dart 复制代码
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(底部通栏)

通过 backgroundColorgravity 实现底部通栏提示,适用于全局通知:

dart 复制代码
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 一次,或使用无上下文模式:

dart 复制代码
// 全局工具类中定义 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,完全摆脱文本限制:

dart 复制代码
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()

dart 复制代码
// 显示 Toast
Fluttertoast.showToast(msg: "正在处理...", toastLength: Toast.LENGTH_LONG);

// 3 秒后主动关闭
Future.delayed(Duration(seconds: 3), () {
  Fluttertoast.cancel();
});

监听 Toast 状态(仅 Android)

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

dart 复制代码
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,背景色避免过于鲜艳

适配实战示例

dart 复制代码
// 跨平台统一的 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:通过 webShowClosetoastLength 调整,或在键盘弹出时动态改变 Toast 位置:

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

Q3:自定义视图(msgWidget)显示异常?

A:确保 msgWidgetmainAxisSize 设为 MainAxisSize.min(避免占满屏幕),且尺寸不超过屏幕宽度的 80%;背景色建议设为不透明,避免与系统背景混合。

6. 总结

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

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

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


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

往期文章

个人主页

相关推荐
Mintopia4 小时前
Next.js 的 Web Vitals 监测与 Lighthouse 分析:从底层到实战的快乐科学
前端·javascript·next.js
charlie1145141914 小时前
前端三件套简单学习:HTML篇1
开发语言·前端·学习·html
很多石头4 小时前
前端img与background-image渲染图片对H5页面性能的影响
前端·css
yenggd4 小时前
3种XSS攻击简单案例
前端·xss
盖头盖4 小时前
【xss基本介绍】
前端·xss
守城小轩4 小时前
Firefox Android 开发环境搭建全流程(四)
android·firefox·chrome devtools·指纹浏览器·浏览器开发
一枚前端小能手4 小时前
「周更第2期」实用JS库推荐:Rsbuild
前端·javascript
小桥风满袖4 小时前
极简三分钟ES6 - 正则表达式的扩展
前端·javascript
袁美丽..5 小时前
Android --- AOSP源码导入Android Studio
android·android studio