Flutter开箱即用一站式解决方案2.0-全局无需Context的Toast

Flutter Chen Common

🌟 简介

本库为Flutter应用开发提供一站式解决方案，包含：

可定制的主题系统
完整的国际化支持
企业级网络请求封装
企业级日志体系封装
N+高质量常用组件
常用开发工具及扩展集合
智能刷新列表解决方案
开箱即用的各类通用弹窗
全局统一各状态布局

特性

🎨 主题系统 ：通过 ThemeExtension 全局配置颜色/圆角/间距等样式
🌍 国际化支持：内置中英文，支持自定义文本和动态语言切换
⚡ 优先级覆盖：支持全局配置 + 组件级参数覆盖
📱 自适应设计：完美适配 iOS/Material 设计规范
🔥 企业级方案：内置日志/网络/安全等通用模块，提供开箱即用的复杂场景解决方案

🚀 快速接入

安装依赖

在 pubspec.yaml 中添加依赖：

yaml 复制代码

dependencies:
  flutter_chen_common: 最新版本

ComToast - 全局无需Context的Toast组件

特性

🚀 全局使用，无需传入 BuildContext
🎨 简洁的内置样式（成功、错误、警告、信息、加载）
🌈 自动适配主题颜色（背景色、文本色）
⚡ 平滑的淡入淡出动画效果
🎯 灵活的位置配置
📱 支持自定义内容
🔧 完全可配置
��️ 智能消息过滤（空消息、重复消息）
🔄 支持自动化异步加载状态

智能消息过滤

自动过滤空消息

Toast会自动过滤空字符串和只包含空白字符的消息：

dart 复制代码

ComToast.show(''); // 不会显示
ComToast.show('   '); // 不会显示
ComToast.show('Hello'); // 正常显示

// 注意：custom类型不受空消息过滤影响，因为它们使用builder构建内容
ComToast.custom(
  builder: (context) => Container(
    child: Text('自定义内容'),
  ),
); // 正常显示，即使message为空

防重复消息机制

默认情况下，1秒内相同的消息会被自动过滤，避免用户误操作导致的重复提示：

dart 复制代码

ComToast.success('操作成功'); 
ComToast.success('操作成功'); // 1秒内不会重复显示

// 可以跳过重复过滤
ComToast.success('操作成功', skipDuplicateFilter: true); // 强制显示

// 配置过滤时间（毫秒）
ComToast.setDuplicateFilterDuration(2000); // 改为2秒

// 清除过滤缓存
ComToast.clearMessageFilter();

快速开始

1. 初始化

在您的 MaterialApp 中使用 ComToastBuilder()：

dart 复制代码

import 'package:module_base/toast/toast.dart';

MaterialApp(
  title: 'Flutter Demo',
  builder: ComToastBuilder(),
  navigatorObservers: [
    ComToastNavigatorObserver(),
  ],
  home: MyHomePage(),
);

2. 可选的全局配置

无需强制初始化 ：Toast可以直接使用，ComToast.init() 是可选的：

dart 复制代码

// 可选：设置全局配置
void main() {
  // 如果不调用 init()，Toast 会使用默认配置
  ComToast.init(config: ComToastConfig(
    duration: 3000,
    fontSize: 16.0,
    // backgroundColor 和 textColor 留空，使用主题适配
  ));
  
  // 可选：配置消息过滤
  ComToast.setDuplicateFilterDuration(1500); // 1.5秒内相同消息过滤
  
  runApp(MyApp());
}

3. 使用 Toast

现在您可以在应用的任何地方使用 Toast，无需传入 BuildContext：

dart 复制代码

// Toast基础用法（自动主题适配 + 消息过滤）
ComToast.show('Hello World!');
// 内置样式（自动主题适配 + 彩色图标 + 消息过滤）
ComToast.success('操作成功！');
ComToast.error('出现错误！');
ComToast.warning('警告信息！');
ComToast.info('提示信息！');
// 跳过重复消息过滤
ComToast.success('强制显示', skipDuplicateFilter: true);
// 局部配置覆盖全局配置
ComToast.success('成功！', config: ComToastConfig(
  duration: 1500, // 覆盖全局配置
  backgroundColor: Colors.green, // 覆盖主题适配，使用固定颜色
));
// 自定义Toast
ComToast.custom(builder: (context) => Container());

// Loading基础用法
ComToast.loading(); 
ComToast.loading('加载中...'); 
ComToast.customLoading(builder: (context) => Container()); 
// 自动化Loading
void showTemporaryLoading() {
  final result = await ComToast.autoLoading(
    () => _mockAsyncOperation(),
    message: '自动Loading测试中...',
  );
}

// 关闭 Toast
ComToast.dismiss();
// 关闭 Loading
ComToast.hideLoading();

🔧 配置优先级

配置按以下优先级应用（高优先级覆盖低优先级）：

局部配置 ：调用时传入的 config 参数
全局配置 ：通过 ComToast.init() 设置的全局配置
默认主题：根据当前主题自动适配的默认值

dart 复制代码

// 全局配置（优先级2）
ComToast.init(config: ComToastConfig(
  duration: 3000,
  fontSize: 16.0,
));

// 局部配置（优先级1，会覆盖全局配置）
ComToast.success('成功！', config: ComToastConfig(
  duration: 1500,
  position: ComToastPosition.top,
));

🌈 智能主题适配

自动检测：自动检测当前主题的明暗模式
动态适配：Toast背景和文字会根据主题自动调整
保持对比：始终保持与主题的反差，确保用户注意
灵活定制：可通过配置覆盖自动适配的颜色

配置选项

ComToastPosition（位置）

top - 顶部显示
center - 中央显示（默认）
bottom - 底部显示

ComToastType（类型）

normal - 普通样式（使用配置的背景色和文字色）
success - 成功样式（绿色图标 + 文字）
error - 错误样式（红色图标 + 文字）
warning - 警告样式（橙色图标 + 文字）
info - 信息样式（蓝色图标 + 文字）
loading - 加载样式（旋转动画 + 文字）
custom - 自定义样式

配置参数

属性	类型	默认值	描述
`position`	`ComToastPosition`	`center`	Toast位置
`duration`	`int`	`2000`	显示时长（毫秒）
`backgroundColor`	`Color`	主题适配	背景颜色（亮色主题下为深色，暗色主题下为浅色）
`textColor`	`Color`	主题适配	文字颜色（与背景形成对比）
`fontSize`	`double`	`14.0`	文字大小
`padding`	`EdgeInsets`	`(16, 12)`	内边距
`borderRadius`	`double`	`12.0`	圆角
`icon`	`IconData?`	`null`	图标（内置类型有默认图标）
`iconColor`	`Color?`	状态色	图标颜色（内置类型使用对应状态色）
`animationDuration`	`int`	`300`	动画时长（毫秒）

主题适配说明 ：内置类型（success/error/warning/info）会自动根据当前主题选择背景色和文字色，确保与主题形成对比。如需固定颜色，请明确指定 backgroundColor 和 textColor。

内置图标和颜色

成功样式

图标：Icons.check_circle
图标颜色：#10B981（绿色）

错误样式

图标：Icons.error
图标颜色：#EF4444（红色）

警告样式

图标：Icons.warning
图标颜色：#F59E0B（橙色）

信息样式

图标：Icons.info
图标颜色：#3B82F6（蓝色）

加载样式

图标：动画⏳
图标颜色：主题适配

注意事项

确保在 MaterialApp 中正确配置了 ComToastBuilder()
确保在 MaterialApp 中正确配置了 ComToastNavigatorObserver()
确保正确初始化了 ComContext.init(navigatorKey)
内置样式会自动适配主题对比，如需完全自定义请明确指定颜色
配置优先级：局部配置 > 全局配置 > 默认主题适配
在自定义 Widget 中使用时，确保应用已经完成初始化
使用Loading状态时注意处理异常情况，确保Loading状态能够正确关闭

示例项目

查看 toast_page.dart 文件了解完整的使用示例。