• JS API 列表
  • 基础
  • TTML
  • 网络
  • 网络 JS API 调用说明
  • 小程序 Cookie 机制
  • HTTP
  • UploadTask
  • tt.request
  • tt.downloadFile
  • RequestTask
  • tt.uploadFile
  • DownloadTask
  • WebSocket
  • EventSource
  • 媒体
  • 地图
  • 文件
  • 数据缓存
  • 地理位置
  • 设备
  • 画布
  • 界面
  • 页面导航
  • 开放接口
  • 行业开放
  • 第三方平台
  • 其它
  • 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(); }, }); }, });