文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>云点播>专业版>开发指南>上传>客户端上传>Flutter 上传 SDK

Flutter 上传 SDK

最近更新时间：2025-06-13 16:30:53

我的收藏

本页目录：

本示例基于 VOD 专业版 Flutter SDK v1.0.2，可 单击下载 上传 Demo 及源码。

环境准备

Flutter SDK 版本：≥ 3.3.0。
在 iOS 和 Android 端上传媒体文件时，如果业务需要从相册或存储中获取文件，则需自行配置并申请相册访问权限和存储访问权限等。
Demo 中以第三方插件访问为示例，配置了所需的权限，客户可根据业务场景自行调整。
<uses-permission android:name="android.permission.INTERNET"/>

依赖组件

将 voduploadadv 项目，复制到本地，使用相对目录进行依赖。
这里以复制到项目的平级目录为例，在项目 pubspec.yaml 根据 voduploadadv 的相对路径进行依赖。
  voduploadadv:
    path: ../voduploadadv/
添加完成后，执行如下命令刷新 pub 依赖。
flutter clean
flutter pub get

配置鉴权

上传过程中，需要对您客户端的身份进行鉴权，此时需要您配置鉴权回调，在 SDK 上传过程中需要拉取鉴权的时候，会调用您配置的回调，来获取 secretId,secretKey,token,expiredTime 等信息。
注意：
该配置为必须调用项，如果不配置，会导致无法上传。
使用示例如下：
TxVodUploadPlugin.instance.initWithScopeLimitCredential((stsCredentialScopes) async {
  // 建议调用服务器端获取鉴权信息
  Map<String, dynamic> jsonMap = jsonDecode(testRsCre);
  Map<String, dynamic> resJsonMap = jsonMap["Response"];
  Map<String, dynamic> credentialsJsonMap = resJsonMap["Credentials"];
  int expiredTimeStamp = DateTime.parse(credentialsJsonMap['Expiration']).millisecondsSinceEpoch;
  return FTXSessionQCloudCredentials(
      secretId: credentialsJsonMap["AccessKeyId"],
      secretKey: credentialsJsonMap["SecretAccessKey"],
      token: credentialsJsonMap["SessionToken"],
      expiredTime: expiredTimeStamp);
});
在获取鉴权的时候，强烈建议您从服务器获取临时的鉴权凭证，防止鉴权凭证泄露。
其中 stsCredentialScopes 包含 action,region,bucket,prefix几个字段。
region 默认为空字符串。
bucket 为您传入的 bucketId，auto 模式下则为 auto。
prefix 前缀目录，默认为空字符串。
action 则可能会包含如下字段：
//简单上传操作 
"name/cos:PutObject",
//表单上传对象 
"name/cos:PostObject",
//分块上传：初始化分块操作 
"name/cos:InitiateMultipartUpload",
//分块上传：List 进行中的分块上传
"name/cos:ListMultipartUploads",
//分块上传：List 已上传分块操作 
"name/cos:ListParts",
//分块上传：上传分块操作 
"name/cos:UploadPart",
//分块上传：完成所有分块上传操作 
"name/cos:CompleteMultipartUpload",
//取消分块上传操作 
"name/cos:AbortMultipartUpload"
如果您针对不同的上传应用有不同的鉴权凭证，可以根据以上信息进行区分。

创建上传对象

创建TXUploader的时候，有两种模式，分别是subApp和bucket，分别对应自动模式和指定桶模式。
两种模式分别对应构造方法为TXUploader.bucketMode 和 TXUploader.autoMode。
此外还需要传入您的子应用 id，示例代码如下：
_uploader = TXUploader.bucketMode(0000000000, "xxxxxxxxxxxxx");

设置上传回调

创建完成之后，如果需要对上传状态进行监控，需要设置回调。回调均为可选实现，业务可根据自身需求进行实现。设置回调示例代码如下：
 _uploader?.setUploadCallback = FTXUploadCallback(
  successCallBack: (header, result) async {
    
   // 上传成功回调，此处可从 result 中获取上传完成后的文件 url， result.accessUrl

    }, failCallBack: (clientException, serviceException) async {
    
    // 上传失败回调，可在此处处理错误信息
    
    }, progressCallBack: (complete, target) {
    
    // 上传进度回调，complete 为已上传的字节数量，target为总数量
    
    },stateCallBack:(state) {
    
    // 上传状态变更回调
    
    }
    , startUploadCallback: (bucket, cosKey, uploadId) async {
    
    // 上传开始回调，此处可以获得 uploadId，可以进行存储，后续如果文件上传到一半，可以传入 uploadId 进行续传
    
    });

开始上传

根据业务需要，可选是否设置上传配置。
UploadConfig uploadConfig = UploadConfig();
uploadConfig.sliceSizeForUpload = 1024 * 1024 * 2; // 默认设置分片大小2M，可根据项目需要来调整
uploadConfig.isHttps = true; // 是否开启 https，默认开启
uploadConfig.enableVerification = true; // 是否开启分片校验，默认开启

配置上传参数

上传参数 UploadParams 参数如下
参数
含义
localFilePath
本地文件路径，必传。
fileKey
上传文件键值，为上传到服务器的文件名，必传。
uploadId
上传 uploadId，可不传，传入则会续传之前该 uploadId 没有上传的部分。
uploadConfig
上传配置，可不传。
配置完成后，可以开始上传，示例如下：
int? code = await _uploader?.upload(params);
if (code == TXUploadCode.TX_UPLOAD_OK) {
  showResult("正在上传");
} else {
  showResult("上传 code$code");
}
上传 code 的返回值：
TXUploadCode.TX_UPLOAD_OK 代表调用成功。
TXUploadCode.TX_UPLOAD_BUSY 代表该 TXUploader 已经在处理上传，拒绝再次调用。
TX_FILE_NOT_FOUND 代表传入的文件路径不存在。
中国站
目录