FileSystemDirectoryEntry: getFile() メソッド
FileSystemDirectoryEntry
インターフェイスのメソッド getFile()
は、呼び出されたディレクトリーをルートとするディレクトリーサブツリーのどこかに格納されているファイルに対応する FileSystemFileEntry
オブジェクトを返します。
構文
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
省略可-
もし
true
でcreate
オプションもtrue
であれば、呼び出す前にファイルが存在してはいけません。 その代わり、呼び出し時に新たに作成することが可能でなければなりません。 既定値はfalse
です。この引数はcreate
がfalse
の場合には無視されます。
下記の表は、対象とするファイルのパスが既に存在するかどうかに応じて、これらのフラグを可能な限り組み合わせた場合の結果を記述したものです。
create オプション |
exclusive オプション |
パスの条件 | 結果 |
---|---|---|---|
false |
無視 | パスが存在してファイルである | successCallback が FileSystemFileEntry で呼び出される。 |
false |
無視 | パスが存在しているがディレクトリーである | errorCallback が適切なエラーコードで呼び出される(コールバックが提供されていた場合)。 |
true |
false |
パスが存在する | 既存のファイルが除去され、新しいファイルに置き換わる。次に successCallback が FileSystemFileEntry で呼び出される。 |
true |
false |
パスが存在しない | ファイルが作成され、FileSystemFileEntry が successCallback に渡される。 |
true |
true |
パスが存在する | errorCallback は FileError.PATH_EXISTS_ERR のような適切なエラーで呼び出されます。 |
true |
true |
パスが存在しない | ファイルが作成され、FileSystemFileEntry が successCallback に渡される。 |
返値
なし (undefined
)。
例外
NotFoundError
DOMException
-
create
オプションが指定されず(またはfalse
を指定します)、ファイルが存在しない場合に発生します。 SecurityError
DOMException
-
ファイルへのアクセスリクエストがセキュリティ上の理由で拒否された場合に発生します。
TypeMismatchError
DOMException
-
指定したパスがファイルでない場合に発生します。おそらくファイルですが、パイプのような対応していないファイル記述子かもしれません。これはユーザーエージェントにある程度依存します。
例
この例では、指定した言語のユーザー辞書を含む JSON ファイルをユーザーのアプリデータディレクトリー内に格納し、その辞書を読み込むことを仕事とする関数を表示しています。
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