ファイル API

1. はじめに

このセクションは参考情報です。

ウェブアプリケーションは、ユーザーがリモートサーバーにアップロードしたいファイルや、リッチなウェブアプリケーション内で操作したいファイルなど、できるだけ幅広いユーザー入力を操作できる能力を持つべきです。 本仕様は、ファイルの基本的な表現、ファイルリスト、ファイルアクセスによって発生するエラー、およびファイルをプログラムで読み取る方法を定義します。 さらに、本仕様は「生データ」を表すインターフェイスも定義しており、現行標準に準拠したユーザーエージェントのメインスレッドで非同期的に処理できます。 本仕様で定義されるインターフェイスやAPIは、ウェブプラットフォームで公開されている他のインターフェイスやAPIと組み合わせて利用できます。

File インターフェイスは通常、基盤となるファイルシステムから取得したファイルデータを表し、 Blob インターフェイス （「Binary Large Object」— この名称は Google Gears でウェブAPIに初めて導入されました） は変更不可能な生データを表します。File や Blob の読み込みは、メインスレッド上で非同期的に行うべきであり、スレッド化されたウェブアプリケーション内ではオプションで同期APIも利用できます。 ファイルの非同期APIを利用することで、ユーザーエージェントのメインスレッドがブロックされたり、UIが「フリーズ」するのを防げます。 本仕様は、イベントモデルに基づいた非同期APIを定義し、File や Blob のデータを読み取ったりアクセスできます。 FileReader オブジェクトは、イベントハンドラーの内容属性やイベント発火により、ファイルデータへ非同期的にアクセスするための読み取りメソッドを提供します。 イベントやイベントハンドラーを用いることで、別々のコードブロックが読み取りの進捗（特にリモートドライブやマウントされたドライブなど、ファイルアクセスのパフォーマンスがローカルドライブとは異なる場合）や読み込み時に発生するエラー状況を監視できます。 下記の例が参考になります。

function startRead() {
  // DOMからinput要素を取得

  var file = document.getElementById('file').files[0];
  if(file){
    getAsText(file);
  }
}

function getAsText(readFile) {

  var reader = new FileReader();

  // ファイルをUTF-16としてメモリに読み込む
  reader.readAsText(readFile, "UTF-16");

  // 進捗・成功・エラーを処理
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

function updateProgress(evt) {
  if (evt.lengthComputable) {
    // evt.loadedとevt.totalはProgressEventプロパティ
    var loaded = (evt.loaded / evt.total);
    if (loaded < 1) {
      // 進捗バーの長さを増加させる
      // style.width = (loaded * 200) + "px";
    }
  }
}

function loaded(evt) {
  // 読み込んだファイルデータを取得
  var fileString = evt.target.result;
  // UTF-16ファイルダンプを処理
  if(utils.regexp.isChinese(fileString)) {
    // 中国語文字 + 名前検証
  }
  else {
    // 他の文字セットテストを実行
  }
  // xhr.send(fileString)
}

function errorHandler(evt) {
  if(evt.target.error.name == "NotReadableError") {
    // ファイルを読み取れませんでした
  }
}

2. 用語とアルゴリズム

この仕様書で アルゴリズムを終了する と記載されている場合、ユーザーエージェントは現在実行中のステップを完了した後にアルゴリズムを終了しなければなりません。 本仕様で定義される非同期 読み込みメソッドは、該当するアルゴリズムの終了前に戻る場合があり、 abort() の呼び出しで終了することができます。

この仕様書のアルゴリズムとステップでは、以下の数学的演算を使用します：

• max(a,b) は a と b のうち大きい方を返します。 実行は常に WebIDL [WebIDL] で定義される整数値で行われます。 例えば max(6,4) の結果は 6 です。 この演算は ECMAScript [ECMA-262] でも定義されています。

• min(a,b) は a と b のうち小さい方を返します。 実行は常に WebIDL [WebIDL] で定義される整数値で行われます。 例えば min(6,4) の結果は 4 です。 この演算は ECMAScript [ECMA-262] でも定義されています。

• <（より小さい）、≤（以下）、>（より大きい）などの数学的比較は ECMAScript [ECMA-262] と同様です。

Unix Epoch という用語は、 本仕様書では 1970年1月1日 00:00:00 UTC （または 1970-01-01T00:00:00Z ISO 8601）を指します。 これは ECMA-262 [ECMA-262] で概念的に "0" とされる時刻と同じです。

3. Blobインターフェイスとバイナリデータ

Blob オブジェクトはバイト列を参照し、 size属性はバイト列全体のバイト数を示し、 type属性は バイト列のメディア型を表すASCII小文字列です。

各Blobは内部にスナップショット状態を持ち、 その値は基盤となるストレージの状態に初期化されます（ストレージが存在する場合）。 スナップショット状態の詳細な規定はFileに記載されています。

[Exposed=(Window,Worker), Serializable]
interface Blob {
  constructor(optional sequence<BlobPart> blobParts,
              optional BlobPropertyBag options = {});

  readonly attribute unsigned long long size;
  readonly attribute DOMString type;

  // Blobをバイト範囲のチャンクに分割
  Blob slice(optional [Clamp] long long start,
            optional [Clamp] long long end,
            optional DOMString contentType);

  // Blobから読み込む
  [NewObject] ReadableStream stream();
  [NewObject] Promise<USVString> text();
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] Promise<Uint8Array> bytes();
};

enum EndingType { "transparent", "native" };

dictionary BlobPropertyBag {
  DOMString type = "";
  EndingType endings = "transparent";
};

typedef (BufferSource or Blob or USVString) BlobPart;

Blobオブジェクトはシリアライズ可能オブジェクトです。そのシリアライズ手順は、valueとserializedが与えられた場合、次の通りです：

1. serialized.[[SnapshotState]]にvalueのスナップショット状態を設定する。

2. serialized.[[ByteSequence]]にvalueの基盤となるバイト列を設定する。

そのデシリアライズ手順は、serializedとvalueが与えられた場合、次の通りです：

1. valueのスナップショット状態にserialized.[[SnapshotState]]を設定する。

2. valueの基盤となるバイト列にserialized.[[ByteSequence]]を設定する。

3.1. コンストラクター

3.1.1. コンストラクターパラメーター

Blob() コンストラクターは以下のパラメーターで呼び出せます：

blobParts sequence

以下の型の要素を任意の数・順序で受け取ります：

• BufferSource 要素。

• Blob 要素。

• USVString 要素。

省略可能な BlobPropertyBag

以下の省略可能なメンバーを受け取ります：

• type: Blob のメディア型を表すASCII小文字列。このメンバーの規定は § 3.1 コンストラクター 参照。

• endings: "transparent" または "native" の値を取ることができるenum。デフォルト値は "transparent"。 "native" に設定した場合、 USVString 要素の改行がネイティブ形式に変換されます。

// 新しいBlobオブジェクトを作成

var a = new Blob();

// 1024バイトのArrayBufferを作成
// bufferはFile読み込みで取得することも可能

var buffer = new ArrayBuffer(1024);

// bufferを元にArrayBufferViewオブジェクトを作成

var shorts = new Uint16Array(buffer, 512, 128);
var bytes = new Uint8Array(buffer, shorts.byteOffset + shorts.byteLength);

var b = new Blob(["foobarbazetcetc" + "birdiebirdieboo"], {type: "text/plain;charset=utf-8"});

var c = new Blob([b, shorts]);

var a = new Blob([b, c, bytes]);

var d = new Blob([buffer, b, c, bytes]);

3.2. 属性

size, 型 unsigned long long, 読み取り専用

byte 列のバイト数を返します。 取得時、準拠するユーザーエージェントは FileReader や FileReaderSync オブジェクトで読み取れるバイト総数を返すか、Blob に読み取り可能なバイトがない場合は 0 を返します。

type, 型 DOMString, 読み取り専用

Blob のメディア型を表すASCII小文字列です。 取得時、ユーザーエージェントは Blob の型をASCII小文字列として返し、 これをbyte 列に変換した場合、 解析可能な MIME 型となるか、 型が判別できない場合は空文字列（0バイト）を返します。

type 属性はウェブアプリケーション自身がコンストラクター呼び出しや slice() 呼び出しで設定できます。 これらの場合の規定は § 3.1 コンストラクター、§ 4.1 コンストラクター、 § 3.3.1 slice() メソッド を参照してください。 また、ユーザーエージェントが type を決定することもあり、 特にbyte 列がディスク上のファイル由来の場合は ファイル型ガイドラインに従って規定します。

注: Blob の型 t は、 解析可能な MIME 型とみなされ、 Blob オブジェクトの型を表すASCII文字列をバイト列に変換して MIME 型の解析アルゴリズムを実行して失敗しなければ成立します。

注: type 属性の利用はパッケージデータアルゴリズムに通知され、 fetchでblob URLを取得する際の Content-Type ヘッダーが決定されます。

3.3. メソッドとパラメーター

3.3.1. slice() メソッド

// DOMからinput要素を取得

var file = document.getElementById('file').files[0];
if(file)
{
  // fileの完全なコピーを作る
  // 下記2つの呼び出しは同じ意味

  var fileClone = file.slice();
  var fileClone2 = file.slice(0, file.size);

  // ファイルの中間から1/2チャンク分切り出す（負数利用）
  var fileChunkFromEnd = file.slice(-(Math.round(file.size/2)));

  // ファイル先頭から1/2チャンク分切り出す
  var fileChunkFromStart = file.slice(0, Math.round(file.size/2));

  // ファイル先頭から末尾150バイト手前まで切り出す
  var fileNoMetadata = file.slice(0, -150, "application/experimental");
}

3.3.2. stream() メソッド

stream() メソッドは呼び出されると、 get stream を this に対して呼び出した結果を返さなければなりません。

3.3.3. text() メソッド

text() メソッドは呼び出されると、以下のステップを実行します：

1. get stream を this に対して呼び出した結果の stream を取得する。

2. reader を reader取得で stream から取得する。 例外が発生した場合は、その例外でリジェクトされた新しいPromiseを返す。

3. promise を 全バイト読み出しで stream と reader で取得する。

4. promise の fulfill時にその最初の引数へ UTF-8デコード を実行した結果を返す。

注: この動作は readAsText() とは異なり、 Fetchのtext() とより一致するよう調整されています。 このメソッドは必ずUTF-8を使用しますが、FileReader はblobのtypeや渡されたencoding名によって異なるエンコーディングを利用できます。

3.3.4. arrayBuffer() メソッド

arrayBuffer() メソッドは呼び出されると、以下のステップを実行します：

1. get stream を this に対して呼び出した結果の stream を取得する。

2. reader を reader取得で stream から取得する。 例外が発生した場合は、その例外でリジェクトされた新しいPromiseを返す。

3. promise を 全バイト読み出しで stream と reader で取得する。

4. promise の fulfill時にその最初の引数を内容とする新しい ArrayBuffer を返す。

3.3.5. bytes() メソッド

bytes() メソッドは呼び出されると、以下のステップを実行します：

1. get stream を this に対して呼び出した結果の stream を取得する。

2. reader を reader取得で stream から取得する。 例外が発生した場合は、その例外でリジェクトされた新しいPromiseを返す。

3. promise を 全バイト読み出しで stream と reader で取得する。

4. promise の fulfill時にその最初の引数を内容とする新しい Uint8Array （ArrayBuffer でラップ）を返す。

4. Fileインターフェイス

File オブジェクトは Blob オブジェクトであり、 name 属性（文字列）を持ちます。 ウェブアプリケーション内でコンストラクターにより作成するか、 または基盤の（OS）ファイルシステムのファイル由来のバイト列への参照となります。

File オブジェクトがディスク上のファイル由来のバイト列参照の場合、 スナップショット状態は File オブジェクト作成時の ディスク上のファイルの状態に設定すべきです。

注: これはユーザーエージェント実装にとって容易ではなく、 must ではなく should としています [RFC2119]。 ユーザーエージェントは File オブジェクトの スナップショット状態を 参照取得時のディスクの状態に設定するよう努めるべきです。 参照取得後にディスク上のファイルが変更された場合、 File の スナップショット状態は 基盤ストレージの状態と異なるものとなります。 ユーザーエージェントは更新日時や他の仕組みを用いて スナップショット状態を管理してもよいですが、これは実装詳細です。

File オブジェクトがディスク上のファイル参照の場合、 ユーザーエージェントはそのファイルの type を返し、 以下のファイル型ガイドラインに従わなければなりません：

• ユーザーエージェントは type を ASCII小文字列として返し、そのバイト列が 解析可能なMIME型となるようにするか、 型が判定できない場合は空文字列（0バイト）を返す。

• ファイル型が text/plain の場合、ユーザーエージェントはメディア型のパラメータ辞書部分に charsetパラメータを追加してはなりません [MIMESNIFF]。

• ユーザーエージェントはエンコーディングの推定（統計的手法など）を行ってはなりません。

[Exposed=(Window,Worker), Serializable]
interface File : Blob {
  constructor(sequence<BlobPart> fileBits,
              USVString fileName,
              optional FilePropertyBag options = {});
  readonly attribute DOMString name;
  readonly attribute long long lastModified;
};

dictionary FilePropertyBag : BlobPropertyBag {
  long long lastModified;
};

File オブジェクトは シリアライズ可能オブジェクトです。そのシリアライズ手順は value と serialized が与えられた場合：

1. serialized.[[SnapshotState]] に value の スナップショット状態を設定する。

2. serialized.[[ByteSequence]] に value の基盤となるバイト列を設定する。

3. serialized.[[Name]] に value の name 属性の値を設定する。

4. serialized.[[LastModified]] に value の lastModified 属性の値を設定する。

デシリアライズ手順は、value と serialized が与えられた場合：

1. value の スナップショット状態に serialized.[[SnapshotState]] を設定する。

2. value の基盤となるバイト列に serialized.[[ByteSequence]] を設定する。

3. value の name 属性の値を serialized.[[Name]] で初期化する。

4. value の lastModified 属性の値を serialized.[[LastModified]] で初期化する。

4.1. コンストラクター

4.1.1. コンストラクターパラメーター

File() コンストラクターは以下のパラメーターで呼び出せます：

fileBits sequence

以下の要素を任意の数・順序で受け取ります：

• BufferSource 要素。

• Blob 要素（File 要素を含む）。

• USVString 要素。

fileName パラメーター

USVString 型でファイル名を表します。規定は § 4.1 コンストラクター を参照してください。

省略可能な FilePropertyBag 辞書

BlobPropertyBag のメンバーに加え、以下のメンバーを持ちます：

• 省略可能な lastModified メンバー（long long型）。規定は § 4.1 コンストラクター 参照。

4.2. 属性

name, 型 DOMString, 読み取り専用

ファイルの名前。 取得時はファイル名（文字列）を返します。 OSファイルシステムごとに様々なファイル名表現や規約がありますが、ここではパス情報を含まない単なる名前です。 取得時に情報が取得できない場合は空文字列を返します。 File オブジェクトがコンストラクターで生成された場合、詳細な規定は § 4.1 コンストラクター にあります。

lastModified, 型 long long, 読み取り専用

ファイルの最終更新日時。 取得時、ユーザーエージェントがこの情報を取得できる場合は、ファイルの最終更新時刻（Unix Epochからのミリ秒数）を long long 型で返します。 更新日時が不明な場合は、現在日時（Unix Epochからのミリ秒数）を long long 型で返します。これは Date.now() [ECMA-262] と同等です。 File オブジェクトがコンストラクターで生成された場合、詳細な規定は § 4.1 コンストラクター にあります。

File インターフェイスは FileList 型属性を公開するオブジェクトで利用できます（HTML [HTML] で定義）。 File インターフェイスは Blob を継承し、不変（immutable）です。そのため、読み込み操作開始時にメモリ上に読み込まれるファイルデータを表します。 ユーザーエージェントは、読み込み時点でファイルが存在しない場合は エラーとして処理し、 Web Worker [Workers] で FileReaderSync を使った場合は NotFoundError 例外を投げ、 error イベントを発火する場合は error 属性で NotFoundError を返します。

var file = document.getElementById("filePicker").files[0];
var date = new Date(file.lastModified);
println("ファイル「" + file.name + "」は " + date.toDateString() + " に更新されました。");

...

// 特定の最終更新日時でファイルを生成

var d = new Date(2013, 12, 5, 16, 23, 45, 600);
var generatedFile = new File(["Rough Draft ...."], "Draft1.txt", {type: "text/plain", lastModified: d})

...

5. FileListインターフェイス

注: FileList インターフェイスは「リスクあり」とみなされるべきです。 現行標準の動向として、このようなインターフェイスはECMAScript Arrayプラットフォームオブジェクトに置き換えられる傾向があります [ECMA-262]。 特に、filelist.item(0)のような構文はリスクがありますが、 他のほとんどの FileList のプログラム的利用は、 最終的に Array型へ移行しても影響を受ける可能性は低いです。

このインターフェイスは File オブジェクトのリストです。

[Exposed=(Window,Worker), Serializable]
interface FileList {
  getter File? item(unsigned long index);
  readonly attribute unsigned long length;
};

FileList オブジェクトはシリアライズ可能オブジェクトです。そのシリアライズ手順は value と serialized が与えられた場合：

1. serialized.[[Files]] に空のリストを設定する。

2. value の各 file について、file のサブシリアライズを serialized.[[Files]] に追加する。

デシリアライズ手順は serialized と value が与えられた場合：

1. 各 file を serialized.[[Files]] から、 file のサブデシリアライズを value に追加する。

// uploadData は form要素
// fileChooser は 'file' 型の input要素
var file = document.forms['uploadData']['fileChooser'].files[0];

// 別構文
// var file = document.forms['uploadData']['fileChooser'].files.item(0);

if(file)
{
  // ファイル操作を実施
}

5.1. 属性

length, 型 unsigned long, 読み取り専用

FileList オブジェクト内のファイル数を返すこと。 ファイルがない場合は0を返すこと。

5.2. メソッドとパラメーター

item(index)

FileList内のindex番目のFileオブジェクトを返すこと。 FileList内にindex番目のFileオブジェクトがない場合、このメソッドはnullを返すこと。

indexは、ユーザーエージェントによってFileList内のFileオブジェクトの位置を示す値として扱われる。 0が最初のファイルを示す。サポートされるプロパティインデックスは、0からFileListオブジェクトが表すFileオブジェクト数-1までの数字。 ファイルオブジェクトがない場合は、サポートされるプロパティインデックスも存在しない。

注: HTMLInputElement インターフェイスは FileList 型の読み取り専用属性を持っており、上記例でアクセスされています。 FileList 型の読み取り専用属性を持つ他のインターフェイスには、 DataTransfer インターフェイスなどがあります。

6. データの読み込み

6.1. ファイル読み込みタスクソース

本仕様は新しい汎用 タスクソースである ファイル読み込みタスクソース を定義します。 これは本仕様でキューされるすべての タスクで、 Blob や File オブジェクトに関連付けられたバイト列を読み取るために利用されます。 バイナリデータの非同期読み取りに反応して発火する機能に使用されます。

6.2. FileReader API

[Exposed=(Window,Worker)]
interface FileReader: EventTarget {
  constructor();
  // 非同期読み取りメソッド
  undefined readAsArrayBuffer(Blob blob);
  undefined readAsBinaryString(Blob blob);
  undefined readAsText(Blob blob, optional DOMString encoding);
  undefined readAsDataURL(Blob blob);

  undefined abort();

  // 状態
  const unsigned short EMPTY = 0;
  const unsigned short LOADING = 1;
  const unsigned short DONE = 2;

  readonly attribute unsigned short readyState;

  // FileまたはBlobデータ
  readonly attribute (DOMString or ArrayBuffer)? result;

  readonly attribute DOMException? error;

  // イベントハンドラー属性
  attribute EventHandler onloadstart;
  attribute EventHandler onprogress;
  attribute EventHandler onload;
  attribute EventHandler onabort;
  attribute EventHandler onerror;
  attribute EventHandler onloadend;
};

FileReader には 状態（"empty"、"loading"、"done"）があり、初期値は "empty" です。

FileReader には 結果（null、DOMString、ArrayBuffer）があり、初期値は null です。

FileReader には エラー（null または DOMException）があり、初期値は null です。

FileReader() コンストラクターは呼び出されると新しい FileReader オブジェクトを返します。

readyState 属性のgetterは、 thisの状態ごとに次のステップを実行します：

"empty"

EMPTY を返す

"loading"

LOADING を返す

"done"

DONE を返す

result 属性のgetterは、 thisの結果を返します。

error 属性のgetterは、 thisのエラーを返します。

6.2.1. イベントハンドラー内容属性

以下は イベントハンドラー内容属性（および対応する イベントハンドラーイベント型）であり、 ユーザーエージェントは FileReader 上でDOM属性としてサポートしなければなりません：

6.2.2. FileReaderの状態

6.2.3. ファイルやBlobの読み込み

FileReader インターフェイスは複数の 非同期読み取りメソッド—​readAsArrayBuffer(), readAsBinaryString(), readAsText() および readAsDataURL() を提供し、ファイルをメモリに読み込みます。

注: 同じ FileReader オブジェクトで複数の読み込みメソッドを同時に呼び出した場合、 ユーザーエージェントは InvalidStateError を、readyState = LOADING 状態のときに呼ばれた読み込みメソッドに対して投げます。

(FileReaderSync は複数の 同期読み取りメソッドを提供します。 FileReader および FileReaderSync の同期・非同期読み取りメソッドを総称して 読み込みメソッドと呼びます。)

6.2.3.1. readAsDataURL() メソッド

readAsDataURL(blob) メソッドは呼び出されると、 blob に対して DataURL で 読み込み操作を開始しなければなりません。

6.2.3.2. readAsText() メソッド

readAsText(blob, encoding) メソッドは呼び出されると、 blob に対して Text と encoding で 読み込み操作を開始しなければなりません。

6.2.3.3. readAsArrayBuffer()

readAsArrayBuffer(blob) メソッドは呼び出されると、 blob に対して ArrayBuffer で 読み込み操作を開始しなければなりません。

6.2.3.4. readAsBinaryString() メソッド

readAsBinaryString(blob) メソッドは呼び出されると、 blob に対して BinaryString で 読み込み操作を開始しなければなりません。

注: readAsArrayBuffer() の利用が readAsBinaryString() より推奨されます。 readAsBinaryString() は後方互換のために提供されています。

6.2.3.5. abort() メソッド

abort() メソッドが呼ばれると、 ユーザーエージェントは以下のステップを実行しなければなりません：

1. this の 状態が "empty" または this の 状態が "done" の場合、 this の 結果 を null に設定し、このアルゴリズムを終了する。

2. this の 状態が "loading" の場合、 this の 状態 を "done" に設定し、this の 結果 を null に設定する。

3. もし タスク が this 由来で ファイル読み込みタスクソース の関連付けられた タスクキュー に存在する場合、 それらの タスク をそのタスクキューから削除する。

4. 処理中の 読み込みメソッド の アルゴリズムを終了する。

5. abort進捗イベントを this に発火する。

6. this の 状態が "loading" でなければ、loadend進捗イベントを this に発火する。

6.3. データのパッケージ化

6.4. イベント

FileReader オブジェクトは本仕様におけるすべてのイベントのイベントターゲットでなければなりません。

本仕様において 進捗イベントを発火する（ある ProgressEvent e を、指定した FileReader reader に対して発火する）と言った場合、以下が規定事項です：

• 進捗イベント e はバブルしません。e.bubbles は false でなければなりません [DOM]

• 進捗イベント e はキャンセル不可です。e.cancelable は false でなければなりません [DOM]

6.4.1. イベント一覧

以下は 発火される FileReader オブジェクト上のイベントです。

6.4.2. イベント不変条件まとめ

この節は参考情報です。

本仕様の非同期 読み込みメソッド に関する イベント発火の不変条件は以下の通りです：

1. loadstart が発火したら、対応する loadend が読み込み完了時に発火します。ただし以下の場合は除く：

   • 読み込みメソッドが abort() でキャンセルされ、さらに新たな 読み込みメソッドが呼ばれた場合

   • load イベントのハンドラ関数が新たな読み込みを開始した場合

   • error イベントのハンドラ関数が新たな読み込みを開始した場合

   注: loadstart と loadend は1対1で対応するものではありません。

   この例は「リードチェイン」を示します。イベントハンドラ内で別の読み込みを開始し、最初の読み込みが継続する場合です。

   // 以下のようなコード…
   reader.readAsText(file);
   reader.onload = function(){reader.readAsText(alternateFile);}
   
   .....
   
   //... 最初の読み込みでは loadend イベントは発火しない
   
   reader.readAsText(file);
   reader.abort();
   reader.onabort = function(){reader.readAsText(updatedFile);}
   
   //... 最初の読み込みでは loadend イベントは発火しない
   

2. progress イベントは blob がメモリに完全に読み込まれたときに1回発火します。

3. progress イベントは loadstart より前には発火しません。

4. progress イベントは abort、load、error のいずれかが発火した後には発火しません。 1つの読み込みについては abort、load、 error のいずれか1つだけが発火します。

5. abort、load、 error イベントは loadend の後には発火しません。

6.5. スレッドでの読み込み

Web Workersでは、同期的な File や Blob の読み込みAPIが利用可能です。スレッド上の読み込みはメインスレッドをブロックしないためです。 この節ではWorkers内で利用できる同期APIを定義します。Workerは非同期API（FileReader オブジェクト）および同期API（FileReaderSync オブジェクト）を利用できます。

6.5.1. FileReaderSync API

このインターフェイスは同期的に読み込みを行い、 File や Blob オブジェクトをメモリに読み込みます。

[Exposed=(DedicatedWorker,SharedWorker)]
interface FileReaderSync {
  constructor();
  // 同期的に文字列を返す

  ArrayBuffer readAsArrayBuffer(Blob blob);
  DOMString readAsBinaryString(Blob blob);
  DOMString readAsText(Blob blob, optional DOMString encoding);
  DOMString readAsDataURL(Blob blob);
};

6.5.1.1. コンストラクター

FileReaderSync() コンストラクターが呼び出されると、ユーザーエージェントは新しい FileReaderSync オブジェクトを返さなければなりません。

6.5.1.2. readAsText()

readAsText(blob, encoding) メソッドは呼び出されると、以下のステップを実行しなければなりません：

1. stream を blob に対して get stream で取得する。

2. reader を stream から reader取得 で取得する。

3. promise を stream と reader で 全バイトの読み出し結果とする。

4. promise がfulfilledまたはrejectedになるまで待つ。

5. promise が バイト列 bytes でfulfilledされた場合：

   1. bytes、Text、blobの type、encoding を パッケージデータ に渡した結果を返す。

6. promise の rejection理由をthrowする。

6.5.1.3. readAsDataURL() メソッド

readAsDataURL(blob) メソッドは呼び出されると、以下のステップを実行しなければなりません：

1. stream を blob に対して get stream で取得する。

2. reader を stream から reader取得 で取得する。

3. promise を stream と reader で 全バイトの読み出し結果とする。

4. promise がfulfilledまたはrejectedになるまで待つ。

5. promise が バイト列 bytes でfulfilledされた場合：

   1. bytes、DataURL、blobの type を パッケージデータ に渡した結果を返す。

6. promise の rejection理由をthrowする。

6.5.1.4. readAsArrayBuffer() メソッド

readAsArrayBuffer(blob) メソッドは呼び出されると、以下のステップを実行しなければなりません：

1. stream を blob に対して get stream で取得する。

2. reader を stream から reader取得 で取得する。

3. promise を stream と reader で 全バイトの読み出し結果とする。

4. promise がfulfilledまたはrejectedになるまで待つ。

5. promise が バイト列 bytes でfulfilledされた場合：

   1. bytes、ArrayBuffer、blobの type を パッケージデータ に渡した結果を返す。

6. promise の rejection理由をthrowする。

6.5.1.5. readAsBinaryString() メソッド

readAsBinaryString(blob) メソッドは呼び出されると、以下のステップを実行しなければなりません：

1. stream を blob に対して get stream で取得する。

2. reader を stream から reader取得 で取得する。

3. promise を stream と reader で 全バイトの読み出し結果とする。

4. promise がfulfilledまたはrejectedになるまで待つ。

5. promise が バイト列 bytes でfulfilledされた場合：

   1. bytes、BinaryString、blobの type を パッケージデータ に渡した結果を返す。

6. promise の rejection理由をthrowする。

注: readAsArrayBuffer() の利用が readAsBinaryString() より推奨されます。 readAsBinaryString() は後方互換のために提供されています。

7. エラーと例外

ファイル読み込みエラーは、基盤となるファイルシステムからファイルを読み込む際に発生する場合があります。 以下に示す潜在的エラー条件のリストは参考情報です。

• アクセスしようとしている File や Blob が、非同期読み込みメソッドまたは同期読み込みメソッドの呼び出し時に存在しない場合があります。 これは、参照の取得後に移動または削除されたため（例：他のアプリケーションによる並行変更）が考えられます。 NotFoundErrorを参照してください。

• File や Blob が読み込めない場合があります。 これは、File や Blob への参照取得後に発生するパーミッションの問題（例：他のアプリケーションによる並行ロック）が理由の場合があります。 また、スナップショット状態が変更された場合も含まれます。 NotReadableErrorを参照してください。

• ユーザーエージェントは、Webアプリケーションで使用するには一部ファイルが安全でないと判断する場合があります。 ファイルは、元の選択後にディスク上で変更される可能性があり、無効な読み取りとなる場合があります。 さらに、一部のファイルやディレクトリ構造は基盤ファイルシステムによって制限されている場合があり、 それらからの読み込みはセキュリティ違反とみなされる場合があります。 § 9 セキュリティとプライバシーの考慮事項および SecurityErrorを参照してください。

7.1. 例外のスローまたはエラーの返却

この節は規定事項です。

File や Blob の読み込み時にはエラー条件が発生する場合があります。

読み込み操作は、File や Blob の読み込み時のエラー条件によって終了する場合があります。 特定のエラー条件が get stream アルゴリズムの失敗を引き起こす場合、その条件は 失敗理由 と呼ばれます。失敗理由 には、NotFound、UnsafeFile、TooManyReads、SnapshotState、FileLock のいずれかがあります。

同期読み込みメソッドは、下記表に記載された型の例外をthrowします。これは特定の失敗理由によるエラーが発生した場合です。

非同期読み込みメソッドは、error 属性（FileReader オブジェクト）を使用し、 特定の失敗理由によるエラーが発生した場合は、下記表で最も適切な型の DOMException オブジェクトを返し、 それ以外の場合は null を返します。

8. BlobおよびMediaSource参照用のURL

この節では、Blob および MediaSource オブジェクトを参照するためのスキーム付きURLを定義します。

8.1. 概要

この節は参考情報です。

Blob（またはオブジェクト）URLは blob:http://example.com/550e8400-e29b-41d4-a716-446655440000 などのURLです。 これにより、Blob や MediaSource を URLのみ対応のAPI（例：img要素）と統合できます。Blob URLはローカル生成データのナビゲートやダウンロードのトリガーにも利用できます。

この目的のため URL インターフェイスに2つの静的メソッド createObjectURL(obj) と revokeObjectURL(url) が公開されています。 最初のメソッドは URL と Blob のマッピングを作成し、 2番目のメソッドはそのマッピングを破棄します。 マッピングが存在する間は Blob はガベージコレクトされませんので、 参照が不要になったら早めにURLを破棄する必要があります。 URLを生成したグローバルが消滅すると全てのURLも破棄されます。

8.2. モデル

各ユーザーエージェントは blob URLストア を保持しなければなりません。 blob URLストアは マップであり、 キーは 有効なURL文字列、 値は blob URLエントリです。

blob URLエントリは オブジェクト （型は Blob または MediaSource）と、 環境 （環境設定オブジェクト）で構成されます。

注: 仕様書は blobオブジェクト取得アルゴリズムを使って blob URLエントリ の オブジェクトにアクセスしなければなりません。

blob URLストアのキー（blob URLとも呼ばれる）は、 有効なURL文字列であり、 パースすると URLとなり、 スキームが "blob"、 空のホスト、 パスは1要素で、その要素も有効なURL文字列です。

8.3. blob URLのデリファレンスモデル

blob URLのパース・フェッチモデルに関する追加要件は [URL] および [Fetch] の現行標準に定義されています。

8.3.1. blob URLのオリジン

この節は参考情報です。

blob URLのオリジンは、URLがまだ失効されていない限り、そのURLを作成した環境のオリジンと常に同じです。これは [URL] 現行標準がURLのパース時に blob URLストアを参照し、そのエントリを使って 正しいオリジンを返すことで実現されています。

URLが失効されている場合でも、オリジンのシリアライズはblob URLを作成した環境のオリジンのシリアライズと同じままです。 ただし不透明なオリジンの場合は、オリジン自体が異なる場合もあります。しかしこの違いは観測できません。なぜなら失効されたblob URLはもはや解決・フェッチできないためです。

8.3.2. blob URLへのアクセス制限

blob URLは、ストレージキーが blob URLが作成された環境と一致する環境からのみフェッチ可能です。blob URLのナビゲーションにはこの制限はありません。

8.3.3. blob URLのライフタイム

この仕様は ドキュメントアンロード時のクリーンアップ手順を以下の手順で拡張します：

1. environment を Document の 関連設定オブジェクトとする。

2. store をユーザーエージェントの blob URLストアとする。

3. store から 値 の 環境 が environment と等しい全てのエントリを削除する。

Workerのアンロード時にも同様のフックが必要です。

8.4. blob URLの生成と破棄

Blob URLはURLオブジェクト上の静的メソッドで生成・破棄されます。 blob URLの破棄は blob URLと参照されるリソースの関連付けを解除し、 破棄後にデリファレンスされた場合、ユーザーエージェントはネットワークエラーが発生したかのように動作しなければなりません。 この節ではURL仕様への補足インターフェイスを記述し、blob URLの生成と破棄のためのメソッドを示します。

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partial interface URL {
  static DOMString createObjectURL((Blob or MediaSource) obj);
  static undefined revokeObjectURL(DOMString url);
};

myurl = window1.URL.createObjectURL(myblob);
window2.URL.revokeObjectURL(myurl);

8.4.1. blob URL生成と破棄の例

Blob URLは fetchでBlobオブジェクトを取得するための文字列であり、 documentが存続する限り URL.createObjectURL()で生成したURLは有効です。 § 8.3.3 blob URLのライフタイム参照。

この節ではblob URLの生成・破棄の使用例を説明します。

url = URL.createObjectURL(blob);
img1.src = url;
img2.src = url;

var blobURLref = URL.createObjectURL(file);
img1 = new Image();
img2 = new Image();

// 両方の代入は正常に動作します
img1.src = blobURLref;
img2.src = blobURLref;

// ... bodyロード後
// 両画像の読み込みが完了しているか確認
if(img1.complete && img2.complete) {
  // 以降の参照で例外が投げられるようにする
  URL.revokeObjectURL(blobURLref);
} else {
  msg("Images cannot be previewed!");
  // 文字列参照を破棄
  URL.revokeObjectURL(blobURLref);
}

上記例では1つのblob URLに複数回参照できます。 Web開発者は両方の画像オブジェクトのロード完了後にblob URL文字列を破棄します。 blob URLの利用回数に制限を設けないことで柔軟性は増しますが、 リークの可能性も高まるため、 対応するURL.revokeObjectURL()呼び出しを組み合わせるべきです。

9. セキュリティとプライバシーに関する考慮事項

この節は参考情報です。

本仕様は、ウェブコンテンツが基盤となるファイルシステムからファイルを読み込むことを許可し、 ファイルを一意の識別子でアクセスする手段も提供するため、いくつかのセキュリティ上の考慮事項が生じます。 本仕様では主なユーザー操作はHTMLフォームの<input type="file"/>要素 [HTML]を通じて行われることを前提とし、 FileReader オブジェクトで読み込まれる全ファイルは、ユーザーによって選択済みであるものとします。 重要なセキュリティ上の考慮事項には、悪意あるファイル選択攻撃（選択ループ）の防止、 システム重要ファイルへのアクセス防止、 選択後のディスク上ファイルの改変防止などが含まれます。

選択ループ防止

ファイル選択時、ユーザーが<input type="file"/>に関連付けられたファイルピッカーによって繰り返し選択を強いられる（ファイルピッカーが閉じられる前に選択を強制される「強制選択」ループ）場合、 ユーザーエージェントは、返されるFileList オブジェクトのサイズを0にすることでファイルアクセスを防止できます。

システム重要ファイル

（例：/usr/bin内のファイル、パスワードファイル、その他OSの実行ファイルなど） は一般的にウェブコンテンツへ公開すべきではなく、 blob URL経由でもアクセスすべきではありません。 ユーザーエージェントは同期読み込みメソッドでSecurityError 例外をthrowしたり、 非同期読み込みでSecurityError 例外を返すことがあります。

この節は暫定的なものであり、将来の草案でより多くのセキュリティ情報が補足される可能性があります。

10. 要件とユースケース

この節では、本APIの要件と、いくつかのユースケース例を示します。 このバージョンのAPIはすべてのユースケースを満たすものではなく、 今後のバージョンで追加対応する場合があります。

• ユーザーが権限を与えた後は、 ユーザーエージェントはローカルファイルからデータをプログラムで直接読み込み・解析できる機能を提供すべきです。

  歌詞ビューア。 ユーザーは自分のplistファイル内の楽曲から歌詞を読み込みたい。 ユーザーはplistファイルを選択する。 ファイルが開かれ、読み込まれ、解析された結果、ウェブアプリ内で並び替えや操作が可能なリストとして表示される。 ユーザーは楽曲を選択して歌詞を取得できる。 ファイル選択ダイアログを利用。

• データはローカルに保存可能であるべきで、後で利用できるようにすることで ウェブアプリのオフラインデータアクセスにも役立ちます。

  カレンダーアプリ。 ユーザーの会社にカレンダーがある。 ユーザーはローカルイベントを会社カレンダーに同期したい（個人情報漏洩なしで「予定あり」枠としてマーク）。 ユーザーはファイル選択ダイアログで選択。 text/calendarファイルがブラウザで解析され、 ユーザーは両ファイルを統合カレンダーとして表示できる。 ユーザーは統合後のカレンダーファイルをローカルに「名前を付けて保存」できる。 また、統合カレンダーをサーバカレンダーストアに非同期送信も可能。

• ユーザーエージェントはデータとファイル名を指定してローカルファイルをプログラムで保存できる機能を提供すべきです。

  注: 本仕様には明示的なダウンロードAPIはありませんが、HTML5仕様で対応済みです。 download 属性を付与した a 要素でダウンロードが開始され、 File の名前も指定できます。 本APIと download 属性付き a 要素の組み合わせでウェブアプリ内でファイル生成・ローカル保存が可能となります。

  表計算アプリ。 ユーザーがフォームで入力を行う。 フォームがCSV（カンマ区切り値）出力を生成し、ユーザーがスプレッドシートにインポート可能。 「保存...」で出力。 生成データはウェブベースの表計算アプリへ直接統合したり、非同期アップロードも可能。

• ユーザーエージェントは、ファイルからリモートサーバにデータを効率的に送信できるプログラムAPIを提供すべきです（従来のフォームアップロードより効率的）。

  動画・写真アップロードアプリ。 ユーザーは大きなファイルを選択しアップロード可能。 サーバに「チャンク転送」で送信できる。

• ユーザーエージェントは上記機能をスクリプトから利用できるAPIを公開すべきです。 ファイルシステムとのやりとりが発生した際は必ずUIで通知し、 ユーザーは取引のキャンセル・中断が可能。 ファイル選択時にも通知し、キャンセルできる。 これらAPIはユーザーの関与なしにサイレントに呼び出されることはありません。

謝辞

本仕様はSVGワーキンググループにより初期開発されました。Mark Baker氏、Anne van Kesteren氏のフィードバックに感謝します。

Robin Berjon氏、Jonas Sicking氏、Vsevolod Shmyroff氏による初期仕様編集に感謝します。

Olli Pettay氏、Nikunj Mehta氏、Garrett Smith氏、Aaron Boodman氏、Michael Nordman氏、Jian Li氏、Dmitry Titov氏、Ian Hickson氏、Darin Fisher氏、Sam Weinig氏、Adrian Bateman氏、Julian Reschke氏に特別な感謝を。

W3C WebApps WGおよびpublic-webapps@w3.orgリスト参加者にも感謝します。