qs_toast

qs_toast 是一个基于 flutter_easyloading 封装的 Flutter Toast 插件，提供加载中、文本、成功、错误提示以及手动关闭能力。

功能特性

显示加载中提示
显示普通文本 Toast
显示成功提示
显示错误提示
手动关闭当前提示
支持遮罩类型、显示时长和关闭回调
支持在已有 MaterialApp.builder 基础上初始化
支持加载提示去重，避免相同加载提示重复弹出

安装

在项目的 pubspec.yaml 中添加依赖：

dependencies:
  qs_toast: ^1.0.1

如果使用本地路径依赖：

dependencies:
  qs_toast:
    path: ../qs_toast

然后执行：

flutter pub get

初始化

使用前需要在 MaterialApp 的 builder 中调用 QsToast.init()：

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

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: QsToast.init(),
      home: const HomePage(),
    );
  }
}

如果项目已经配置了自定义 builder，可以通过 builder 参数传入原有逻辑：

MaterialApp(
  builder: QsToast.init(
    builder: (context, child) {
      return MediaQuery(
        data: MediaQuery.of(context),
        child: child ?? const SizedBox.shrink(),
      );
    },
  ),
  home: const HomePage(),
);

使用方法

加载中

await QsToast.loading(text: '加载中...');

如果当前已经显示相同文案的加载提示，会直接忽略本次调用；如果文案不同，会先关闭旧提示，再显示新的加载提示。

设置最长显示时间，超时后自动关闭：

await QsToast.loading(
  text: '提交中...',
  longestTime: 10,
  dismissAction: () {
    // 加载提示自动关闭后的回调
  },
);

文本提示

await QsToast.text(text: '操作已完成');

自定义显示时长：

await QsToast.text(
  text: '保存成功',
  duration: const Duration(seconds: 2),
);

成功提示

await QsToast.success(text: '提交成功');

错误提示

await QsToast.error(text: '提交失败，请稍后再试');

关闭提示

await QsToast.dismiss();

关闭后执行回调：

await QsToast.dismiss(
  dismissAction: () {
    // 提示关闭后的回调
  },
);

API

QsToast.init

参数	类型	默认值	说明
`builder`	`TransitionBuilder?`	`null`	已有的 `MaterialApp.builder` 逻辑

QsToast.loading

参数	类型	默认值	说明
`text`	`String?`	`null`	加载提示文案
`longestTime`	`int?`	`null`	最长显示时间，单位为秒。设置后到时自动关闭
`maskType`	`EasyLoadingMaskType`	`EasyLoadingMaskType.black`	遮罩类型
`dismissAction`	`VoidCallback?`	`null`	自动关闭后的回调

QsToast.text

参数	类型	默认值	说明
`text`	`String`	必填	文本提示文案
`maskType`	`EasyLoadingMaskType`	`EasyLoadingMaskType.black`	遮罩类型
`duration`	`Duration`	`Duration(seconds: 1)`	显示时长
`dismissAction`	`VoidCallback?`	`null`	关闭后的回调

QsToast.success

参数	类型	默认值	说明
`text`	`String`	必填	成功提示文案
`maskType`	`EasyLoadingMaskType`	`EasyLoadingMaskType.black`	遮罩类型
`duration`	`Duration`	`Duration(seconds: 1)`	显示时长
`dismissAction`	`VoidCallback?`	`null`	关闭后的回调

QsToast.error

参数	类型	默认值	说明
`text`	`String`	必填	错误提示文案
`maskType`	`EasyLoadingMaskType`	`EasyLoadingMaskType.black`	遮罩类型
`duration`	`Duration`	`Duration(seconds: 1)`	显示时长
`dismissAction`	`VoidCallback?`	`null`	关闭后的回调

QsToast.dismiss

参数	类型	默认值	说明
`animation`	`bool`	`true`	关闭时是否显示动画
`dismissAction`	`VoidCallback?`	`null`	关闭后的回调

maskType 来自 flutter_easyloading。如果需要使用其他遮罩类型，可以引入：

import 'package:flutter_easyloading/flutter_easyloading.dart';

示例：

await QsToast.success(
  text: '保存成功',
  maskType: EasyLoadingMaskType.clear,
);

完整示例

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

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: QsToast.init(),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('qs_toast 示例')),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: () {
                QsToast.loading(text: '加载中...', longestTime: 5);
              },
              child: const Text('显示加载'),
            ),
            ElevatedButton(
              onPressed: () {
                QsToast.text(text: '这是一条提示');
              },
              child: const Text('显示文本'),
            ),
            ElevatedButton(
              onPressed: () {
                QsToast.success(text: '操作成功');
              },
              child: const Text('显示成功'),
            ),
            ElevatedButton(
              onPressed: () {
                QsToast.error(text: '操作失败');
              },
              child: const Text('显示错误'),
            ),
            ElevatedButton(
              onPressed: () {
                QsToast.dismiss();
              },
              child: const Text('关闭提示'),
            ),
          ],
        ),
      ),
    );
  }
}

注意事项

QsToast.init() 必须配置在应用入口的 MaterialApp.builder 中。
loading 设置 longestTime 后会进入加载状态，到时会自动关闭；也可以通过 QsToast.dismiss() 主动关闭。
多次调用 loading 时，相同文案不会重复显示；不同文案会替换当前加载提示。
text、success、error 的 dismissAction 会在 duration 结束后触发。

运行示例

进入示例工程后运行：

cd example
flutter pub get
flutter run

平台支持

当前插件工程包含 Android 和 iOS 平台配置。

许可

本项目使用 LICENSE 文件中声明的许可证。