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

Flutter Chen Common

🌟 简介

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

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

特性

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

🚀 快速接入

安装依赖

在 pubspec.yaml 中添加依赖：

dependencies:
  flutter_chen_common: 最新版本

Toast 提示

🌟 特性

• 🚀 全局使用，无需传入 BuildContext
• 🎨 简洁的内置样式（成功、错误、警告、信息、加载）
• 🌈 自动适配主题颜色（背景色、文本色）
• ⚡ 平滑的淡入淡出动画效果
• 🪄 独立 Banner 语义，顶部横幅使用类 iOS 动画与布局
• 🎯 灵活的位置配置
• 📱 支持自定义内容
• 🔧 完全可配置
• 🛡️ 智能消息过滤（空消息、重复消息）

📱 效果预览

🚀 快速开始

初始化配置

在 MaterialApp 中配置：

MaterialApp(
  navigatorObservers: [ComToastNavigatorObserver()],
)

基础使用

// 普通提示
ComToast.show('这是一条普通提示');

// 成功提示
ComToast.success('操作成功');

// 错误提示
ComToast.error('操作失败');

// 警告提示
ComToast.warning('请注意');

// 信息提示
ComToast.info('这是一条信息');

// 顶部横幅 Banner（推荐）
ComToast.banner(
  message: '网络已恢复',
  titleText: '连接状态',
);

// 语义化 Banner
ComToast.successBanner(
  message: '文件已上传',
  titleText: '上传成功',
);

// Widget 化标题 / 副标题
ComToast.banner(
  title: const Text('同步完成'),
  subtitle: const Text('3 个文件已更新'),
);

// 关闭Toast
ComToast.dismiss();

🎨 自定义配置

自定义样式

ComToast.show(
  '自定义Toast',
  config: ComToastConfig(
    duration: const Duration(seconds: 3),
    position: ComToastPosition.center,
    backgroundColor: Colors.black87,
    textColor: Colors.white,
    fontSize: 16.0,
    padding: const EdgeInsets.symmetric(horizontal: 16.0, vertical: 10.0),
    borderRadius: 8.0,
    maxWidth: 200.0,
    showShadow: true,
  ),
);

ComToast.init(
  theme: const ComToastTheme(
    toast: ComToastStateTheme(
      base: ComToastConfig(
        duration: Duration(seconds: 2),
        position: ComToastPosition.bottom,
      ),
      success: ComToastConfig(
        iconWidget:
            Icon(Icons.check_circle, color: Color(0xFF10B981), size: 20),
      ),
      error: ComToastConfig(
        iconWidget: Icon(Icons.cancel, color: Color(0xFFEF4444), size: 20),
      ),
      warning: ComToastConfig(
        iconWidget:
            Icon(Icons.priority_high, color: Color(0xFFF59E0B), size: 20),
      ),
      info: ComToastConfig(
        iconWidget:
            Icon(Icons.info_outline, color: Color(0xFF3B82F6), size: 20),
      ),
    ),
    banner: ComToastStateTheme(
      base: ComToastConfig(
        showCloseButton: true,
        topMargin: 16,
      ),
      success: ComToastConfig(
        iconWidget:
            Icon(Icons.check_circle, color: Color(0xFF10B981), size: 20),
      ),
      error: ComToastConfig(
        iconWidget: Icon(Icons.cancel, color: Color(0xFFEF4444), size: 20),
      ),
    ),
    loading: ComToastConfig(
      builder: (ctx) => const SizedBox(
        width: 120,
        child: ComLoading(),
      ),
      clickThrough: false,
      duration: Duration.zero,
    ),
  ),
);

自定义内容

ComToast.custom(
  builder: (context) => Container(
    padding: const EdgeInsets.all(16),
    decoration: BoxDecoration(
      color: Colors.black87,
      borderRadius: BorderRadius.circular(8),
    ),
    child: Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        Icon(Icons.star, color: Colors.yellow),
        const SizedBox(width: 8),
        Text('自定义Toast', style: TextStyle(color: Colors.white)),
      ],
    ),
  ),
);

⚡ Loading 功能

基础使用

// 显示Loading
ComToast.loading(message: '加载中...');

// 隐藏Loading
ComToast.hideLoading();

// 自动处理Loading的异步操作
final result = await ComToast.autoLoading(
  () => api.getData(),
  message: '加载数据中...',
);

自定义 Loading

ComToast.customLoading(
  builder: (context) => Container(
    padding: const EdgeInsets.all(16),
    decoration: BoxDecoration(
      color: Colors.black87,
      borderRadius: BorderRadius.circular(8),
    ),
    child: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        CircularProgressIndicator(color: Colors.white),
        const SizedBox(height: 8),
        Text('自定义Loading', style: TextStyle(color: Colors.white)),
      ],
    ),
  ),
);

🔧 高级配置

全局配置

ComToast.init(
  theme: const ComToastTheme(
    toast: ComToastStateTheme(
      base: ComToastConfig(
        duration: Duration(seconds: 2),
        position: ComToastPosition.bottom,
      ),
    ),
    banner: ComToastStateTheme(
      base: ComToastConfig(
        showCloseButton: true,
      ),
    ),
  ),
);

消息过滤

// 设置重复消息过滤时间（毫秒）
ComToast.setDuplicateFilterDuration(1000);

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

其他功能

// 关闭当前显示的Toast
ComToast.dismiss();

📚 API 参考

设计建议

• ComToast.show/success/error/info：用于轻量、短暂、非阻断提示
• ComToast.banner/successBanner/errorBanner/...：用于顶部状态通知、系统结果反馈
• ComToast.loading：用于阻断式等待反馈
• Banner 支持上滑关闭与顺序切换显示，体验更接近系统通知
• 全局推荐通过 ComToastTheme 分别配置 toast / banner / loading

ComToastConfig

参数	类型	默认值	描述
duration	Duration	1.5秒	显示时长
position	ComToastPosition	center	显示位置
backgroundColor	Color	主题色	背景颜色
textColor	Color	白色	文字颜色
fontSize	double	14.0	文字大小
padding	EdgeInsets	16.0	内边距
borderRadius	double	12.0	圆角大小
maxWidth	double	0.85	最大宽度，<= 1 时按屏宽比例，> 1 时按像素值
showShadow	bool	true	是否显示阴影
presentation	ComToastPresentation	toast	展示语义，banner 会使用顶部横幅布局
showCloseButton	bool	false	Banner 是否显示关闭按钮
topMargin	double	12.0	顶部 Toast 与安全区的默认间距

ComToastTheme

• toast：普通 Toast 的分状态主题，支持 base / normal / success / error / warning / info
• banner：顶部 Banner 的分状态主题，支持 base / normal / success / error / warning / info
• loading：Loading 的全局配置

ComToastPosition

值	描述
top	顶部显示
center	中间显示
bottom	底部显示