Flutter加载状态管理插件loading_state_handler的使用

loading_state_handler 是一个强大的Flutter插件，用于管理UI状态，并内置了重试功能。这个插件优雅地处理了加载、错误、空数据和正常状态，并提供了可定制的重试机制和冷却支持。

特性

• 🔄 智能状态管理（加载、错误、空数据、正常）
• ⏲️ 内置重试机制与可配置冷却时间
• 🎨 为每种状态完全自定义的部件
• 🌐 全局默认配置
• ⚡ 使用常量构造函数优化性能
• 🎯 类型安全回调和构建器

安装

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  flutter:
    sdk: flutter
  loading_state_handler: ^1.3.3

快速开始

设置全局默认值（可选）

LoadingStateHandlerWidget.setDefaults(
  defaultRetryCooldown: const Duration(seconds: 5),
  defaultLoadingBuilder: (context, loadingMessage) =>
        const Center(child: CircularProgressIndicator()),
);

在你的组件中使用

LoadingStateHandlerWidget(
  currentState: CurrentStateEnum.error,
  errorMessage: 'Failed to load data',
  enableRetry: true,
  retryCooldown: const Duration(seconds: 3),
  onRetry: () => fetchData(),
  child: YourWidget(),
);

高级用法

重试机制

包含复杂的重试机制和冷却时间：

LoadingStateHandlerWidget(
  currentState: CurrentStateEnum.error,
  errorMessage: 'Network error occurred',
  enableRetry: true,
  retryCooldown: const Duration(seconds: 3),
  onRetry: () async {
    await refetchData();
  },
  child: ContentWidget(),
);

全局配置

设置所有实例的默认行为：

LoadingStateHandlerWidget.setDefaults(
  defaultRetryCooldown: const Duration(seconds: 5),
  defaultLoadingBuilder: (context, message) => CustomLoadingWidget(),
  defaultErrorBuilder: (context, message) => CustomErrorWidget(),
  defaultEmptyBuilder: (context, message) => CustomEmptyWidget(),
);

状态特定的回调

通过自定义回调处理不同状态：

LoadingStateHandlerWidget(
  loading: isLoading,
  error: hasError,
  empty: isEmpty,
  onLoading: (defaultCallback, context, message) {
    // 自定义加载行为
  },
  onError: (defaultCallback, context, message) {
    // 自定义错误处理
  },
  onEmpty: (defaultCallback, context, message) {
    // 自定义空状态处理
  },
  child: ContentWidget(),
);

禁用状态更改

细粒度控制小部件的行为：

LoadingStateHandlerWidget(
  disableWidgetChanges: false,
  disableErrorWidgetChanges: true,
  disableEmptyWidgetChanges: false,
  // ...其他属性
);

示例代码

以下是一个完整的示例应用，展示了如何使用 loading_state_handler 插件：

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

void main() {
  LoadingStateHandlerWidget.setDefaults(
    defaultOnData: (context, message) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(message ?? 'Default Got Data...')),
      );
    },
    defaultOnLoading: (context, message) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(message ?? 'Default Loading...')),
      );
    },
    defaultLoadingBuilder: (context, loadingMessage) =>
        const Center(child: CircularProgressIndicator()),
    defaultErrorBuilder: (context, errorMessage, retryWidget, retryCooldown, onRetry) => Center(
      child: Text('Custom Error: $errorMessage', style: const TextStyle(color: Colors.red)),
    ),
    defaultEmptyBuilder: (context, emptyMessage) => const Center(
      child: Text('No Data Available'),
    ),
  );

  runApp(const MyApp());
}

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  HomeScreenState createState() => HomeScreenState();
}

class HomeScreenState extends State<HomeScreen> {
  bool empty = false;
  bool error = false;
  String? errorMessage;
  bool loading = true;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Loading State Handler Example')),
      body: LoadingStateHandlerWidget(
        loading: loading,
        onLoading: (defaultOnLoading, context, message) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text(message ?? 'Custom Loading...')),
          );
        },
        onData: (defaultOnData, context, message) {
          defaultOnData?.call(context, message);
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text(message ?? 'Custom Got Data...')),
          );
        },
        error: error,
        errorMessage: errorMessage,
        empty: empty,
        child: const Center(child: Text('Data Loaded Successfully!')),
      ),
    );
  }

  @override
  void initState() {
    super.initState();
    Future.delayed(const Duration(seconds: 2), () {
      setState(() {
        loading = false;
        // Uncomment to simulate an error
        // error = true;
        // errorMessage = "Failed to load data";
        // Uncomment to simulate an empty state
        // empty = true;
      });
    });
  }
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: HomeScreen(),
    );
  }
}

以上是 loading_state_handler 插件的基本介绍和使用示例，希望对您有所帮助！如果您需要进一步了解或贡献，请查看其GitHub仓库。