以 JavaScript 讀取檔案

Kayce Basques

Pete LePage

Thomas Steiner

選取使用者本機裝置上的檔案並進行互動，是最常用的網路功能之一。可讓使用者選取檔案並上傳到伺服器，例如分享相片或提交稅務文件時。也允許網站讀取及操控這些網站，而不需要在網路中傳輸資料。本頁面將逐步說明如何使用 JavaScript 與檔案互動。

新型 File System Access API

File System Access API 可讓使用者讀取及寫入使用者本機系統上的檔案和目錄。大部分以 Chromium 為基礎的瀏覽器 (例如 Chrome 和 Edge) 都支援這項技術。如要進一步瞭解，請參閱 File System Access API。

由於 File System Access API 並非與所有瀏覽器都相容，建議您使用 browser-fs-access。在可以使用新 API 的情況下，這個輔助程式庫會在可用時採用，並在不適用時改回使用舊版方法。

輕鬆處理檔案

本指南將說明如何使用舊版 JavaScript 方法與檔案互動。

選取多個檔案

選取檔案主要有兩種方法：使用 HTML 輸入元素和拖曳區域。

HTML 輸入元素

使用者選取檔案最簡單的方法，就是使用 <input type="file"> 元素，所有主要瀏覽器都支援此元素。使用者點選之後，就能使用作業系統內建的檔案選取 UI，選取一或多個檔案 (如果內含 multiple 屬性)。使用者選取一或多個檔案後，就會觸發元素的 change 事件。您可以存取 event.target.files 中的檔案清單，即 FileList 物件。FileList 中的每個項目都是 File 物件。

<!-- The `multiple` attribute lets users select multiple files. -->
<input type="file" id="file-selector" multiple>
<script>
  const fileSelector = document.getElementById('file-selector');
  fileSelector.addEventListener('change', (event) => {
    const fileList = event.target.files;
    console.log(fileList);
  });
</script>

注意： 請查看 window.showOpenFilePicker() 方法是否適用於您的用途。這樣不僅提供了檔案控制代碼，因此除了讀取以外，您也可以寫回檔案。此方法可以以折線形式填入。

以下範例可讓使用者使用作業系統內建的檔案選取 UI 選取多個檔案，然後將每個選取的檔案記錄到控制台。

限制使用者可選取的檔案類型

在某些情況下，您可能會想限制使用者可選取的檔案類型。舉例來說，圖片編輯應用程式應該只接受圖片，而非文字檔。如要設定檔案類型限制，請在輸入元素中加入 accept 屬性，指定系統可接受的檔案類型：

<input type="file" id="file-selector" accept=".jpg, .jpeg, .png">

自訂拖曳

在某些瀏覽器中，<input type="file"> 元素也是放置目標，可讓使用者將檔案拖曳到應用程式中。不過，這個放置目標較小，可能難以使用。相反地，使用 <input type="file"> 元素提供核心功能後，您就可以提供大型的自訂拖曳介面。

注意： 請檢查 DataTransferItem.getAsFileSystemHandle() 方法是否是您用途的替代方法。它提供了檔案控制代碼，因此除了讀取以外，您也可以寫回檔案。

選擇放置區域

下降途徑取決於應用程式設計。您可能只想讓部分視窗成為掉落介面，但可以使用整個視窗。

Squoosh 讓整個視窗變成放置區。

圖片壓縮應用程式 Squoosh 可讓使用者將圖片拖曳到視窗中的任何位置，然後按一下「Select a image」 (選取圖片) 來叫用 <input type="file"> 元素。無論您選擇哪種放置區域，請務必明確告知使用者，他們可以將檔案拖曳到該途徑上。

定義放置區

如要將元素設為拖曳區域，請為兩個事件建立事件監聽器：dragover 和 drop。dragover 事件會更新瀏覽器 UI，以視覺方式表示拖曳動作正在建立檔案副本。使用者將檔案放到途徑上後，就會觸發 drop 事件。與輸入元素一樣，您可以從 event.dataTransfer.files 存取檔案清單，也就是 FileList 物件。FileList 中的每個項目都是 File 物件。

const dropArea = document.getElementById('drop-area');

dropArea.addEventListener('dragover', (event) => {
  event.stopPropagation();
  event.preventDefault();
  // Style the drag-and-drop as a "copy file" operation.
  event.dataTransfer.dropEffect = 'copy';
});

dropArea.addEventListener('drop', (event) => {
  event.stopPropagation();
  event.preventDefault();
  const fileList = event.dataTransfer.files;
  console.log(fileList);
});

event.stopPropagation() 和 event.preventDefault() 會停止瀏覽器的預設行為，讓程式碼改為執行。如果沒有這類檔案，瀏覽器將會離開網頁，並開啟使用者拖放到瀏覽器視窗中的檔案。

如需實際示範，請參閱「自訂拖曳」。

那目錄呢？

很抱歉，不是良好的方式是使用 JavaScript 存取目錄。

<input type="file"> 元素的 webkitdirectory 屬性可讓使用者選擇目錄或目錄。除了 Android 版 Firefox 和 iOS 版 Safari 之外，大多數主要瀏覽器支援此功能。

注意： 請檢查 window.showDirectoryPicker() 方法是否是您用途的替代方法。這樣可提供目錄控制代碼，因此除了讀取以外，您還可寫回目錄。此方法可以以折線形式填入。

如果已啟用拖曳功能，使用者可能會嘗試將目錄拖曳至放置區域。放置事件發生時，會包含該目錄的 File 物件，但不會提供目錄內任何檔案的存取權。

讀取檔案中繼資料

File 物件包含檔案的中繼資料。大多數瀏覽器都會提供檔案名稱、檔案大小和 MIME 類型，但視平台而定，不同的瀏覽器可能會提供不同或額外的資訊。

function getMetadataForFileList(fileList) {
  for (const file of fileList) {
    // Not supported in Safari for iOS.
    const name = file.name ? file.name : 'NOT SUPPORTED';
    // Not supported in Firefox for Android or Opera for Android.
    const type = file.type ? file.type : 'NOT SUPPORTED';
    // Unknown cross-browser support.
    const size = file.size ? file.size : 'NOT SUPPORTED';
    console.log({file, name, type, size});
  }
}

您可以在 input-type-file 示範中查看實際運作情形。

讀取檔案的內容

您可以使用 FileReader 將 File 物件的內容讀取到記憶體中。您可以指示 FileReader 以陣列緩衝區、資料網址或文字的形式讀取檔案：

function readImage(file) {
  // Check if the file is an image.
  if (file.type && !file.type.startsWith('image/')) {
    console.log('File is not an image.', file.type, file);
    return;
  }

  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    img.src = event.target.result;
  });
  reader.readAsDataURL(file);
}

這個範例會讀取使用者提供的 File，然後將其轉換為資料網址，並使用該資料網址在 img 元素中顯示圖片。如要瞭解如何確認使用者已選取圖片檔，請參閱 read-image-file 示範。

監控檔案讀取的進度

讀取大型檔案時，建議您提供使用者體驗一些使用者體驗，讓使用者瞭解讀取的進度。這時請使用 FileReader 提供的 progress 事件。progress 事件有兩個屬性：loaded (讀取的數量) 和 total (讀取的數量)。

function readFile(file) {
  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    const result = event.target.result;
    // Do something with result
  });

  reader.addEventListener('progress', (event) => {
    if (event.loaded && event.total) {
      const percent = (event.loaded / event.total) * 100;
      console.log(`Progress: ${Math.round(percent)}`);
    }
  });
  reader.readAsDataURL(file);
}

主頁橫幅由 Vincent Botta 在 Unsplash 網站上提供