cordova.file
オブジェクトを定義します。 グローバルスコープでは、deviceready
イベントの発火後まで使用できません。window.resolveLocalFileSystemURL()
を使用すれば、次のような DirectoryEntry
に、この URL を変換することもできます。cordova.file.applicationDirectory
- アプリのインストール先となる、読み取り専用のディレクトリーです。 ( iOS、Android、BlackBerry 10、OSX、windows )cordova.file.applicationStorageDirectory
- アプリのサンドボックス ( sandbox ) のルートディレクトリーです。iOS と Windows では、このディレクトリーは読み取り専用です ( ただし、iOS の /Documents
、Windows の /localState
など、特定のサブディレクトリーに関しては、読み取りと書き込みができます )。このディレクトリーに格納されているすべてのデータは、対象のアプリのみが利用できます。 ( iOS、Android、BlackBerry 10、OSX )cordova.file.dataDirectory
- アプリのサンドボックス ( sandbox ) 内の永続的およびプライベートなデータストレージです。内蔵のメモリーが使用されます。Android の場合、外部のメモリーが必要なときは、.externalDataDirectory
を使用します。また、iOS の場合、このディレクトリーは、iCloud 間とは同期されません ( .syncedDataDirectory
を使用します )。 ( iOS、Android、BlackBerry 10、windows )cordova.file.cacheDirectory
- キャッシュしたデータファイルまたは他のファイル ( アプリ側で再作成可能な、なんらかのファイル ) 用のディレクトリーです。端末側のストレージが不足する場合には、OS 側が、これらのファイルを削除します。ファイルの削除は、本来であれば、アプリ側で制御すべき処理です。 ( iOS、Android、BlackBerry 10、OSX、windows )cordova.file.externalApplicationStorageDirectory
- アプリが使用する、外部ストレージ上の領域 ( 親のディレクトリー ) です。 ( Android )cordova.file.externalDataDirectory
- 外部ストレージ上の領域内で、アプリが使用するデータファイルを置く領域 ( 子のディレクトリー ) です。 ( Android )cordova.file.externalCacheDirectory
- 外部ストレージ上の領域内で、アプリがキャッシュに使用する領域 ( 子のディレクトリー ) です。 ( Android )cordova.file.externalRootDirectory
- 外部ストレージ ( SD カード ) のルートです。 ( Android、BlackBerry 10 )cordova.file.tempDirectory
- Temp ディレクトリーです。OS 側がコンテンツを自由に削除できますが、このような挙動に頼るのではなく、このディレクトリーの処理は、アプリ側で常に行うべきです。 ( iOS、OSX、windows )cordova.file.syncedDataDirectory
- 同期対象である、アプリのファイルを格納します ( 例 : iCloud 間 )。 ( iOS、windows )cordova.file.documentsDirectory
- 対象のアプリだけが使用する、プライベートなファイルです。ただし、他のアプリ間ともなんらかの関係があります ( 例 : OFFICE ファイルなど )。OSX では、ユーザーの ~/Documents
ディレクトリーとなります。 ( iOS、OSX )cordova.file.sharedDirectory
- すべてのアプリ間で共有できる、グローバルなファイルを置けます。 ( BlackBerry 10 )cordova.file.*
プロパティと端末内の物理パスの関係 ( マップ方法 ) を理解しておくことは有意義です。/var/mobile/Applicati ons/<UUID>/
appname.app/
www/
Documents/
NoCloud/
Cloud/
Caches/
tmp/
file:///android_asset/
/data/data/<app-id>/
cache
files
Documents
<sdcard>/
Android/data/<app-id>/
cache
files
cordova.file.external\*
プロパティは null
になります。/data/data/<packageId>
下に、データを保存してました。この場合、アプリ間ではデータの処理は個別化されましたが、ユーザー間ではデータの共有ができました。config.xml
ファイルの preference 設定を使用して、内部 ( Internal ) の保存場所を使用するか、または、以前の設定 ( Compatibility ) をそのまま使用して、ファイルを保存するか選択することができます。この設定を行うには、次の記述のいずれかを、config.xml
ファイルに追加します。Internal
( 内部 ) を使用します。なお、preference タグが存在する場合でも、上記の値のいずれかが設定されていなければ、アプリは起動しません。Internal
の設定を推奨します。src/android/build-extras.gradle
を追加で置けば、この処理時間を短縮できます ( Android 向け Cordova の 4.0.0 以上が必要 )。cordova.file.applicationStorageDirectory
と cordova.file.externalApplicationStorageDirectory
への書き込みに関しては、デフォルト でパーミッションがアプリ側に付与されているため、プラグイン側ではユーザー側に許可を求めませんが、外部のストレージがマウントされていないときだけ、通知の意味も込めて、ユーザー側の許可を求めます。また、同様に、なんらかの理由で外部のストレージがマウントされていない場合にも、cordova.file.externalApplicationStorageDirectory
に書き込みを行ってよいか、プラグイン側からユーザー側に確認します。cordova.file.applicationStorageDirectory
は、読み取り専用です。このルートディレクトリーへファイルを保存しようとした場合、失敗します。よって、iOS がサポートしている他の cordova.file.*
プロパティを使用します ( applicationDirectory
と applicationStorageDirectory
のみ、読み取り専用です )。FileReader.readAsText(blob, encoding)
encoding
パラメーターは使用できません。UTF-8 形式のエンコーディングが常に使用されます。config.xml
ファイルの preference 設定を使用して、Documents ディレクトリーまたは Library ディレクトリーのいずれかに、ファイルを保存するか選択できます。この設定を行う場合、次の記述のいずれかを、config.xml
ファイルに追加します。Compatibility
を使用します。なお、preference タグが存在する場合でも、上記の値のいずれかが設定されていなければ、アプリは起動しません。Compatibility
に設定します。Library
に場所を変更してしまうと、アプリをアップグレードしたときに、以前保存したファイルに、アクセスできなくなる場合があります。Library
の設定を推奨します。FileEntry
と DirectoryEntry
の構造に修正を加えました。Entry
オブジェクトの fullPath
プロパティ内に、「 端末固有のファイル保存場所への絶対パス ( device-absolute-file-location ) 」 を保存していました。典型的なパスは、次のようになっていました。Entry
オブジェクトの toURL()
メソッドを使用しても取得できました。fullPath
属性には置かれます。よって、上記の 2 つのパスは、FileEntry
オブジェクトの fullPath
では、次のようになっています。Entry
オブジェクトの fullPath
プロパティを使用して、これらの絶対パスを取得していた場合には、entry.toURL()
を使用するように、コードを更新してください。resolveLocalFileSystemURL()
メソッドに、「 端末固有の絶対パス ( device-absolute-paths ) 」 を渡せば、それに対応した Entry
オブジェクトが返ってきます ( ただし、TEMPORARY
または PERSISTENT
ファイルシステムに、ファイルが存在していることが前提です )。entry.fullPath
を entry.toURL()
に置き換えれば、端末上のファイルを支障なく操作できるはずです。toURL()
の戻り値は、可能であれば、file:// 形式の絶対 URL を返すように仕様が変わりました ( CB-6394 を参照のこと )。 cdvfile: 形式の URL を取得したい場合には、現在、toInternalURL()
を使用できます。このメソッドでは、次の形式の ファイルシステム URL ( FileSystem URL ) を返します。cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file
」 形式のファイルパスを使用できます。この形式は、プラットフォームには依存せず、多くのプラットフォームでサポートされています。また、基本 Cordova プラグイン ( Core Cordova プラグイン ) でも、この cdvfile 形式のパスがサポートされています。たとえば、ファイル転送プラグイン
( File Transfer プラグイン ) を使用して、mp3 ファイルを、cdvfile 形式で指定された場所へダウンロードすることができます。また、メディア操作プラグイン
( Media プラグイン ) を使用すれば、そのファイルを再生できます。src
に cdvfile
を使用する場合、取得した fileEntry の toURL()
メソッドを使用すれば、cdvfile
のパスをネイティブパス ( native path ) に変換することができます。fileEntry は、resolveLocalFileSystemURL
を使用して取得できます。下に例を示しています。また、 cdvfile://
のパスをDOM内で直接使うこともできます。使用例です。Content-Security-Policy
の meta タグに、cdvfile:
スキームを追加します。<access origin="cdvfile://*" />
を config.xml
に追加します。1
NOT_FOUND_ERR
2
SECURITY_ERR
3
ABORT_ERR
4
NOT_READABLE_ERR
5
ENCODING_ERR
6
NO_MODIFICATION_ALLOWED_ERR
7
INVALID_STATE_ERR
8
SYNTAX_ERR
9
INVALID_MODIFICATION_ERR
10
QUOTA_EXCEEDED_ERR
11
TYPE_MISMATCH_ERR
12
PATH_EXISTS_ERR
config.xml
内のタグを使用して、インストール対象のファイルシステムを指定できます。デフォルトでは、すべてのファイルシステムのルートディレクトリーを利用できます。files
: アプリが使用する、ファイルストレージ用のディレクトリーです( 内部 )。files-external
: アプリが使用する、ファイルストレージ用のディレクトリーです (外部)。sdcard
: グローバルに使用する、外部のファイルストレージ用のディレクトリーですandroid.permission.WRITE_EXTERNAL_STORAGE
のパーミッション ( 許可 ) が必要です。cache
: アプリが使用する、キャッシュ用のディレクトリーです ( 内部)。cache-external
: アプリが使用する、キャッシュ用のディレクトリーです( 外部 )。assets
: アプリのバンドル(読み取り専用)root
: 端末のすべてのファイルシステムlibrary
: アプリの Library ディレクトリーです。documents
: アプリの Documents ディレクトリーです。cache
: アプリの Cache ディレクトリーです。bundle
: bundle container です (ディスク上のアプリ本体の格納先、読み取り専用 )。root
: 端末のすべてのファイルシステムlibrary-nosync
と documents-nosync
の 2 つのファイルシステムも追加して使用できます。これらのファイルシステムは、それぞれ、 /Library
と /Documents
ファイルシステム下に置かれますが、同期の対象外となるディレクトリーです。requestFileSystem
を使用すれば、ファイルシステムへアクセスすることができます。また、requestFileSystem
の実行時には、PERSISTENT または TEMPORARY のいずれかを指定できます。PERSISTENT にストレージを指定した場合、ユーザーの許可がない限り、ストレージの削除はできません。requestFileSystem
を使用してファイルシステムへアクセスした場合、サンドボックス化されたファイルシステムへのアクセスのみ許可され ( サンドボックス化した場合、対象のアプリのみ、ストレージにアクセス可能 )、端末上の他のファイルシステムへのアクセスはできません。サンドボックス化されたストレージ以外へアクセスする場合には、window.resolveLocalFileSystemURL
などのメソッドを使用します ( 参考として、下の 「 ファイルへの追記 」 を参照のこと )。fs.root
を使用します。また、fs.root
は、ファイルの作成/取得時にも使用できます ( getFile
を実行 )。ここでは、fs.root
は、DirectoryEntry オブジェクトであり、同時に、サンドボックス化されたファイルシステム内に作成された、永続的なストレージへのリファレンスとなります。getFile
の成功時のコールバックには、FileEntry オブジェクトが渡されます。FileEntry オブジェクトを使用して、ファイルへの書き込み・ファイルの読み込みを行います。getFile
を実行して、ファイルの作成/取得を行えます。永続的なストレージと同様、このメソッドを使用して、FileEntry オブジェクトの作成/取得を行えます。作成/取得後は、ファイルの読み込み・ファイルへの書き込みを行えます。createWriter
を実行して、ファイルへの書き込みを行います。このメソッドの成功時のコールバックに、FileWriter オブジェクトが渡されるので、FileWriter の write
メソッドを実行して、ファイルへの書き込みを行います。readAsText
などのメソッドを使用できます。読み込み処理の完了後、this.result
には、処理結果が保存されています。resolveLocalFileSystemURL
を使用できます。詳細は、上記の 「 ファイルの保存場所 」 をご確認ください。多くの場合、ストレージの場所はプラットフォーム毎に異なります。また、resolveLocalFileSystemURL
へ渡す File URL には、*cdvfile プロトコル* 形式も使用できます。createFile
関数に関しても、先ほど解説した内容と異なる点はありません ( 「 一時的に使用するファイルの作成 」 を参照のこと )。createFile
を実行し、次に、writeFile
を実行します。writeFile
では、追記処理であることを指定します。seek
メソッドを呼び出し、追記位置を指定します。また、ここでは、ファイルが存在するかも確認しています。seek の処理完了後、FileWriter の write メソッドを実行します。requestFileSystem
を使用して、ファイルシステム ( FileSystem ) へのリファレンスを取得します。以前と同じように、window.TEMPORARY を指定し、メソッドを実行します。実行後、返ってきた FileSystem オブジェクト ( fs ) には、サンドボックス化されたファイルシステム内のキャッシュへの情報が格納されています。次に、fs.root
を使用して、必要な DirectoryEntry オブジェクトを取得します。http://cordova.apache.org
を設定する必要があります ( index.html
内 )。DirectoryEntry
オブジェクトは、キャッシュ先にすでに紐づけされています。Blob
オブジェクト ( dataObj
) を渡し、新規のファイル上に保存します。FileReader.readAsArrayBuffer
を使用して、データを読み込みます。window.URL.createObjectURL
を使用します。toURL
メソッドを使用できます。