ファイル 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;

  // slice Blob into byte-ranged chunks
  Blob slice(optional [Clamp] long long start,
            optional [Clamp] long long end,
            optional DOMString contentType);

  // read from the Blob.
  [NewObject] ReadableStream stream();
  [NewObject] Promise<USVString> text();
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] ReadableStream textStream();
  [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" の値を取ることができる列挙型である。 デフォルトでは、これは "transparent" に設定される。 "native" に設定されている場合、 blobParts 内の任意の 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() の呼び出しを通じて、Web アプリケーション自体によって設定できる。 これらの場合、この属性に関する追加の規範的条件は、それぞれ § 3.1 コンストラクター、 § 4.1 コンストラクター、 および § 3.3.1 slice() メソッドにある。 ユーザーエージェントは、type、すなわち Blob の型も決定でき、 特にそのバイト列がディスク上のファイルからのものである場合が該当する。 この場合、追加の規範的条件はファイル型ガイドラインにある。

注: 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 でラップ）を返す。

3.3.6. textStream() メソッド

textStream() メソッドの手順は次のとおりです:

1. stream を、get stream を this に対して呼び出した結果とする。

2. decoder を、this の 関連レルム内の新しい TextDecoderStream とする。

3. decoder を UTF-8 で設定する。

4. stream を decoder にpipe through した結果を返す。

注: これは readAsText() とは異なり、常に UTF-8 エンコーディングを使用する。

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 のメンバーに加えて、 1 つのメンバーを持つ：

• 省略可能な lastModified メンバーであり、 long long でなければならない。 このメンバーに関する規範的条件は、§ 4.1 コンストラクターに規定されている。

4.2. 属性

name, 型 DOMString, 読み取り専用

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

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

ファイルの最終更新日時。 取得時に、ユーザーエージェントがこの情報を利用可能にできる場合、 これはファイルが最後に更新された時刻を Unix エポックからのミリ秒数として設定した long long を返さなければならない。 最終更新日時が不明な場合、 この属性は現在の日付と時刻を Unix エポックからのミリ秒数を表す long long として返さなければならない。 これは Date.now() [ECMA-262] と同等である。 File オブジェクトがコンストラクターを使用して作成された場合、 この属性に関する追加の規範的条件は § 4.1 コンストラクターにある。

File インターフェイスは、FileList 型の属性を公開するオブジェクト上で利用可能である。 これらのオブジェクトは HTML の [HTML] に定義されている。 File インターフェイスは、Blob から継承し、変更不可能（immutable）であり、 したがって、read operation が開始された時点でメモリに読み込むことができるファイルデータを表す。 ユーザーエージェントは、読み取り時点で既に存在しないファイルに対する読み取りを errors として処理し、 Web Worker 上で 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 は、ユーザーエージェントによって File オブジェクトの FileList 内での位置を表す値として扱われなければならず、 0 は最初のファイルを表す。 サポートされるプロパティインデックスは、 0 から FileList オブジェクトによって表される File オブジェクトの数より 1 少ない数までの範囲の数である。 そのような File オブジェクトが存在しない場合、 サポートされるプロパティインデックスは存在しない。

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

6. データの読み込み

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

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

6.2. FileReader API

[Exposed=(Window,Worker)]
interface FileReader: EventTarget {
  constructor();
  // async read methods
  undefined readAsArrayBuffer(Blob blob);
  undefined readAsBinaryString(Blob blob);
  undefined readAsText(Blob blob, optional DOMString encoding);
  undefined readAsDataURL(Blob blob);

  undefined abort();

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

  readonly attribute unsigned short readyState;

  // File or Blob data
  readonly attribute (DOMString or ArrayBuffer)? result;

  readonly attribute DOMException? error;

  // event handler content attributes
  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. 処理中の read メソッド のアルゴリズムを 終了する。

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 イベントは一対一で対応しているわけではない。

   この例は「読み取りの連鎖」を示している： 「最初の」読み取りが処理を継続している間に、イベントハンドラー内から別の読み取りを開始する。

   // 次のようなコードでは...
   reader.readAsText(file);
   reader.onload = function(){reader.readAsText(alternateFile);}
   
   .....
   
   //... 最初の読み取りについて loadend イベントは発火してはならない
   
   reader.readAsText(file);
   reader.abort();
   reader.onabort = function(){reader.readAsText(updatedFile);}
   
   //... 最初の読み取りについて loadend イベントは発火してはならない
   

2. blob が完全にメモリへ読み込まれたとき、1 つの progress イベントが発火する。

3. loadstart より前に progress イベントが発火することはない。

4. abort、load、 および error のいずれかが発火した後に progress イベントが発火することはない。 特定の読み取りについて、abort、load、 および error のうち発火するのは最大でも 1 つである。

5. loadend の後に abort、load、 または error イベントが発火することはない。

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

Web Workers は、同期的な File や Blob 読み取り API の使用を可能にする。これは、スレッド上での読み取りがメインスレッドをブロックしないためである。 この節では、Workers [Workers] 内で使用できる同期 API を定義する。 Workers は、非同期 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リスト参加者にも感謝します。