JS實現單個或多個檔案批次下載的方法詳解

2023-02-28 18:00:40

前言

在前端Web開發中，下載檔案是一個很常見的需求，也有一些比較特殊的Case，比如下載檔案請求是一個POST、url不是同源的、批次下載檔案等。本文就介紹下幾種download解決方案，以及特殊Case的最佳方案選擇。

單個檔案Download

方案一：location.href or window.open

<a href={url} target="_blank">download</a>

window.location.href = url; // 當前tab
window.open(url); // 新tab

缺點：

1.只支援get請求，不支援post請求。

2.瀏覽器會根據header的content-type來判斷是下載檔案還是預覽檔案。

比如 txt png 等格式檔案，會在當前tab或新tab中預覽，而不是下載下來。

3.由於只支援get，會有url引數過長問題。

4.不能加request header，無法做許可權驗證等邏輯。

5.不支援自定義file name。

方案二：通過a標籤的download屬性

通過HTML a標籤的原生屬性，使用瀏覽器下載。

https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/a

<a href={url} download={fileName}>download</a>

function downloadFile(url, fileName) {
    const a = document.createElement('a');
    a.style.display = 'none';
    a.href = url;
    a.download = fileName;
    document.body.appendChild(a);
    a.click();
    document.body.removeChild(a);
}

優點：

都是走的瀏覽器下載檔案邏輯，不會預覽檔案。
當前tab開啟方式下載。
支援設定file name。

缺點：

只支援get請求，不支援post請求。
不能加request header，無法做許可權驗證等邏輯。
不支援跨域地址。

方案三：API請求

API傳送請求的方式，獲取檔案blog物件，然後通過URL.createObjectURL方法獲取download url，然後用方案二的<a download />方式下載。

// 封裝一個fetch download方法
async function fetchDownload(fetchUrl, method = "POST", body = null) {
    const response = await window.fetch(fetchUrl, {
        method,
        body: body ? JSON.stringify(body) : null,
        headers: {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "X-Requested-With": "XMLHttpRequest",
        },
    });
    const fileName = getFileName(response);
    const blob = await response.blob();
    const url = URL.createObjectURL(blob);
    return { blob, url, fileName }; // 返回blob、download url、fileName
}
// 根據response header獲取檔名
function getFileName(response) {
    const disposition = response.headers.get('Content-Disposition');

    // 本例格式是："attachment; filename="img.jpg""
    let fileName = disposition.split('filename=')[1].replaceAll('"', '');

    // 可以根據自己的格式來擷取檔名
    // 參考https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Content-Disposition
    // let fileName = '';
    // if (disposition && disposition.indexOf('attachment') !== -1) {
    //     const matches = /filename[^;=n]*=((['"]).*?2|[^;n]*)/.exec(disposition);
    //     fileName = matches?.[1]?.replace(/['"]/g, '');
    // }
    fileName = decodeURIComponent(fileName);
    return fileName;
}

// 頁面裡呼叫
// get
fetchDownload('/api/get/file?name=img.jpg', 'GET').then(({ blob, url, fileName }) => {
    downloadFile(url, fileName); // 呼叫方案二的download方法
});
// post
fetchDownload('/api/post/file', 'POST', { name: 'img.jpg' }).then(({ blob, url, fileName }) => {
    downloadFile(url, fileName);
});

URL.createObjectURL 生成的url如果過多會有效率問題，可以在合適的時機（download後）釋放掉。參考：developer.mozilla.org/zh-CN/docs/…

if (window.URL) {
    window.URL.revokeObjectURL(url);
} else {
    window.webkitURL.revokeObjectURL(url);
}

優點：

因為最後用的是方案二，所以滿足方案二的優點。
支援post請求、支援跨域（fetch本身支援）。
可以加request header。

缺點：

低版本瀏覽器不支援，可以通過'download' in document.createElement('a')判斷是否支援。
瀏覽器相容可能有問題，比如Safari、IOS Safari。

多個檔案批次Download

有些需求是，點一個按鈕需要把多個檔案同時download下來，有以下幾個方案可以實現。

方案一：按單個檔案download方式，迴圈依次下載

downloadFile("/files/file1.txt", "file1.txt");
downloadFile("/files/word1.docx", "word1.docx");
downloadFile("/files/img1.jpg", "img1.jpg");

利用上面的方案二的<a download />方式下載，會觸發瀏覽器是Download multiple files提示，如果選了Allow則會正常下載。

嘗試每個download之間加延遲，依然會彈提示。這個應該是瀏覽器機制問題了，沒辦法避免了。

方案二：前端打包成zip download

前端可以通過一個第三方庫 jszip，可以把多個檔案以blob、base64或純文字等形式，按自定義的檔案結構，壓縮成一個zip檔案，然後通過瀏覽器download下來。

官網：stuk.github.io/jszip/ 用法不難，直接看code：

// 先封裝一個方法，請求返回檔案blob
async function fetchBlob(fetchUrl, method = "POST", body = null) {
    const response = await window.fetch(fetchUrl, {
        method,
        body: body ? JSON.stringify(body) : null,
        headers: {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "X-Requested-With": "XMLHttpRequest",
        },
    });
    const blob = await response.blob();
    return blob;
}

const zip = new JSZip();
zip.file("Hello.txt", "Hello Worldn"); // 支援純文字等

zip.file("img1.jpg", fetchBlob('/api/get/file?name=img.jpg', 'GET')); // 支援Promise型別，需要返回資料型別是 String, Blob, ArrayBuffer, etc
zip.file("img2.jpg", fetchBlob('/api/post/file', 'POST', { name: 'img.jpg' })); // 同樣支援post請求，只要返回型別正確就行

const folder1 = zip.folder("folder01"); // 建立folder
folder1.file("img3.jpg", fetchBlob('/api/get/file?name=img.jpg', 'GET')); // folder裡建立檔案

zip.generateAsync({ type: "blob" }).then(blob => {
    const url = window.URL.createObjectURL(blob);
    downloadFile(url, "test.zip");
});

jszip還支援一些別的型別檔案壓縮，比如純文字、base64、binary等等，詳見：https://stuk.github.io/jszip/documentation/api_jszip/file_data.html

由於走的是純前端壓縮，所以會有延遲問題，走到最後download時才會調起瀏覽器下載，所以頁面可能需要一個效果來更新壓縮排度。zip.generateAsync方法就支援第二個引數，支援進度更新：

zip.generateAsync({ type: "blob" }, metadata => {
    const progress = metadata.percent.toFixed(2); // 保留2位小數
    console.log(metadata.currentFile, "progress: " + progress + " %");
}).then(blob => ... );