Flutter网络连接监测插件connectivity_monitor的使用

Flutter网络连接监测插件connectivity_monitor的使用

connectivity_monitor 是一个简化Flutter应用中网络连接处理的包。它提供了一个强大的服务 (ConnectivityService) 和一个灵活的组件 (ConnectivityMonitor)，帮助你无缝管理网络变化并提升用户体验。

特性

• 全局网络连接监控：自动跟踪网络变化，并验证互联网访问。
• 可自定义的网络连接指示器：通过对话框、自定义小部件或提示信息来通知用户网络状态的变化。
• 事件去抖动：通过应用去抖逻辑减少频繁更新。
• 网络连接事件的回调：轻松处理 onConnected 和 onDisconnected 事件。
• 跨平台支持：在Android和iOS上表现良好。
• 可定制选项：自定义提示信息、颜色和小部件以匹配你的应用主题和设计。

安装

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

dependencies:
  connectivity_monitor: ^1.0.0

然后运行：

flutter pub get

重要说明

为了有效使用 ConnectivityMonitor 小部件，必须首先调用 ConnectivityService.startConnectionNotifier 来初始化全局网络监听器。这确保了网络事件能够被正确监控，并且可以被 ConnectivityMonitor 小部件或其他自定义逻辑利用。

你可以使用 ConnectivityMonitor 小部件来根据网络变化调整UI，或者选择不使用它，而仅依靠 ConnectivityService 进行监控和回调。

使用方法

1. 开始全局监控（使用 ConnectivityService）

在应用的 main 函数中开始网络连接监控：

注意：确保在启动网络服务之前调用 WidgetsFlutterBinding.ensureInitialized();。

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

void main() {
  // 确保绑定在启动网络服务之前已初始化
  WidgetsFlutterBinding.ensureInitialized();

  // 开始全局网络连接监控
  ConnectivityService.startConnectionNotifier(
    connectedToastMessage: "Connected!",
    disconnectedToastMessage: "No Internet Connection.",
    showToasts: true, // 显示网络变化的提示信息
  );

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Connectivity Monitor Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: HomeScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Connectivity Monitor Example')),
      body: Center(child: Text('Home Screen')),
    );
  }
}

2. 使用 ConnectivityMonitor 小部件

将应用的小部件或页面包裹在 ConnectivityMonitor 小部件中，以便在网络设备离线时显示自定义UI或消息：

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Connectivity Monitor Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: ConnectivityMonitor(
        child: HomeScreen(),
        customDisconnectedWidget: Center(
          child: Text(
            'No Internet Connection. Please reconnect.',
            style: TextStyle(color: Colors.red, fontSize: 18),
          ),
        ),
        customDialog: AlertDialog(
          title: Text('No Internet'),
          content: Text('Please check your connection and try again.'),
        ),
      ),
    );
  }
}

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Connectivity Monitor Example')),
      body: Center(child: Text('Home Screen')),
    );
  }
}

ConnectivityMonitor 小部件参数

• child (必需)：显示当连接时的主要小部件。
• customDisconnectedWidget：设备断开连接时显示的自定义小部件。（默认：null）
• requiresConnection：如果为 true，则只在设备连接到互联网时显示 child 小部件。（默认：true）
• useDialogAsConnectivityIndicator：是否显示对话框作为网络连接指示器。（默认：true）
• useWidgetAsConnectivityIndicator：是否使用自定义小部件作为网络连接指示器。（默认：false）
• customDialog：设备断开连接时显示的自定义对话框。（默认：null）

如何与 ConnectivityService 配合使用

ConnectivityService 选项

• startConnectionNotifier：初始化全局网络连接监控，验证互联网访问并广播变化。
• stopNotifier：停止全局网络连接监控并清理资源。
• validateInternetConnection：通过向指定URL发送请求检查设备是否有互联网访问权限。

ConnectivityService 方法详解

startConnectionNotifier()

startConnectionNotifier 方法初始化全局网络连接监控，并监听互联网连接变化。它还提供了显示提示信息、处理连接事件和去抖网络变化事件的选项。此方法必须在使用 ConnectivityMonitor 小部件之前调用，以确保提供网络更新。

功能：

1. 使用 connectivity_plus 监控网络连接变化。
2. 通过ping一个可靠的URL来验证实际的互联网访问。
3. 触发 onConnected 和 onDisconnected 事件的回调。
4. 显示可自定义的提示信息来反映连接状态。
5. 对网络变化事件进行去抖处理，以防止频繁更新。

参数：

• connectedToastMessage (字符串，默认值：“You are now connected to the Internet.”)： 设备连接到互联网时显示的消息。
• disconnectedToastMessage (字符串，默认值：“No internet connection. Please check your network.”)： 设备断开互联网连接时显示的消息。
• testUrl (字符串，默认值：“https://google.com”)： 用于验证实际互联网访问的URL。
• connectedBackgroundColor (颜色，默认值：Colors.green)： 连接时提示信息的背景颜色。
• disconnectedBackgroundColor (颜色，默认值：Colors.red)： 断开连接时提示信息的背景颜色。
• connectedWebBackgroundHexColor (字符串，默认值："#4CAF50")： 网页提示信息连接时的背景颜色（十六进制）。
• disconnectedWebBackgroundHexColor (字符串，默认值："#F44336")： 网页提示信息断开连接时的背景颜色（十六进制）。
• toastGravity (ToastGravity，默认值：ToastGravity.BOTTOM)： 提示信息在屏幕上的位置。
• toastFontSize (双精度浮点数，默认值：16.0): 提示信息的字体大小。
• showToasts (布尔，默认值：true): 是否显示网络变化的提示信息。
• debounceDuration (持续时间，默认值：Duration(milliseconds: 500)): 网络变化事件的去抖持续时间。
• onConnected (函数，可选): 设备连接到互联网时触发的回调函数。
• onDisconnected (函数，可选): 设备断开互联网连接时触发的回调函数。

示例用法：

确保在应用的 main 函数中调用 WidgetsFlutterBinding.ensureInitialized();。

import 'package:flutter/material.dart';
import 'package:connectivity_monitor/connectivity_service.dart';

void main() {
  // 确保初始化
  WidgetsFlutterBinding.ensureInitialized();

  // 开始全局网络连接监控
  ConnectivityService.startConnectionNotifier(
    connectedToastMessage: "Connected to the Internet!",
    disconnectedToastMessage: "No Internet Connection.",
    onConnected: () => debugPrint("Connected!"),
    onDisconnected: () => debugPrint("Disconnected!"),
    showToasts: true,
  );

  runApp(MyApp());
}

stopNotifier()

stopNotifier 方法停止全局网络连接监控过程并清理资源。它执行以下操作：

1. 取消当前的连接监听订阅，防止进一步更新。
2. 关闭用于广播连接变化的 StreamController，释放所有相关资源。
3. 标记连接监听器为非活动状态。

此方法特别适用于不再需要监控连接的情况，例如应用被销毁或测试期间。

// `stopNotifier` 的示例用法
void dispose() {
  ConnectivityService.stopNotifier();
  super.dispose();
}

注意：大多数情况下，无需显式调用 stopNotifier，因为当应用关闭时监听器会自动停止。仅在需要特定清理时使用它。

validateInternetConnection()

validateInternetConnection 方法检查设备是否具有活跃的互联网访问权限。不同于基本的网络连接检查（如Wi-Fi或移动数据），此方法确保设备可以通过发送HTTP请求到可靠URL来实际访问互联网。

参数：

• testUrl：用于验证互联网访问的URL（默认为 https://google.com）。
• retries：如果请求失败，重试的次数（默认为3次）。
• retryDelay：重试尝试之间的延迟（默认为2秒）。

如何工作：

1. 向指定的 testUrl 发送HTTP GET请求。
2. 如果请求成功并返回 200 状态码，则确认互联网访问。
3. 如果请求失败，在指定的重试次数内重新尝试，否则返回 false。

// `validateInternetConnection` 的示例用法
Future<void> checkConnection() async {
  bool isConnected = await ConnectivityService.validateInternetConnection(
    testUrl: 'https://example.com',
    retries: 2,
    retryDelay: Duration(seconds: 1),
  );

  if (isConnected) {
    print('Internet is accessible');
  } else {
    print('No active internet connection');
  }
}