Fileプラグインを使う
では、早速プラグインを導入し、使い方を説明します。
インストール
インストールするプラグインは、「cordova-plugin-file」です。インストールはリスト1のように行います。
$cordova plugin add cordova-plugin-file
プラグインの使い方
HTML5のFileSystem APIと同じであっても、実装はプラグインで提供されている機能ですので、devicereadyイベントが発火された以降でしか利用できない点は忘れないようにして下さい。また、AndroidもしくはiOSで使えるディレクトリはcordova.fileオブジェクトの中にプロパティとして設定されますので、リスト2のように利用可能です。アプリケーションからは、これらのプロパティで取得できるパス配下のファイルだけを扱えます。
console.log(cordova.file.applicationDirectory);
利用できるプロパティは、AndroidとiOSで多少異なりますが、表1はAndroidとiOSのいずれのOSでも利用できるプロパティです。
| プロパティ | 説明 |
|---|---|
| applicationDirectory | アプリケーションがインストールされたディレクトリ。読込専用のディレクトリ。 |
| applicationStorageDirectory | アプリケーションが利用するための基底となる読み書き可能なディレクトリ。直接利用するのではなく、その配下となるディレクトリを主に利用する。 |
| dataDirectory | アプリケーションがファイルを永続的にデータを保存する為のディレクトリ。Androidの場合には「データを消去」で削除可能。 |
| cacheDirectory | アプリケーションががキャッシュとしてデータを保存する為のディレクトリ。Androidの場合には「キャッシュを消去」で削除可能 |
このディレクトリ以外に、iOSであればiCloudに保存するためのディレクトリや、AndroidであればSDカードに保存するためのディレクトリなど、OS特有のディレクトリがあります。
ハイブリッドアプリとして共通の処理の実装にする場合には、上記ディレクトリを覚えておけば問題ありません。ただし、OS特有の機能などを使いたい場合には、File System Layoutsを参照してください。
図1は、サンプルアプリを実行し、各プロパティを表示した結果です。ご自分のスマートフォンではどのようなパスになるのかを知りたい場合には、サンプルアプリを実行してみてください。
Fileを操作する流れ
JavaScriptでファイル操作をするには、提供されているメソッドが非同期型ということもあり、サーバサイドなどでファイル操作をするよりも手順が多少複雑になっています。少々、わかりにくいので全体の流れを図2に示します。
ファイル情報を取得するには、リスト3に示す2つのメソッドがあります。これらのメソッドがファイルを扱う場合に最初に実行するメソッドです。
window.requestFileSystem(type,size,successCallback,[errorCallback]); window.resolveLocalFileSystemURL(URL, successCallback, [errorCallback] );
これらのメソッドのsuccessCallbackの結果から取得できるFile情報(Entry)オブジェクトを利用し、ファイルの操作を行うのが共通の流れになります。
requestFileSystemメソッドは、先ほど、紹介したcordova.fileで取得できるパスを指定するのではなく、恒久的な領域、もしくは一時的な領域のみのいずれかのみが指定可能で、表2に示す引数が指定できます。
| プロパティ | 型 | 説明 |
|---|---|---|
| type | Number | window.PERSISTENT(恒久的な保存領域)もしくは、window.TEMPORARY(一時的なファイル領域)のいずれかが指定可能 |
| size | Number | 指定した容量が空いているかをチェック。0を指定した場合にはチェックはしない |
| successCallback | Function | 成功した場合に呼ばれるコールバック関数 |
| errorCallback | Function | エラー時に呼ばれるコールバック関数 |
続いて、resolveLocalFileSystemURIメソッドの引数を表3に示します。
こちらのメソッドではpathを指定しますが、cordova.fileで取得できるパスもしくはその配下を指定します。
| プロパティ | 型 | 説明 |
|---|---|---|
| path | DOMString | 取得するファイル、もしくはディレクトリのパス |
| successCallback | Function | 成功した場合に呼ばれるコールバック関数 |
| errorCallback | Function | エラー時に呼ばれるコールバック関数 |
どちらのメソッドを使えばよいか迷った際には、resolveLocalFileSystemURIメソッドを使えばよいでしょう。
現在のスマホの容量を考慮すれば、事前に容量のチェックを行う必要があるような大きなファイルを扱う事はまれだと思います。
resolveLocalFileSystemURIでは実際に保存する先のパスを指定できるのでより細かい操作が行えます。本サンプルでもこちらのメソッドを利用して実際の使い方を紹介します
ファイル、ディレクトリを操作するEntryオブジェクト
続いて、ファイル・ディレクトリ操作をするためのEntryオブジェクトの紹介します。先ほどのメソッドを利用して取得したパスがファイルなのか、ディレクトリなのかによってFileEntryもしくはDirectoryEntryのようにオブジェクトの実体は変わります。
表4はEntryのプロパティ一覧で、FileEntryとDirectoryEntryで共通となります。パスやそのパスがファイルなのか、ディレクトリなのかなどのチェックできるようなプロパティが管理されています。
| プロパティ | 型 | 説明 |
|---|---|---|
| isFile | Boolean | ファイルかどうか |
| isDirectory | Boolean | ディレクトリかどうか |
| name | DOMString | ファイル名、もしくはディレクトリ名(パスは含まない) |
| fullPath | DOMString | すべてのパス |
| filesystem | FileSystem | このEntryを読んだ時のFileSystemオブジェクト |
続いてメソッドを紹介します。実際に扱うパスがファイル、もしくはディレクトリによって行いたい事も変わりますので、メソッドもそれぞれ別に用意されています。
取得したパスがディレクトリの場合（DirectoryEntryオブジェクト）のメソッドは表5のようになります。
| メソッド | 説明 |
|---|---|
| createReader() | ファイル一覧を取得する為のReaderオブジェクトを作成する |
| getFile(path,options,successCallback, errorCallback ) | 指定したファイルのEntryを取得する |
| getDirectory(path,options,successCallback, errorCallback ) | 指定したディレクトリのEntryを取得する |
| moveTo(parent,newName,successCallback, errorCallback ) | ディレクトリの移動 |
| copyTo(parent,newName,successCallback, errorCallback ) | ディレクトリのコピー（配下のディレクトリ、ファイルも含む) |
| remove(successCallback, errorCallback ) | ディレクトリの削除 |
| removeRecursively(successCallback, errorCallback ) | 配下のEntryを再帰的に削除します |
取得したパスがファイルの場合（FileEntryオブジェクト）のメソッドは表6のようになります。
| メソッド | 説明 |
|---|---|
| createWriter(successCallback, errorCallback ) | ファイルにデータを書き込む為のWriterオブジェクトを作成する |
| file(successCallback, errorCallback ) | Fileオブジェクトを取得する。Fileオブジェクトを使って内容を読みこむ事ができる |
| moveTo(parent,newName,successCallback, errorCallback ) | ファイルの移動 |
| copyTo(parent,newName,successCallback, errorCallback ) | ファイルのコピー |
| remove(successCallback, errorCallback ) | ファイルの削除 |
ここで紹介したプロパティやメソッドでおおよその目的は実現できますが、紹介していないメソッドもありますので、もっと詳しく知りたい方は、HTML5関連の書籍や、MDNのようなサイトを参照してみると良いでしょう。ただし、先ほども説明したとおり通常のWebアプリなどでは利用できないことからドキュメントなども日本語になっていないなど、あまり情報は整備されているとは言えず、他の情報も含めて探してみると良いでしょう。
