Flutter网络连接检测插件internet_connection_checker的使用

🌍 Internet Connection Checker

internet_connection_checker 是一个用于无缝检查互联网连接的库。它不仅可以验证您的互联网连接，还可以检测慢速互联网连接。

目录

• Usecases of this library
• Description
• Demo
• Quick start
• Purpose
• Getting Started
  • Singleton Basic Usage Example
  • Listen to Stream for Internet Connection Availability Changes
  • Creating a Custom Instance
  • Enable Detection for Slow Internet Connectivity
  • Using requireAllAddressesToRespond
• Features and bugs

Usecases of this library:

Backend Server Checks

无缝验证互联网连接和服务器可达性，通过内置默认地址或配置自定义后端服务器URL以满足应用需求。

Slow Internet Detection

高效检测并管理用户的设备上的慢速互联网连接，确保流畅的用户体验。

Auto Refresh

当互联网可用时自动刷新应用中的页面，提供动态且无缝的用户体验。

Description

此插件通过检查可访问的Uri来检查互联网（数据）连接。默认情况下，该插件应该足以可靠地确定设备当前是否已连接到全球网络，即是否有访问互联网的权限。

Demo

Quick start

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

dependencies:
  internet_connection_checker: ^2.0.0

Android Configuration

对于Android，在发布模式下正确工作，您必须在 AndroidManifest.xml 中添加 INTERNET 和 ACCESS_NETWORK_STATE 权限：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Permissions for internet_connection_checker -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <application
        ...

Mac OS Configuration

对于MacOS，您需要在 DebugProfile.entitlements 和 Release.entitlements (位于 macos/Runner 下) 中添加以下条目以允许访问互联网。

<key>com.apple.security.network.server</key>
<true/>

示例：

<plist version="1.0">
    <dict>
	    <key>com.apple.security.app-sandbox</key>
	    <true/>
    </dict>
</plist>

Purpose

此包存在的原因是因为 connectivity_plus 包不能可靠地确定数据连接是否实际可用。更多详情请参阅其页面：connectivity_plus。

Getting Started

InternetConnectionChecker 可以作为单例使用，也可以通过自定义实例与您策划的 AddressCheckOption 实例化。

Singleton Basic Usage example

import 'package:internet_connection_checker/internet_connection_checker.dart';

void main() async {
  final bool isConnected = await InternetConnectionChecker.instance.hasConnection;
  if (isConnected) {
    print('Device is connected to the internet');
  } else {
    print('Device is not connected to the internet');
  }
}

Listen to Stream for Internet Connection availability changes

import 'package:internet_connection_checker/internet_connection_checker.dart';

void main() {
  final connectionChecker = InternetConnectionChecker.instance;

  final subscription = connectionChecker.onStatusChange.listen(
    (InternetConnectionStatus status) {
      if (status == InternetConnectionStatus.connected) {
        print('Connected to the internet');
      } else {
        print('Disconnected from the internet');
      }
    },
  );

  // Remember to cancel the subscription when it's no longer needed
  subscription.cancel();
}

注意: 记得在不再需要监听器和 InternetConnectionChecker 实例时进行释放，以防止内存泄漏。例如，在 StatefulWidget 的 dispose 方法中：

...
@override
void dispose() {
  listener.cancel();
  connectionChecker.dispose();
  super.dispose();
}
...

Creating a Custom Instance

要创建具有特定检查选项的 InternetConnectionChecker 自定义实例：

import 'package:internet_connection_checker/internet_connection_checker.dart';

void main() async {
  final customChecker = InternetConnectionChecker.createInstance(
    addresses: [
      AddressCheckOption(uri: Uri.parse('https://api.github.com/users/octocat')),
      AddressCheckOption(
        uri: Uri.parse('https://api.agify.io/?name=michael'),
      ),
    ],
  );

  bool isConnected = await customChecker.hasConnection;
  print('Custom instance connected: $isConnected');
}

// Remember to dispose of InternetConnectionChecker instance,
// when it's not needed to prevent memory leaks,
// e.g. in a StatefulWidget's dispose() method:
...
@override
void dispose() {
  super.dispose();
  customChecker.dispose();
}
...

Enable detection for slow internet connectivity

要创建具有慢速互联网连接检测功能的 InternetConnectionChecker 自定义实例：

import 'package:internet_connection_checker/internet_connection_checker.dart';

void main() async {
  final customChecker = InternetConnectionChecker.createInstance(
    slowConnectionConfig: SlowConnectionConfig(
        enableToCheckForSlowConnection: true,
        slowConnectionThreshold: const Duration(seconds: 1),
      ),
  );

  bool isConnected = await customChecker.hasConnection;
  print('Custom instance connected: $isConnected');
}

注意: 确保您的 slowConnectionThreshold 持续时间不超过 checkInterval 和 checkTimeout 的持续时间。

Using requireAllAddressesToRespond

要确保只有在所有指定地址都可访问时才将互联网连接状态标记为已连接，您可以启用 requireAllAddressesToRespond 配置。

import 'package:internet_connection_checker/internet_connection_checker.dart';

void main() async {
  // Create a custom instance with requireAllAddressesToRespond set to true
  /// Remember to dispose of [customChecker] instance, when it's not needed 
  /// to prevent memory leaks.
  final customChecker = InternetConnectionChecker.createInstance(
    requireAllAddressesToRespond: true,
    addresses: [
      AddressCheckOption(uri: Uri.parse('https://dummyapi.online/api/movies/1')),
      AddressCheckOption(
        uri: Uri.parse('https://jsonplaceholder.typicode.com/albums/1'),
      ),
    ],
  );

  // Check connectivity
  final bool isConnected = await customChecker.hasConnection;

  if (isConnected) {
    print('All specified backend servers are reachable.');
  } else {
    print('Not all specified backend servers are reachable.');
  }
}

Features and bugs

请在 issue tracker 上提交功能请求和错误报告。

Credits

• 注意：此包是 data_connection_checker 的延续，后者目前未继续开发。
• Web平台支持受到 internet_connection_checker_plus 库的启发。