七牛云存储 Flutter SDK

基于七牛云 API 实现，封装了七牛云存储系统的客户端操作。

快速导航

• 概述
• 示例
• 快速开始
• 功能简介
• 贡献代码
• 许可证

概述

Qiniu-Flutter-SDK 基于七牛云存储官方 API 构建，提供抽象的接口用于快速使用七牛的对象存储功能。注意：token 应从服务端获取。

示例

请查看 Example。

快速开始

编辑 pubspec.yaml

在 dependencies 添加 qiniu-flutter-sdk：

dependencies:
  ...
  qiniu_flutter_sdk: ^x.x.x # 替换为需要的版本

导入包

import 'package:qiniu_flutter_sdk/qiniu_flutter_sdk.dart';

快速使用

// 创建 storage 对象
final storage = Storage();

// 使用 storage 的 putFile 对象进行文件上传
storage.putFile(File('./file.txt'), 'TOKEN')
  ..then((response) {
    print('上传成功: ${response.key}');
  })
  ..catchError((error) {
    print('上传失败: $error');
  });

监听进度/状态

// 创建 Controller 对象
final putController = PutController();

// 添加整体进度监听
putController.onProgress((double percent) {
  print('任务进度变化：已发送：$percent');
});

// 添加发送进度监听
putController.onSendProgress((double percent) {
  print('已上传进度变化：已发送：$percent');
});

// 添加状态监听
putController.addStatusListener((StorageStatus status) {
  print('状态变化: 当前任务状态：$status');
});

// 使用 storage 的 putFile 对象进行文件上传
storage.putFile(File('./file.txt'), 'TOKEN', PutOptions(
  controller: putController,
));

取消正在上传的任务

// 创建 Controller 对象
final putController = PutController();

// 使用 storage 的 putFile 对象进行文件上传
final uploadTask = storage.putFile(File('./file.txt'), 'TOKEN', PutOptions(
  controller: putController,
));

// 取消当前任务
putController.cancel();

完整示例 Demo

以下是一个完整的 Flutter 示例，包含文件选择、上传进度显示等功能：

import 'dart:convert';
import 'dart:io';
import 'package:file_picker/file_picker.dart';
import 'package:flutter/material.dart';
import 'package:qiniu_flutter_sdk/qiniu_flutter_sdk.dart';

void main() => runApp(MyApp());

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

class UploadPage extends StatefulWidget {
  @override
  _UploadPageState createState() => _UploadPageState();
}

class _UploadPageState extends State<UploadPage> {
  String? key;
  String? mimeType;
  int partSize = 4;
  String? token;
  final Storage storage = Storage();
  PlatformFile? selectedFile;
  double progressValue = 0.0;
  StorageStatus? statusValue;
  PutController? putController;

  void onSelectedFile(PlatformFile file) {
    setState(() {
      selectedFile = file;
      startUpload();
    });
  }

  void startUpload() {
    putController = PutController();

    putController!.addSendProgressListener((double percent) {
      print('实际发送变化：进度：${percent.toStringAsFixed(4)}');
    });

    putController!.addProgressListener((double percent) {
      setState(() => progressValue = percent);
      print('任务进度变化：进度：${percent.toStringAsFixed(4)}');
    });

    putController!.addStatusListener((StorageStatus status) {
      setState(() => statusValue = status);
      print('状态变化: 当前任务状态：${status.toString()}');
    });

    if (selectedFile == null) {
      printToConsole('请选择文件');
      return;
    }

    final putOptions = PutOptions(
      key: key,
      mimeType: mimeType,
      partSize: partSize,
      controller: putController,
    );

    Future<PutResponse> upload;
    if (kIsWeb) {
      upload = storage.putBytes(
        selectedFile!.bytes!,
        token!,
        options: putOptions,
      );
    } else {
      upload = storage.putFile(
        File(selectedFile!.path!),
        token!,
        options: putOptions,
      );
    }

    upload
      ..then((PutResponse response) {
        print('上传已完成: 原始响应数据: ${jsonEncode(response.rawData)}');
      })
      ..catchError((dynamic error) {
        print('发生错误: $error');
      });
  }

  void printToConsole(String message) {
    debugPrint(message);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('文件上传')),
      body: ListView(
        children: [
          ElevatedButton(
            onPressed: () async {
              FilePickerResult? result = await FilePicker.platform.pickFiles();
              if (result != null) {
                onSelectedFile(result.files.first);
              }
            },
            child: Text('选择文件'),
          ),
          LinearProgressIndicator(value: progressValue),
          Text('上传进度: ${(progressValue * 100).toStringAsFixed(2)}%'),
          if (statusValue == StorageStatus.Request)
            ElevatedButton(
              onPressed: () => putController?.cancel(),
              child: Text('取消上传'),
            ),
        ],
      ),
    );
  }
}

功能列表

• 单文件上传
• 分片上传
• 任务状态
• 任务进度
• 上传进度
• 失败重试

许可证

基于 Apache 2.0 协议发布。