Flutter文件上传管理插件uploadcare_client的使用

Uploadcare是一个全面的文件处理平台，可以帮助你更快地交付产品并专注于业务目标。uploadcare_client是Dart/Flutter的一个库，用于与Uploadcare REST API交互，支持文件上传、媒体处理和自适应交付。

安装

在你的项目中添加uploadcare_client包：

Dart

dart pub add uploadcare_client # 或者 uploadcare_flutter

Flutter

flutter pub add uploadcare_client # 或者 uploadcare_flutter

创建一个客户端实例：

final client = UploadcareClient.withSimpleAuth(
  publicKey: 'your_public_key',
  apiVersion: 'v0.7',
);

UploadcareClient提供了多个API部分：

final ApiUpload upload;
final ApiFiles files;
final ApiGroups groups;
final ApiDocumentConverting documentConverting;
final ApiVideoEncoding videoEncoding;
final ApiAddons addons;
final ApiWebhooks webhooks;
final ApiProject project;

文件上传

基本上传

适用于小文件：

final fileId = await client.upload.base(UCFile(File('path/to/small_file')));

分块上传

适用于大文件：

final fileId = await client.upload.multipart(UCFile(File('path/to/large_file')));

从URL上传

final fileId = await client.upload.fromUrl('https://files.st/path_to_file');

自动上传

自动选择合适的上传方法：

final fileId1 = await client.upload.auto(UCFile(File('path/to/small_file')));
final fileId2 = await client.upload.auto(UCFile(File('path/to/large_file')));
final fileId3 = await client.upload.auto('https://files.st/path_to_file');

在隔离线程中上传

不适用于Web环境：

final fileId = await client.upload.auto(UCFile(File('path/to/file')), runInIsolate: true);

进度跟踪

所有上传方法都接受一个进度回调：

final fileId = await client.upload.auto(UCFile(File('path/to/file')), onProgress: (progress) => print(progress));

可取消的上传

使用CancelToken取消上传：

final cancelToken = CancelToken();

Timer(Duration(seconds: 1), cancelToken.cancel);

try {
  final fileId = await client.upload.auto(UCFile(File('/some/file')), cancelToken: cancelToken);
} on CancelUploadException catch (e) {
  // 已取消
}

签名上传

需要提供项目的私钥：

final client = UploadcareClient(options: ClientOptions(
  authorizationScheme: AuthSchemeRegular(
    publicKey: 'public_key',
    privateKey: 'private_key',
    apiVersion: 'v0.7',
  ),
  useSignedUploads: true,
));

await client.upload.base(UCFile(File('path/to/file')));

图像和文件转换

官方文档：图像转换

示例代码：

final cropedCdnImage = CdnImage('<image-uuid>')..transform(CropTransformation(aspectRatio: AspectRatio(9, 16)));

// 使用以下字段获取裁剪后的图像URL
print(cropedCdnImage.url);

文件操作

获取文件信息

final FileInfoEntity file = await client.files.file('<file-uuid>');

获取文件列表

final ListEntity<FileInfoEntity> list = await client.files.list();

删除文件

await client.files.remove(['<file-uuid>', '<file-uuid>']);

存储文件

await client.files.store(['<file-uuid>', '<file-uuid>']);

元数据操作

// 获取文件的所有元数据
final Map<String, String> metadata = await client.files.getFileMetadata('<file-uuid>');

// 更新特定元数据键的值
final String updatedValue = await client.files.updateFileMetadataValue('<file-uuid>', '<metadata-key>', '<new-value>');

示例Demo

以下是一个完整的示例，展示了如何使用uploadcare_client进行文件上传和基本操作：

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

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: UploadPage(),
    );
  }
}

class UploadPage extends StatefulWidget {
  [@override](/user/override)
  _UploadPageState createState() => _UploadPageState();
}

class _UploadPageState extends State<UploadPage> {
  final UploadcareClient client = UploadcareClient.withSimpleAuth(
    publicKey: 'your_public_key',
    apiVersion: 'v0.7',
  );

  Future<void> uploadFile() async {
    try {
      final fileId = await client.upload.base(UCFile(File('path/to/your/file')));
      print('File uploaded with ID: $fileId');
    } catch (e) {
      print('Error uploading file: $e');
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Uploadcare Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: uploadFile,
          child: Text('Upload File'),
        ),
      ),
    );
  }
}