Flutter插件tusc的使用_tus 是一个基于 HTTP 的协议，用于可恢复的文件上传

Flutter插件tusc的使用_tus 是一个基于 HTTP 的协议，用于可恢复的文件上传

A tus 客户端

一个用纯 Dart 编写的 tus 客户端，用于通过 tus 协议进行可恢复的文件上传。

tus 是什么？

tus 是一个基于 HTTP 的协议，用于可恢复的文件上传。可恢复意味着在任何时候上传都可以中断，并且无需重新上传之前的数据就可以继续上传。中断可能由用户意愿引起（例如，用户想要暂停），也可能由于网络问题或服务器故障意外发生。

这个包基于 tus_client（https://pub.dev/packages/tus_client），但有一些改进。

安装

首先，需要将 tusc 添加为项目的依赖项。你可以使用以下命令：

对于纯 Dart 项目

dart pub add tusc

对于 Flutter 项目

flutter pub add tusc

此命令会将 tusc 添加到项目的 pubspec.yaml 文件中。最后，你需要运行：

dart pub get

或者

flutter pub get

这将根据项目类型下载依赖项到你的 pub-cache 中。

使用

import 'dart:io';

import 'package:tusc/tusc.dart';
import 'package:cross_file/cross_file.dart' show XFile;
import 'package:http/http.dart' as http;

void main() async {
  /// 要上传的文件
  final file = XFile('/path/to/some/video.mp4');
  final uploadURL = 'https://master.tus.io/files';

  /// 创建一个客户端
  final tusClient = TusClient(
    url: uploadURL,

    /// 必须设置
    file: file,

    /// 必须设置
    chunkSize: 5.MB,

    /// 可选，默认为 256 KB
    tusVersion: TusClient.defaultTusVersion,

    /// 可选，默认为 1.0.0。如果你的 tus 服务器使用不同的版本，请更改此值
    cache: TusPersistentCache('/some/path'),

    /// 可选，默认为 null。参见 [TusMemoryCache]
    headers: <String, dynamic>{
      /// 可选，默认为 null。当需要传递额外的请求头（如认证）时使用
      HttpHeaders.authorizationHeader:
          'Bearer d843udhq3fkjasdnflkjasdf.hedomiqxh3rx3r23r.8f392zqh3irgqig'
    },
    metadata: <String, dynamic>{
      /// 可选，默认为 null。当你需要传递额外数据（如文件名或其他特定业务数据）时使用
      'name': 'my-video'
    },
    timeout: Duration(seconds: 10),

    /// 可选，默认为 30 秒
    httpClient: http.Client(),

    /// 可选，默认为 http.Client()，当你需要对 HTTP 请求有更多的控制时使用
  );

  /// 开始上传
  tusClient.startUpload(
    /// count: 已经上传的数据量
    /// total: 需要上传的总数据量
    /// response: 最后一个 chunkSize 上传的 HTTP 响应
      onProgress: (count, total, progress) {
    print('进度: $count of $total | ${((count / total) * 100).toInt()}%');
  },

      /// response: 最后一个 chunkSize 上传的 HTTP 响应
      onComplete: (response) {
    print('上传完成');
    print(tusClient.uploadUrl.toString());
  }, onTimeout: () {
    print('上传超时');
  });

  await Future.delayed(const Duration(seconds: 6), () async {
    await tusClient.pauseUpload();
    print(tusClient.state);

    /// 暂停上传进度
  });

  await Future.delayed(const Duration(seconds: 6), () async {
    await tusClient.cancelUpload();
    print(tusClient.state);

    /// 取消上传进度
  });

  await Future.delayed(const Duration(seconds: 8), () async {
    tusClient.resumeUpload();
    print(tusClient.state);

    /// 在上次暂停的地方恢复上传进度，并通知与 startUpload(...) 相同的回调
  });
}

分块大小

文件将以分块方式上传。默认大小为 256KB。这个值应该根据上传速度和设备内存约束来设置。 要指定 chunkSize，可以轻松地设置为 512.KB 或 10.MB，这将使用 int 扩展在内部计算字节数。

final tusClient = TusClient(
    uploadURL,
    file,
    chunkSize: 10.MB,
);

上传回调

当你调用 tusClient.startUpload(...) 时，可以选择设置一些回调：

• onProgress: (count, total, progress)：此回调通知上传进度。它提供了 count，即已经上传的数据量，total，即需要上传的总数据量，以及 response，即最后一个 chunkSize 上传的 HTTP 响应。通过这个响应，你可以检查头部或正文，如果 tus 服务器返回某些信息的话。
• onComplete: (response)：此回调通知上传已完成。它提供了一个 response，即最后一个 chunkSize 上传的 HTTP 响应。通过这个响应，你可以检查头部或正文，如果 tus 服务器返回某些信息的话。
• onTimeout: ()：此回调通知上传超时，根据 TusClient 构造函数中指定的 timeout 属性。默认情况下，超时时间为 30 秒。

缓存

为了使 TusClient 管理 pause/resume 上传，可以通过使用以下方法设置缓存：

• TusMemoryCache：使用此缓存可以在应用运行时暂停/恢复上传。如果你的应用崩溃或简单关闭，你将无法恢复未完成的上传。
• TusPersistentCache：使用此缓存可以在任何时间暂停/恢复上传，无论应用是否崩溃、关闭甚至设备重启。

final tusClient = TusClient(
    uploadURL,
    file,
    cache: TusMemoryCache(),
);

或者

final tusClient = TusClient(
    uploadURL,
    file,
    cache: TusPersistentCache('/some/path'),
);

请注意，TusPersistentCache 需要一个路径，该路径将是缓存存储的位置。此持久化缓存实现完全使用 Dart 实现，因此无论你想在 flutter 项目还是 dart 项目中使用它，它都适用。

如何在 Flutter 中设置持久化缓存

你可以使用 path_provider 插件来获取一个目录的路径，你的应用在这个目录下有写权限。 path_provider 在大多数平台上工作，除了 Web 平台，但这不是问题，TusPersistentCache 会处理这个问题，你只需要设置一个 path，如果应用在 Web 上运行，TusPersistentCache 将忽略该 path 并在后台处理持久化缓存。

以下示例代码适用于任何平台。

import 'dart:io';
import 'package:path_provider/path_provider.dart';

Future<void> sample() async {
  Directory dir = Directory.systemTemp;
  try {
    /// 这里的 try/catch 用于处理 path_provider 在应用运行于不支持的平台（如 Web）时抛出的 MissingPlatformDirectoryException 异常。
    /// 你可以用不同的方式处理此异常，例如询问 kIsWeb，但这只是一个示例
    dir = await getApplicationDocumentsDirectory();
  } catch (e) {
    print(e);
  }

  final tusClient = TusClient(
    uploadURL,
    file,
    cache: TusPersistentCache(dir.path),
  );
}