ファイル API

メモ: この機能はウェブワーカー内で利用可能です。

概念と使い方

ファイル API は、ウェブアプリケーションがファイルとそのコンテンツにアクセスできるようにするためのものです。

ウェブアプリケーションは、ユーザーがファイルを利用可能にしたとき、すなわち file 型の <input> 要素を使用するか、ドラッグ＆ドロップを介するかのどちらかでファイルにアクセスすることができるようになります。

このようにして利用可能になった一連のファイルは FileList オブジェクトとして表され、ウェブアプリケーションが個々の File オブジェクトを取得することができるようになっています。そして、 File オブジェクトから、ファイル名、サイズ、型、最終更新日時などのメタデータにアクセスすることができます。

File オブジェクトを FileReader オブジェクトに渡すことで、ファイルの内容にアクセスすることができます。 FileReader インターフェイスは非同期ですが、ウェブワーカーでのみ利用できる同期バージョンが FileReaderSync インターフェイスで提供されています。

他のファイル関連 API との関係

ファイルを扱う主要な API は他にも 2 つあります。ファイルとディレクトリー項目API とファイルシステム API です。

ファイル API は最も基本的な API です。ユーザーがフォーム要素の入力やドラッグ＆ドロップ操作という形で明示的に指定したファイルデータの読み取りと処理に対応しています。また、Blob を介してバイナリーデータを処理することもできます。

ファイルとディレクトリー項目 API は、ファイル API と同様に、ユーザーがフォーム入力やドラッグ＆ドロップ操作で提供するファイルを扱います。ただし、入力要素では単一のファイルではなく、ディレクトリーまたは複数のファイルの選択が可能になりました。この API は、ディレクトリーやファイルを処理する手段を提供します。これは主に Chrome 独自の発明です。他インターフェイスへの拡張はすべて webkit で始まる接頭辞が付与されていることがわかります。ファイルとディレクトリー項目 API には、その実装と標準化に関するより完全な経緯が記載されています。当初は完全な仮想ファイルシステムに対応するためのものでしたが、現在はユーザーが提供するデータに対する読み取り操作のみに対応しています。

ファイルシステム API は、ウェブアプリケーション向けに仮想ファイルシステムを提供します。これにより、アプリケーションは文書のオリジンに固有の仮想システム（オリジンプライベートファイルシステム (OPFS) と呼ばれる）にデータを永続的に格納することが可能です。ファイルシステムアクセス API は、ファイルシステムAPIをさらに拡張し、ユーザーの同意を得た上でウェブサイトがユーザーファイルの読み書きをすることができるようにします。ファイル API やファイルとディレクトリー項目 API とは異なり、ファイルシステム API は純粋な JavaScript で実装され、フォーム入力の処理は行いません。

インターフェイス

Blob

"Binary Large Object" を表し、不変の生データを持つファイルのようなオブジェクトを意味します。 Blob はテキストまたはバイナリーデータとして読み込むことができ、そのメソッドを使用してデータを処理できるように ReadableStream に変換されることがあります。

File

ファイルに関する情報を提供し、ウェブページ内の JavaScript がそのコンテンツにアクセスできるようにします。

FileList

HTML の <input> 要素の files プロパティが返す値です。これにより、 <input type="file"> 要素で選択されたファイルのリストにアクセスすることができます。また、ドラッグ & ドロップ API を用いてウェブコンテンツにドロップされたファイルのリストにも使用されます。この使用方法の詳細については、 DataTransfer オブジェクトを参照してください。

FileReader

ウェブアプリケーションが、ユーザーのコンピューターに保存されているファイル（または生データバッファー）の内容を、 File または Blob オブジェクトを使って非同期に読み込むことができるようにするもので、ファイルまたはデータを指定して読み込みます。

FileReaderSync

ウェブアプリケーションが、ユーザーのコンピューターに保存されているファイル（または生データバッファー）の内容を、 File または Blob オブジェクトを使って同期的に読み込むことができるようにするもので、ファイルまたはデータを指定して読み込みます。

他のインターフェイスの拡張

URL.createObjectURL()

File または Blob オブジェクトを取得するために使用できる URL を作成します。

URL.revokeObjectURL()

URL.createObjectURL() を呼び出して作成された既存のオブジェクト URL を解放します。

例

ファイルの読み取り

この例では、 file 型の <input> 要素を用意しており、ユーザーがファイルを選択すると、最初に選択したファイルの内容をテキストとして読み込み、結果を <div> で表示します。

HTML

html
<input type="file" />
<div class="output"></div>

CSS

css
.output {
  overflow: scroll;
  margin: 1rem 0;
  height: 200px;
}

JavaScript

js
const fileInput = document.querySelector("input[type=file]");
const output = document.querySelector(".output");

fileInput.addEventListener("change", async () => {
  const [file] = fileInput.files;

  if (file) {
    output.innerText = await file.text();
  }
});