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

耳東陈
969 阅读5分钟

Flutter Chen Common

Pub VersionLicense

🌟 简介

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

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

特性

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

🚀 快速接入

安装依赖

在 pubspec.yaml 中添加依赖：

dependencies:
  flutter_chen_common: 最新版本

ComToast - 全局无需Context的Toast组件

特性

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

📱 效果预览

ComToast 效果预览

智能消息过滤

自动过滤空消息

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

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

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

防重复消息机制

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

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

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

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

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

快速开始

1. 初始化

在您的 MaterialApp 中使用 ComToastBuilder()：

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

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

2. 可选的全局配置

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

// 可选：设置全局配置
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：

// 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();

🔧 配置优先级

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

  1. 局部配置：调用时传入的 config 参数
  2. 全局配置：通过 ComToast.init() 设置的全局配置
  3. 默认主题：根据当前主题自动适配的默认值
// 全局配置（优先级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 - 自定义样式

配置参数

属性类型默认值描述
positionComToastPositioncenterToast位置
durationint2000显示时长（毫秒）
backgroundColorColor主题适配背景颜色（亮色主题下为深色，暗色主题下为浅色）
textColorColor主题适配文字颜色（与背景形成对比）
fontSizedouble14.0文字大小
paddingEdgeInsets(16, 12)内边距
borderRadiusdouble12.0圆角
iconIconData?null图标（内置类型有默认图标）
iconColorColor?状态色图标颜色（内置类型使用对应状态色）
animationDurationint300动画时长（毫秒）

主题适配说明：内置类型（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 文件了解完整的使用示例。

avatar
文章
阅读
粉丝