tt.uploadFile
收藏
我的收藏

基础库 1.0.0 开始支持本方法,这是一个异步方法。

将本地资源上传到服务器。客户端发起一个 HTTPS POST 请求,其中 content-type 为 multipart/form-data。网络相关的 API 在使用前需要配置域名白名单。请参考网络请求

前提条件
业务背景
使用限制
  • Tip:目前 tt.uploadFile 暂不支持多文件上传,一次只能上传一个文件;
注意事项
  • Tip:header 不支持设置 referer 、user-agent、content-type 字段字段;
  • Tip:线上版本只支持 HTTPS 协议的请求,测试版同时支持 HTTP 和 HTTPS 协议,请注意提审版本中的协议配置;
  • Tip:上传本地图片需要本地路径,可以通过 tt.chooseImage 或者 tt.saveFile 获取到本地路径;
支持沙盒
相关教程

语法

tt.uploadFile(options)

参数说明

options 为 object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
headerobject

HTTP 请求的 header,详情见 header 说明

1.0.0
formDataobject
请求额外参数
1.0.0
timeoutnumber
超时时间,单位为毫秒
1.0.0
urlstring
开发者服务器地址
1.0.0
filePathstring

要上传文件资源的路径 (本地路径),可通过 tt.chooseVideott.chooseImagett.getSavedFileListtt.saveFile 等API获取本地路径

1.0.0
namestring
HTTP 请求的文件名
1.0.0
successfunction
接口调用成功的回调函数
1.0.0
failfunction
接口调用失败的回调函数
1.0.0
completefunction
接口调用结束的回调函数(调用成功、失败都会执行)
1.0.0

header 参数说明

  • 网络请求 header 中的 referer 不可设置。 其固定格式为:https://tmaservice.developer.toutiao.com/?appid={appid}&version={appVersion},其中 appid为小程序的 APPID,appVersion为小程序的版本号。
  • 网络请求 header 中的 user-agent 不可设置。 其固定格式分为:
    • iOS 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] webview/[插件版本]。
    • Android 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] PluginVersion/[插件版本]。
  • content-type 为 multipart/form-data。

回调成功

object 类型,属性如下:

属性名类型说明最低支持版本
errMsgstring
"uploadFile:ok"
1.0.0
statusCodenumber
返回 HTTP 状态码
1.0.0
profileobject
网络请求过程中一些调试信息,详情见 Profile 类型说明
1.0.0
datastring | object | arraybuffer
返回数据
1.0.0

profile 类型说明

object 类型,属性如下:

属性名类型说明最低支持版本
domainLookupStartnumber
DNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
1.0.0
domainLookupEndnumber
DNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
1.0.0
connectStartnumber
HTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间
1.0.0
connectEndnumber
HTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过
1.0.0
sslConnectionStartnumber
SSL 建立连接的时间,如果不是安全连接,则值为 0
1.0.0
sslConnectionEndnumber
SSL 建立完成的时间,如果不是安全连接,则值为 0
1.0.0
requestStartnumber
HTTP 请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间
1.0.0
requestEndnumber
HTTP 请求读取真实文档结束的时间
1.0.0
rttnumber
当次请求连接过程中实时 rtt
1.0.0
estimateNetTypestring
评估的网络状态 unknown, offline, slow 2g, 2g, 3g, 4g, last/0, 1, 2, 3, 4, 5, 6
1.0.0
throughputKbpsnumber
当前网络的实际下载 kbps
1.0.0
portnumber
当前请求的端口
1.0.0
socketReusedboolean
是否复用连接
1.0.0
sentBytesCountnumber
发送的字节数
1.0.0
receivedBytesCountnumber
收到的字节数
1.0.0

回调失败

object 类型,属性如下:

属性名类型说明最低支持版本
errMsgstring
"uploadFile:fail" + 详细错误信息
1.0.0

返回值

类型说明最低支持版本
object1.0.0

错误码

errorCodeerrMsgerrorType说明最低支持版本
121999url use invalid protocol, url == %s, url support protocol is %sD
url协议无效
1.0.0
121999url is invalid, url == %sD
url不合法
1.0.0
121901url not in domain list, url == %sD
url域名不在upload域名列表中
1.0.0
121902no file exist, filePath == %sD
文件不存在
1.0.0
121985network unavailableU
用户无网
1.0.0
121985network unavailableU
用户无网或抖音没有网络权限
1.0.0
121923network changedU
用户网络波动
1.0.0
121924dns errorU
用户网络波动
1.0.0
121925ssl errorU
用户网络波动
1.0.0
121926connection errorU
用户网络波动
1.0.0
121927interruptedU
用户网络波动
1.0.0
121928certificate errorD
url证书错误
1.0.0
121929url errorD
url无效
1.0.0
121991network error:%sF
小程序框架内部错误,有需要请拉客服咨询
1.0.0
121920request time outD
请求超时
1.0.0
121905upload file abortD
主动中断请求
1.0.0
121906file path permission denied, open '%s'D
文件路径没有读权限
1.0.0
121992%sF
小程序框架内部错误,有需要请拉客服咨询
1.0.0
121994app in backgroundU
小程序已进入后台
1.0.0

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

<view class="container"> <view class="body"> <view class="page-section"> <view class="page-body-info"> <block tt:if="{{localImagePath}}"> <image src="{{localImagePath}}" class="image" mode="aspectFit"></image> </block> <block tt:else> <view class="image-plus image-plus-nb" bindtap="chooseImage"> <view class="image-plus-horizontal"></view> <view class="image-plus-vertical"></view> </view> <view class="image-plus-text">选择图片</view> </block> </view> </view> </view> </view>
Page({ data: { localImagePath: "", }, chooseImage() { tt.chooseImage({ count: 1, sizeType: ["compressed"], sourceType: ["album"], success: (res) => { console.log("tt.chooseImage success", res); const localImagePath = res.tempFilePaths[0]; this.uploadFile(localImagePath); }, fail: (res) => { console.log("tt.chooseImage fail", res); }, complete: (res) => { console.log("tt.chooseImage complete", res); }, }); }, uploadFile(path) { tt.showLoading({ title: "正在上传", }); tt.uploadFile({ url: "https://jsonplaceholder.typicode.com/posts/", filePath: path, name: "data", header: { a: "b", }, formData: { c: "d", }, success: (res) => { console.log("tt.uploadFile success", res); this.setData({ localImagePath: path, }); }, fail: (res) => { console.log("tt.uploadFile fail", res); }, complete: (res) => { console.log("tt.uploadFile complete", res); tt.hideLoading(); }, }); }, });