文件上傳、下載uniapp——uploadFile、downloadFile

uni.app中中的上傳、下載接口，分包為uploadFile 和downloadFile。

uni.uploadFile(OBJECT)

定義

將本地資源上傳到開發者服務器，客戶端發起一個 POST 請求，其中 content-type 為 multipart/form-data。

• 如頁面通過 uni.chooseImage 等接口獲取到一個本地資源的臨時文件路徑后，可通過此接口將本地資源上傳到指定服務器。另外選擇和上傳非圖像、視頻文件參考：https://ask.dcloud.net.cn/article/35547。
• 在各個小程序平台運行時，網絡相關的 API 在使用前需要配置域名白名單。
• 推薦開發者上傳到uniCloud，uniCloud提供了免費CDN和更好的易用性，包括安全的cdn直傳。uniCloud的上傳API：https://uniapp.dcloud.io/uniCloud/storage?id=uploadfile ；封裝的更完善的uni-file-picker組件，文件選擇、上傳到uniCloud，一站式集成。

參數

參數名	類型	必填	說明	平台差異
url	String	是	開發者服務器url
files	Array	是（files和filePath選其一）	需要上傳的文件列表。使用 files 時，filePath 和 name 不生效。	App、H5（ 2.6.15+）
fileType	String	見平台差異說明	文件類型，image/video/audio	僅支付寶小程序，且必填。
file	File	否	要上傳的文件對象。	僅H5（2.6.15+）支持
filePath	String	是（files和filePath選其一）	要上傳文件資源的路徑。
name	String	是	文件對應的 key , 開發者在服務器端通過這個 key 可以獲取到文件二進制內容
header	Object	否	HTTP 請求 Header, header 中不能設置 Referer。
timeout	Number	否	超時時間，單位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)
formData	Object	否	HTTP 請求中其他額外的 form data
success	Function	否	接口調用成功的回調函數
fail	Function	否	接口調用失敗的回調函數
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）

注：

• App支持多文件上傳，微信小程序只支持單文件上傳，傳多個文件需要反復調用本API。所以跨端的寫法就是循環調用本API。
• hello uni-app中的客服反饋，支持多圖上傳。uni-app插件市場中也有多個封裝的組件。
• App平台選擇和上傳非圖像、視頻文件，參考https://ask.dcloud.net.cn/article/35547
• 網絡請求的 超時時間 可以統一在 manifest.json 中配置 networkTimeout。
• 支付寶小程序開發工具上傳文件返回的http狀態碼為字符串形式，支付寶小程序真機返回的狀態碼為數字形式

files參數說明

參數名	類型	必填	說明
name	String	否	multipart 提交時，表單的項目名，默認為 file
file	File	否	要上傳的文件對象，僅H5（2.6.15+）支持
uri	String	是	文件的本地地址

注：如果 name 不填或填的值相同，可能導致服務端讀取文件時只能讀取到一個文件。

返回值

參數	類型	說明
data	String	開發者服務器返回的數據
statusCode	Number	開發者服務器返回的 HTTP 狀態碼

 實例

uni.chooseImage({
    success: (chooseImageRes) => {
        const tempFilePaths = chooseImageRes.tempFilePaths;
        uni.uploadFile({
            url: 'https://www.example.com/upload', //僅為示例，非真實的接口地址
            filePath: tempFilePaths[0],
            name: 'file',
            formData: {
                'user': 'test'
            },
            success: (uploadFileRes) => {
                console.log(uploadFileRes.data);
            }
        });
    }
});

監聽上傳進度

• 如果希望返回一個 uploadTask 對象，需要至少傳入 success / fail / complete 參數中的一個。

• 如果沒有傳入 success / fail / complete 參數，則會返回封裝后的 Promise 對象：Promise 封裝。通過 uploadTask，可監聽上傳進度變化事件，以及取消上傳任務。

uploadTask 對象的方法列表

方法	參數	說明
abort		中斷上傳任務
onProgressUpdate	callback	監聽上傳進度變化
onHeadersReceived	callback	監聽 HTTP Response Header 事件。會比請求完成事件更早,僅微信小程序平台支持，規范詳情
offProgressUpdate	callback	取消監聽上傳進度變化事件，僅微信小程序平台支持，規范詳情
offHeadersReceived	callback	取消監聽 HTTP Response Header 事件，僅微信小程序平台支持，規范詳情

onProgressUpdate 返回參數說明

參數	類型	說明
progress	Number	上傳進度百分比
totalBytesSent	Number	已經上傳的數據長度，單位 Bytes
totalBytesExpectedToSend	Number	預期需要上傳的數據總長度，單位 Bytes

示例

uni.chooseImage({
    success: (chooseImageRes) => {
        const tempFilePaths = chooseImageRes.tempFilePaths;
        const uploadTask = uni.uploadFile({
            url: 'https://www.example.com/upload', //僅為示例，非真實的接口地址
            filePath: tempFilePaths[0],
            name: 'file',
            formData: {
                'user': 'test'
            },
            success: (uploadFileRes) => {
                console.log(uploadFileRes.data);
            }
        });

        uploadTask.onProgressUpdate((res) => {
            console.log('上傳進度' + res.progress);
            console.log('已經上傳的數據長度' + res.totalBytesSent);
            console.log('預期需要上傳的數據總長度' + res.totalBytesExpectedToSend);

            // 測試條件，取消上傳任務。
            if (res.progress > 50) {
                uploadTask.abort();
            }
        });
    }
});

uni.downloadFile(OBJECT)

定義

下載文件資源到本地，客戶端直接發起一個 HTTP GET 請求，返回文件的本地臨時路徑。

在各個小程序平台運行時，網絡相關的 API 在使用前需要配置域名白名單。在h5上是跨域的，用戶需要處理好跨域問題。

參數

參數名	類型	必填	說明	平台差異說明
url	String	是	下載資源的 url
header	Object	否	HTTP 請求 Header, header 中不能設置 Referer。
timeout	Number	否	超時時間，單位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)
success	Function	否	下載成功后以 tempFilePath 的形式傳給頁面，res = {tempFilePath: '文件的臨時路徑'}
fail	Function	否	接口調用失敗的回調函數
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）
filePath	string	否	指定文件下載后存儲的路徑 (本地路徑)	微信小程序（IOS小程序保存到相冊需要添加此字段才可以正常保存）

文件的臨時路徑，在應用本次啟動期間可以正常使用，如需持久保存，需在主動調用 uni.saveFile，才能在應用下次啟動時訪問得到。

返回

參數	類型	說明
tempFilePath	String	臨時文件路徑，下載后的文件會存儲到一個臨時文件
statusCode	Number	開發者服務器返回的 HTTP 狀態碼

• 網絡請求的 超時時間 可以統一在 manifest.json 中配置 networkTimeout。

示例

uni.downloadFile({
    url: 'https://www.example.com/file/test', //僅為示例，並非真實的資源
    success: (res) => {
        if (res.statusCode === 200) {
            console.log('下載成功');
        }
    }
});

監聽下載進度

• 如果希望返回一個 downloadTask 對象，需要至少傳入 success / fail / complete 參數中的一個。
• 如果沒有傳入 success / fail / complete 參數，則會返回封裝后的 Promise 對象：Promise 封裝
• 通過 downloadTask，可監聽下載進度變化事件，以及取消下載任務。

downloadTask 對象的方法列表

方法	參數	說明	最低版本
abort		中斷下載任務	*
onProgressUpdate	callback	監聽下載進度變化	*
onHeadersReceived	callback	監聽 HTTP Response Header 事件，會比請求完成事件更早,僅微信小程序平台支持，規范詳情
offProgressUpdate	callback	取消監聽下載進度變化事件，僅微信小程序平台支持，規范詳情
offHeadersReceived	callback	取消監聽 HTTP Response Header 事件，僅微信小程序平台支持，規范詳情

onProgressUpdate 返回參數說明

參數	類型	說明
progress	Number	下載進度百分比
totalBytesWritten	Number	已經下載的數據長度，單位 Bytes
totalBytesExpectedToWrite	Number	預期需要下載的數據總長度，單位 Bytes

示例

const downloadTask = uni.downloadFile({
    url: 'http://www.example.com/file/test', //僅為示例，並非真實的資源
    success: (res) => {
        if (res.statusCode === 200) {
            console.log('下載成功');
        }
    }
});

downloadTask.onProgressUpdate((res) => {
    console.log('下載進度' + res.progress);
    console.log('已經下載的數據長度' + res.totalBytesWritten);
    console.log('預期需要下載的數據總長度' + res.totalBytesExpectedToWrite);

    // 測試條件，取消下載任務。
    if (res.progress > 50) {
        downloadTask.abort();
    }

參考網址

•  https://uniapp.dcloud.io/api/request/network-file?id=downloadfile