FileSystemDirectoryEntry: getFile() メソッド

FileSystemDirectoryEntry インターフェイスのメソッド getFile() は、呼び出されたディレクトリーをルートとするディレクトリーサブツリーのどこかに格納されているファイルに対応する FileSystemFileEntry オブジェクトを返します。

構文

js
getFile()
getFile(path)
getFile(path, options)
getFile(path, options, successCallback)
getFile(path, options, successCallback, errorCallback)

引数

path 省略可

メソッドが呼び出されるディレクトリーにおいて、どのファイルの項目を返すかを記述する相対パスを指定する文字列。

options 省略可

項目がない場合に作成するかどうか、ファイルがすでに存在する場合にエラーとするかどうかを指定するオブジェクトです。これらのオプションは、現在のところウェブのコンテキストでは有益ではありません。 詳しくは options 引数の節を参照してください。

successCallback 省略可

FileSystemFileEntry が作成されたら呼び出されるメソッド。 このメソッドは単一の引数、つまり問題のファイルを表す FileSystemFileEntry オブジェクトを受け取ります。

errorCallback 省略可

エラーが発生した場合に呼び出されるメソッドです。唯一の引数として、発生したエラーを説明する DOMException オブジェクトを受け取ります。

options 引数

options 引数オブジェクトは、以下の引数を受け入れます。

create 省略可

このプロパティが true で、リクエストされたファイルが存在しない場合、ユーザーエージェントはそれを作成する必要があります。 既定値は false です。 親ディレクトリーはすでに存在している必要があります。

exclusive 省略可

もし truecreate オプションも true であれば、呼び出す前にファイルが存在してはいけません。 その代わり、呼び出し時に新たに作成することが可能でなければなりません。 既定値は false です。この引数は createfalse の場合には無視されます。

下記の表は、対象とするファイルのパスが既に存在するかどうかに応じて、これらのフラグを可能な限り組み合わせた場合の結果を記述したものです。

create オプション exclusive オプション パスの条件 結果
false 無視 パスが存在してファイルである successCallbackFileSystemFileEntry で呼び出される。
false 無視 パスが存在しているがディレクトリーである errorCallback が適切なエラーコードで呼び出される(コールバックが提供されていた場合)。
true false パスが存在する 既存のファイルが除去され、新しいファイルに置き換わる。次に successCallbackFileSystemFileEntry で呼び出される。
true false パスが存在しない ファイルが作成され、FileSystemFileEntrysuccessCallback に渡される。
true true パスが存在する errorCallbackFileError.PATH_EXISTS_ERR のような適切なエラーで呼び出されます。
true true パスが存在しない ファイルが作成され、FileSystemFileEntrysuccessCallback に渡される。

返値

なし (undefined)。

例外

NotFoundError DOMException

create オプションが指定されず(または false を指定します)、ファイルが存在しない場合に発生します。

SecurityError DOMException

ファイルへのアクセスリクエストがセキュリティ上の理由で拒否された場合に発生します。

TypeMismatchError DOMException

指定したパスがファイルでない場合に発生します。おそらくファイルですが、パイプのような対応していないファイル記述子かもしれません。これはユーザーエージェントにある程度依存します。

この例では、指定した言語のユーザー辞書を含む JSON ファイルをユーザーのアプリデータディレクトリー内に格納し、その辞書を読み込むことを仕事とする関数を表示しています。

js
let dictionary = null;

function loadDictionaryForLanguage(appDataDirEntry, lang) {
  dictionary = null;

  appDataDirEntry.getDirectory("Dictionaries", {}, (dirEntry) => {
    dirEntry.getFile(`${lang}-dict.json`, {}, (fileEntry) => {
      fileEntry.file((dictFile) => {
        let reader = new FileReader();

        reader.addEventListener("loadend", () => {
          dictionary = JSON.parse(reader.result);
        });

        reader.readAsText(dictFile);
      });
    });
  });
}

loadDictionaryForLanguage() 関数は、まず getDirectory() を使用して、指定したアプリのデータディレクトリー内にある "Dictionaries" という名前のサブフォルダーを表す FileSystemDirectoryEntry オブジェクトを取得します。この成功コールバックは、結果のディレクトリー項目オブジェクトを受け取り、getFile() を呼び出して、辞書ファイルを表す FileSystemFileEntry オブジェクトを取得します。読み込みが成功すると (loadend イベントが発生することで示されます)、読み込まれたテキストは JSON.parse() に渡され、JavaScript オブジェクトに再構成されます。

仕様書

Specification
File and Directory Entries API
# dom-filesystemdirectoryentry-getfile

ブラウザーの互換性

BCD tables only load in the browser

関連情報