Flutter通用输入输出插件universal_io2的使用

Flutter通用输入输出插件universal_io2的使用

概览

universal_io2 是一个跨平台的 dart:io 库，适用于所有平台，包括浏览器。

你可以简单地将 dart:io 的导入替换为 package:universal_io2/io.dart。

该库受 Apache License 2.0 许可。部分源码来自 Dart SDK，并通过 Dart SDK 的 BSD 风格许可证获得。详情见 LICENSE 文件。

增加的API

1. newUniversalHttpClient

// 返回 BrowserHttpClient 在浏览器上，其他平台返回正常的 "dart:io" HttpClient。
HttpClient httpClient = newUniversalHttpClient(); // 推荐的创建 HttpClient 的方法。

2. BrowserHttpClient

// 在浏览器上工作的 "dart:io" HttpClient 的子类。

3. BrowserHttpClientRequest

// 在浏览器上工作的 "dart:io" HttpClientRequest 的子类。

4. BrowserHttpClientResponse

// 在浏览器上工作的 "dart:io" HttpClientResponse 的子类。

5. BrowserHttpClientException

// 一种异常，帮助你理解为什么浏览器上的 HTTP 请求可能失败（参见下文解释）。

其他功能

以下功能可能会在未来的版本（3.x）中被弃用：

1. HttpClient

// HttpClient() 工厂方法已更改，使其在浏览器上返回 BrowserHttpClient。

2. Platform

// 该包使得像 Platform.isAndroid 和 Platform.isMacOS 这样的方法也能在浏览器上工作。

3. InternetAddress

// 该包使得 InternetAddress 也能在浏览器上工作。

4. BytesBuilder

// 该包使得 BytesBuilder 也能在浏览器上工作。

使用步骤

1. 添加依赖

在 pubspec.yaml 文件中添加：

dependencies:
  universal_io2: ^2.2.1

2. 使用 HTTP 客户端

import 'package:universal_io2/io.dart';

Future<void> main() async {
  // HttpClient 可以在浏览器上使用！
  HttpClient httpClient = newUniversalHttpClient(); // 推荐的创建 HttpClient 的方法。
  final request = await httpClient.getUrl(Uri.parse("https://dart.dev/"));
  final response = await request.close();
  print(response);
}

HTTP 客户端行为

HTTP 客户端使用浏览器的 XMLHttpRequest (XHR) API 实现。

XHR 导致与 dart:io 有以下不同点：

• HTTP 连接仅在调用 request.close() 后才创建。
• 同源策略限制。对于跨域请求，请参阅下文文档。

有用的错误信息

当请求失败且断言启用时，错误消息包含如何修复可能问题的描述，例如缺少跨域头。

错误消息类似于以下内容：

XMLHttpRequest error.
-------------------------------------------------------------------------------
HTTP 方法：             PUT
HTTP URL：                http://destination.com/example
来源：                  http://source.com
跨域：                  true
浏览器凭据模式：         false
浏览器响应类型：         arraybuffer

未知的 XHR 错误原因。
（出于安全原因，浏览器不会解释 XHR 错误。）

服务器是否宕机？服务器是否有内部错误？

启用凭据模式将允许在请求和响应中使用某些 HTTP 头。例如，凭据模式是发送/接收 cookie 所必需的。如果你认为需要启用 '凭据模式'，可以执行以下操作：

    final httpClientRequest = ...;
    if (httpClientRequest is BrowserHttpClientRequest) {
      httpClientRequest.browserCredentialsMode = true;
    }

服务器是否响应了跨域 "预检" (OPTIONS) 请求？

服务器是否发送了以下头？
  * Access-Control-Allow-Origin: http://source.com
    * 也可以使用通配符 ("*")。
    * 对于跨域请求总是需要！
  * Access-Control-Allow-Methods: PUT
    * 也可以使用通配符 ("*")。

有时当你在浏览器上进行跨域请求时，你可能想使用 CORS "凭据模式"。这可以通过以下模式实现：

Future<void> main() async {
    final client = HttpClient();
    final request = client.getUrl(Uri.parse('http://example/url'));

    // 启用凭据模式
    if (request is BrowserHttpClientRequest) {
      request.browserCredentialsMode = true;
    }

    // 关闭请求
    final response = await request.close();
    // ...
}

流式文本响应

底层的 XMLHttpRequest (XHR) API 仅在 responseType 为 "text" 时支持响应流。

此包会根据 HTTP 请求头 "Accept" 的值自动使用 "text" 类型。这些媒体类型定义在：

BrowserHttpClient.defaultTextMimes

如果你想要禁用流式处理，可以使用以下模式：

Future<void> main() async {
    final client = newUniversalHttpClient();
    if (client is BrowserHttpClient) {
      client.textMimes = const {};
    }
    // ...
}

示例代码

import 'package:universal_io2/io.dart';

void main() async {
  // 使用 'dart:io' HttpClient API。
  final httpClient = HttpClient();
  final request = await httpClient.getUrl(Uri.parse('https://dart.dev'));
  final response = await request.close();
  print(response);
}