Flutter文件管理工具插件run_small_dropbox的使用

Run Small Dropbox Package

一个简化与Dropbox API交互的Dart SDK。该SDK提供了方便的抽象和方法，用于处理常见的Dropbox操作，例如复制文件、创建文件夹、下载文件等。

目标是加速在Dart和Flutter应用程序中集成Dropbox功能。

SDK设计简单易用，并且遵循与其他流行SDK（如Firebase）类似的结构，使熟悉这些SDK的开发者可以轻松地将Dropbox功能集成到他们的应用程序中。

更新 (3.1.0)

在某些情况下，您可能会遇到包含非ASCII字符的文件或文件夹名称。版本3.1.0引入了escapeNonAscii函数来处理这种情况。当与Dropbox API交互时，如果遇到包含非ASCII字符的文件或文件夹名称，此函数可以帮助正确处理这些字符，以确保通信顺畅。

void main() {
  var escapedString = escapeNonAscii('Café');
  print('Escaped String: $escapedString'); // 输出: Escaped String: Caf\u00e9
}

注意: escapeNonAscii 是 Run Small Dropbox 的内置函数，无需显式导入或定义。

开始使用

要使用此包，请在项目的 pubspec.yaml 文件中添加 run_small_dropbox 作为依赖项。例如：

dependencies:
  run_small_dropbox: ^3.0.2

功能

• 文件操作: 复制、移动、删除文件和文件夹。
• 批量操作: 执行多个文件操作的单次批处理。
• 文件夹创建: 单独或批量创建文件夹。
• 文件下载和上传: 下载文件、下载文件夹为ZIP、上传文件等。
• 元数据检索: 检索文件和文件夹的元数据。
• 文件和文件夹搜索: 搜索文件和文件夹。
• 纸张操作: 创建和更新Paper文档。

使用方法

首先，您需要获取一个 DropboxApp 实例才能使用Dropbox模块。可以通过以下方式实现：

final app = Dropbox.initializeApp('YOUR-ACCESS-TOKEN');

注意: “模块” 是SDK的一部分，您可以单独访问它们。它们类似于Firebase SDK中的Firebase Storage、Firebase Core和Firebase Authentication。

目前我们只有一个模块，即 DropboxFile。

所有 “模块” 都依赖于 DropboxApp 对象才能正常工作。

提示: 我不会在示例中添加注释，您可以使用IDE查看每个方法的功能。所有方法都有详细的文档。

复制文件

Feature<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.copyFile(relocationPath: RelocationPath(fromPath: '/Documents/favicon2_.png', toPath: '/Desktop/favicon2_.png'));
}

在示例中，您会注意到一些路径以正斜杠 / 开头。这是因为如果Dropbox API找不到这个符号，它会抛出异常。但是，Run Small Dropbox 给予了自由选择是否添加它的权利，这得益于 rPath 函数。

void main(){
  String path1 = rPath('/MyPathInDropbox'); // 带有正斜杠 "/"
  String path2 = rPath('MyPathInDropbox'); // 不带斜杠 "/".

  print("output 1: $path1"); // 输出: output 1: /MyPathInDropbox
  print("output 2: $path2"); // 输出: output 2: /MyPathInDropbox
}

提示: rPath 是 Run Small Dropbox 的内部函数，您无需显式导入或定义它。当使用需要 path 的方法时，可以选择传递或不传递 / 符号。例如：dropboxFile.copyFile(FolderWithoutSlash/file.txt);

批量复制文件

Feature<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  List<RelocationPath> entries = [
      RelocationPath(fromPath: '/Documents/drop_up.txt', toPath: '/Desktop/drop_up.txt'),
      RelocationPath(fromPath: '/Documents/uploadtestfile.txt', toPath: '/Desktop/uploadtestfile.txt'),
    ];

    var data = await dropboxFile.copyBatch(entries: entries);
}

批量复制检查

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);
  var data = await dropboxFile.copyBatchCheck('dbjid:AAAeL_0EYiPPSNJabLJLqdAYWSzDBghRkbYWoV2SDx9Lbg7rr9PG8_Igr_7_irFzWvaVNTeWU7r8lab3cJ9sUOsA');
}

获取复制引用

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);
  var data = await dropboxFile.getCopyReference('/Documents/orders.json');
}

保存复制引用

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);
  String copyReference = 'AAAAAlDqCCBkYTZldjZoa3ZiOW0', path = '/Documents/ref/orders.json';

  var data = await dropboxFile.saveCopyReference(copyReference, path);
}

创建文件夹

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.createFolder('Downloads', autorename: true);
}

批量创建文件夹

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.createFolderBatch(
      ['/Lib','Bin'],
      autorename: false,
      forceAsync: true,
  );
}

检查批量创建文件夹作业状态

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  // 调用此方法时，createFolderBatch 中的 forceAsync 必须为 true
  String asyncJobId = 'dbjid:AACIUTFyJ9SsVq7tFezji8rK-sO4GdpJ2wcn5hOUwsEw71d7hfa2aw_r9SCyiE9rxFqkwvIXmiNo5_KLTY8_LezA';

  var data = await dropboxFile.checkCreateFolderBatchJobStatus(asyncJobId);
}

删除文件或文件夹

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.deleteFileOrFolder('/Lib');
}

批量删除文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.deleteFilesBatch([
        DeleteArg(path: 'Downloads (1)'),
        DeleteArg(path: 'Downloads (2)'),
    ],
  );
}

批量删除检查

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  String asyncJobId = 'dbjid:AABWTKVCz9BVnnCDelfli-hJO8ve91g7lszKeV7WmycG5kRb5F1X6kTjhYJDTekMK6IDRHZXV7R3UBY417cseFZd';

  var data = await dropboxFile.deleteBatchCheck(asyncJobId);
}

下载文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.downloadFile('/Documents/orders.json');
  if (data['success']) {
      var file = File('Me/Path/file.json');
      await file.writeAsBytes(utf8.encode(data['result']));
  }
}

下载文件夹为ZIP

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.downloadFolderAsZip('/Documents');

  if (data['success']) {
      var file = File('Me/Path/file.zip');
      await file.writeAsBytes(utf8.encode(data['result']));
  }
}

导出文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.exportFile('/Documents/Prime Factorization.xlsx');
}

获取文件锁批量

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.getFileLockBatch([]);
}

获取元数据

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.getMetadata('Desktop/orders.json');
}

获取预览

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.getPreview('/Documents/mitologiagrega.docx');
}

获取临时链接

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.getTemporaryLink('/Documents/drop_up.txt');
}

获取临时上传链接

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);
  var data = await dropboxFile.getTemporaryUploadLink('/Documents/favicon2_.png');
}

获取缩略图V2

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);
  var data = await dropboxFile.getThumbnailV2('/Documents/favicon2_.png');

  if (data['success']) {
      var file = File('/Me/Desktop/favicon2_.jpeg');
      await file.writeAsBytes(utf8.encode(data['result']));
  }
}

获取缩略图批量

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.getThumbnailBatch(['/Documents/favicon2_.png', '/Documents/favicon2_.png']);
}

列表文件夹

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.listFolder('/Documents');
}

列表文件夹继续

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  String cursor = 'AAE78DDMQjfST3HwI';

  var data = await dropboxFile.listFolderContinue(cursor);
}

获取最新游标

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.listFolderGetLatestCursor('/Documents');
}

长轮询文件夹

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  String cursor = 'AAGvWI9NjRfdjJwFCJdlQKIbRNn';
  int timeout = 30;

  var data = await dropboxFile.listFolderLongpoll(cursor, timeout: timeout);
}

列表修订版本

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.listRevisions('/Documents/mitologiagrega.docx');
}

批量锁定文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.lockFileBatch(['/Desktop/orders.json']);
}

移动文件V2

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.moveV2(RelocationPath(fromPath: '/Documents/users.json', toPath: '/Desktop/users.json'));
}

批量移动文件V2

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.moveBatchV2([
          RelocationPath(fromPath: '/Documents/users.json', toPath: '/Desktop/users.json'),
          RelocationPath(fromPath: '/Documents/main.dart', toPath: '/Desktop/main.dart'),
        ],
  );
}

批量移动检查V2

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  String asyncJobId = 'dbjid:AACUbbYLC4V4a58VE3L923XCBH5myG1_qK33mhOjwS5p-7YxylZCpnhcLMlCNCmEA5oQAJMJIYQZkaLee05zMIXW';

  var data = await dropboxFile.moveBatchCheckV2(asyncJobId);
}

创建Paper文档

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.paperCreate(
      '/Desktop/document.paper',
      importFormat: ImportFormat.html,
  );
}

更新Paper文档

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.paperUpdate('');
}

彻底删除

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.permanentlyDelete('/Desktop/orders.json');
}

恢复文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.restoreFile('/Documents/file.txt', '/Documents/file.txt');
}

保存URL

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.saveUrl('', '');
}

检查任务状态

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.checkJobStatus('');
}

搜索文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.searchFiles('orders');
}

继续搜索

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.searchContinue('');
}

添加标签

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.addTag('/Desktop/orders.json', 'sdkTest');
}

获取标签

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.getTags(['/Desktop/orders.json']);
}

删除标签

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.removeTag('/Desktop/orders.json', 'sdkTest');
}

批量解锁文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.unlockFileBatch(['/Desktop/orders.json']);
}

上传文件

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.uploadFile(File('/Me/Desktop/dev_ttmp/main.dart'), destinationPath: '/Documents/main.dart');
}

分块上传追加

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.uploadSessionAppend(File(''), sessionID: '', offset: 3);
}

分块上传完成

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.uploadSessionFinish('', 0, '');
}

分块上传完成批量

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  List<UploadSessionFinishArg> entries = [
      UploadSessionFinishArg(
          cursor: UploadSessionCursor(sessionId: '', offset: 0),
          commit: CommitInfo(
              path: '/Homework/math/Matrices.txt',
              mode: WriteMode.add,
              autorename: true,
              clientModified: DateTime.now(),
              mute: false,
              propertyGroups: [
                  PropertyGroup(
                      templateId: 'your_template_id',
                      fields: [
                          PropertyField(name: 'name', value: 'Bob'),
                      ]
                  ),
              ],
              strictConflict: false,
              contentHash: 'contentHash123',
          ),
      ),
  ];

  var data = await dropboxFile.uploadSessionFinishBatch(entries);
}

分块上传完成批量检查

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.uploadSessionFinishBatchCheck('');
}

分块上传开始

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.uploadSessionStart(File(''));
}

分块上传开始批量

Future<void> method() async {
  // 获取 DropboxFile 实例
  DropboxFile dropboxFile = DropboxFile(yourDropboxAppInstance);

  var data = await dropboxFile.uploadSessionStartBatch(0);
}