文章 · Flutter 提示与加载组件

提示与加载属于全局体验组件，最容易“各处乱用”。下面用 flutter_easyloading + bot_toast 搭建统一体系，并补充 EasyLoading 的常用高级配置。

0. 依赖

dependencies:
  flutter_easyloading: ^3.0.5
  bot_toast: ^4.0.4

1. 全局初始化

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) {
        final Widget easy = EasyLoading.init()(context, child);
        return BotToastInit()(context, easy);
      },
      navigatorObservers: [BotToastNavigatorObserver()],
      home: const HomePage(),
    );
  }
}

BotToastInit 与 BotToastNavigatorObserver 是官方推荐的初始化方式。 EasyLoading.init() 需要在 MaterialApp.builder 中注册。

2. 统一调用入口

class AppToast {
  static void show(String msg) => BotToast.showText(text: msg);
  static void loading([String? msg]) => EasyLoading.show(status: msg ?? '加载中');
  static void dismiss() => EasyLoading.dismiss();
}

3. 使用方式

AppToast.show('保存成功');
AppToast.loading('提交中');
AppToast.dismiss();

4. EasyLoading 常用用法

EasyLoading.show(status: '加载中');
EasyLoading.showProgress(0.6, status: '上传中');
EasyLoading.showSuccess('成功');
EasyLoading.showError('失败');
EasyLoading.showInfo('提示信息');
EasyLoading.showToast('Toast');
EasyLoading.dismiss();

5. 样式与遮罩配置

void configEasyLoading() {
  EasyLoading.instance
    ..loadingStyle = EasyLoadingStyle.dark
    ..indicatorType = EasyLoadingIndicatorType.fadingCircle
    ..maskType = EasyLoadingMaskType.none
    ..userInteractions = true
    ..dismissOnTap = false
    ..displayDuration = const Duration(milliseconds: 2000)
    ..animationStyle = EasyLoadingAnimationStyle.opacity;
}

如需自定义颜色，请切到 EasyLoadingStyle.custom。

6. 自定义指示器 / 动画

EasyLoading.instance
  ..indicatorWidget = const CircularProgressIndicator()
  ..successWidget = const Icon(Icons.check, color: Colors.green)
  ..errorWidget = const Icon(Icons.close, color: Colors.red);

7. 状态回调与日志

void Function(EasyLoadingStatus)? statusCallback;

statusCallback = (status) {
  Log.d('easyloading', status.toString());
};
EasyLoading.addStatusCallback(statusCallback!);
EasyLoading.removeCallback(statusCallback!);

8. 常见用法细节

8.1 进度提示

EasyLoading.showProgress(0.6, status: '上传中');

8.2 错误提示

BotToast.showText(text: '请求失败，请重试');

8.3 防止多次弹窗

EasyLoading.dismiss();
BotToast.cleanAll();

9. 常见坑点

builder 未初始化：未注册 EasyLoading.init() 会直接无效
Observer 缺失：未添加 BotToastNavigatorObserver 会导致遮罩异常
多次 show：重复调用需先 dismiss

10. 实践清单

统一入口封装
全局初始化
避免页面级重复实现