#uploadFile
上传本地文件,并返回可用于监听进度和中断上传的 UploadTask。
#扫码预览
#支持版本
前端库版本不低于 0.0.39。
#支持平台
| 平台 | 支持情况 |
|---|---|
| Android | 支持 |
| iOS | 支持 |
| PC | 不支持 |
| HarmonyOS | 不支持 |
#支持场景
| 场景 | 支持情况 |
|---|---|
| 页面 | 支持 |
| 卡片 | 不支持 |
#接入准备
#前置条件
- url 需命中当前应用插件的上传域名白名单,filePath 需指向当前应用插件可访问的本地文件
#使用说明
uploadFile 会同步返回可监听、可中断的 Promise 任务对象。
建议在调用后立即注册进度和响应头监听;不再需要上传时调用 UploadTask.abort。
- 上传成功时 Promise resolve,上传失败或取消时 Promise reject;任务结束或不再使用时应移除监听,必要时调用 abort。
#调用方式
#异步 API
uploadFile(params: UploadFileParams): UploadTask#入参
| 名称 | 类型 | 必填 | 默认值 | 约束 | 说明 |
|---|---|---|---|---|---|
enableProfile | false | 否 | false | - | 是否返回网络 profile。豆包当前仅支持 false。 |
filePath | string | 是 | - | - | 要上传文件资源的本地路径。 |
formData | Record<string, unknown> | 否 | - | - | 额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。 |
header | Record<string, string> | 否 | - | - | HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等由豆包客户端管理的字段不会被业务覆盖。 |
name | string | 是 | - | - | 文件对应的 form field name/key,服务端通过该 key 获取文件内容;multipart filename 使用 filePath 的 basename。 |
timeout | number | 否 | - | - | 超时时间,单位 ms;不传时使用豆包客户端的默认超时配置。 |
url | string | 是 | - | - | 开发者服务器地址,需为完整的 HTTP/HTTPS URL,并通过豆包配置的上传域名白名单校验。 |
#调用示例
import { uploadFile } from '@doubao-dev/framework/api';
const task = uploadFile({
url: 'https://example.com/upload',
filePath: 'ttfile://temp/example.png',
name: 'file',
formData: { scene: 'profile' }
});
task
.then((result) => {
console.log(result.statusCode, result.data);
})
.catch((error) => {
console.error(error);
})
.finally(() => {
console.log('upload finished');
});
task.onProgressUpdate((event) => {
console.log(event.progress, event.totalBytesSent);
});
task.onHeadersReceived((event) => {
console.log(event.header);
});
// 不再需要上传时中断任务。
// task.abort();#成功返回
| 名称 | 类型 | 必返 | 说明 |
|---|---|---|---|
data | string | 否 | 服务器返回的数据。 |
header | Record<string, string> | 是 | HTTP 响应头。 |
statusCode | number | 是 | HTTP 状态码。 |
#返回示例
{
"statusCode": 200,
"header": {
"content-type": "application/json"
},
"data": "{\"ok\":true}"
}#错误处理
错误对象和通用错误码见 通用错误处理。
#失败示例
{
"errMsg": "uploadFile:fail request time out",
"errNo": 121920,
"errorCode": 121920
}#错误码
| errNo | errMsg | 平台 | 触发条件 | 处理建议 |
|---|---|---|---|---|
121999 | uploadFile:fail url is invalid | Android、iOS | url 缺失或不是有效上传地址 | 传入完整的 HTTP/HTTPS URL |
121999 | uploadFile:fail name is required | Android、iOS | name 缺失或为空 | 传入服务端接收文件所使用的 form field name |
121901 | uploadFile:fail url not in domain list | Android、iOS | url 未命中上传域名白名单 | 在应用插件配置中添加上传域名后重试 |
121902 | uploadFile:fail no file exist | Android、iOS | filePath 为空、文件不存在或路径不是文件 | 使用文件 API 获取当前应用插件可访问的有效文件路径 |
121905 | uploadFile:fail upload file abort | Android、iOS | 调用 UploadTask.abort 中断上传 | 按业务需要处理取消状态,无需自动重试 |
121906 | uploadFile:fail file path permission denied | Android、iOS | 当前应用插件无权访问 filePath | 改用当前应用插件目录内的文件 |
121920 | uploadFile:fail request time out | Android、iOS | 上传超过豆包客户端的超时时间 | 检查网络或设置合理的 timeout 后重试 |
121985 | uploadFile:fail network unavailable | Android、iOS | 当前网络不可用 | 恢复网络连接后重试 |
121991 | uploadFile:fail network error | Android、iOS | 上传过程中发生网络错误 | 检查网络和服务端状态后重试 |
121992 | uploadFile:fail enableProfile is not supported | Android、iOS | enableProfile 设置为 true | 移除 enableProfile 或设置为 false |