File
FileReader
とFileWriter
オブジェクトはファイルシステムへの読み書き手段を提供します。
オブジェクト
FileReader
FileReader はファイルの読み込みを行うオブジェクトです。
プロパティ
- readyState: 右の3種類の状態のいずれかを表します (EMPTY、LOADING、DONE)
- result: 読み込まれたファイルのコンテンツを表します (DOMString)
- error: エラー情報を表します (FileError)
- onloadstart: 読み込み開始時に呼ばれる関数を表します (Function)
- onprogress: 読み込み中に呼ばれ、進捗状況を報告する関数を表します (progess.loaded/progress.total) (Function) -現在サポートされていません
- onload: 読み込みが成功したときに呼ばれる関数を表します (Function)
- onabort: abort() メソッドを実行したときなど、読み込みが強制終了したときに呼ばれる関数を表します (Function)
- onerror: 読み込みが失敗したときに呼ばれる関数を表します (Function)
- onloadend: 成功、失敗にかかわらずリクエストが完了した際に呼ばれる関数を表します (Function)
メソッド
- abort: 読み込みを強制終了します
- readAsDataURL: ファイルを読み込み、データをBase64でエンコードされたデータURLで返します
- readAsText: テキストファイルを読み込みます
詳細
FileReader
オブジェクトはデバイスのファイルシステムからファイルを読み込みます。
ファイルはテキストもしくはBase64でエンコードされた文字列として読み込まれます。
また、イベントを受け取るための独自のイベントリスナを登録することもできます。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
データURLとして読み込む場合
パラメータ:
- fileName - 読み込むファイルのフルパスを表します
使用例
var win = function(evt) {
console.log(evt.target.result);
};
var fail = function(evt) {
console.log(evt.target.error.code);
};
var paths = navigator.fileMgr.getRootPaths();
var reader = new FileReader();
reader.onload = win;
reader.onerror= fail;
reader.readAsDataURL(paths[0] + "readme.txt");
テキストとして読み込む場合
パラメータ:
- fileName - 読み込むファイルのフルパスを表します
- encoding - ファイルのコンテンツのエンコードを表します (デフォルト: UTF-8)
使用例
var win = function(evt) {
console.log(evt.target.result);
};
var fail = function(evt) {
console.log(evt.target.error.code);
};
var paths = navigator.fileMgr.getRootPaths();
var reader = new FileReader();
reader.onload = win;
reader.onerror= fail;
reader.readAsText(paths[0] + "readme.txt");
読み込みを中断する例
var aborted = function(evt) {
console.log(evt.target.error.code);
};
var paths = navigator.fileMgr.getRootPaths();
var reader = new FileReader();
reader.onabort = aborted;
reader.readAsText(paths[0] + "readme.txt");
reader.abort();
詳細な使用例
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>連絡先の使用例</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// PhoneGapの読み込みを待機
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap準備完了
//
function onDeviceReady() {
var paths = navigator.fileMgr.getRootPaths();
var reader = new FileReader();
reader.onload = win;
reader.onerror= fail;
reader.readAsText(paths[0] + "readme.txt");
}
function win(evt) {
console.log(evt.target.result);
}
function fail(evt) {
console.log(evt.target.error.code);
}
</script>
</head>
<body onload="onLoad()">
<h1>サンプル</h1>
<p>ファイルを読み込みます。</p>
</body>
</html>
iOS に関する注意点
- encoding オプションは現在サポートされておらず、常にUTF-8エンコーディングが使われます。
- readAsDataUrl() はiOSではサポートされおりません。
FileWriter
FileWriterオブジェクトはファイルへの書き込みに使用します。
プロパティ
- readyState: 右の3種類の状態のいずれかを表します (INIT、WRITING、DONE)
- fileName: 書き込みの対象となるファイル名を表します (DOMString)
- length: 書き込みの対象となるファイルの長さを表します (long)
- position: ファイルポインタの現在の位置を表します (long)
- error: エラー情報を表します (FileError)
- onwritestart: 書き込み開始時に呼ばれる関数を表します (Function)
- onprogress: ファイル書き込み中に呼ばれ、進捗状況を報告する関数を表します (Function) -現在サポートされていません
- onwrite: リクエストが成功したときに呼ばれる関数を表します (Function)
- onabort: abort() メソッドを実行したときなど、書き込みが強制終了したときに呼ばれる関数を表します (Function)
- onerror: 書き込みが失敗したときに呼ばれる関数を表します (Function)
- onwriteend: 成功、失敗にかかわらずリクエストが完了した際に呼ばれる関数を表します (Function)
メソッド
- abort: 書き込みを中断します
- seek: ファイルポインタを指定したバイトまで移動します
- truncate: ファイルを指定した長さに切り詰めます
- write: ファイルにデータを書き込みます
詳細
FileWriter
オブジェクトはデバイスのファイルシステムに書き込む際に使用します。
また、イベントを受け取るための独自のイベントリスナを登録することもできます。
FileWriter
はひとつのファイルに対して使用され、複数回書き込みを行うこともできます。
FileWriter
が書き込み位置を管理することで、ユーザーは部分的に書き込むことができます。
FileWrite
はファイルポインタの位置とlength属性を指定することができるので、ファイルのどの位置からでも書き込みを行うことができます。
デフォルトではファイルの開始位置にポインタがセットされ、既存のデータを上書きしながら書き込みが行われます。
書き込みをファイルの最終から始める場合は FileWriter
コンストラクタにtrueを指定してください。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
Seek の例
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt");
// ファイルポインタをEOFに移動
writer.seek(writer.length);
Truncate の例
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt");
writer.truncate(10);
Write の例
var writeSuccess = function(evt) {
console.log("書き込み成功");
};
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt");
writer.onwrite = writeSuccess;
writer.write("サンプルテキスト");
Append の例
var writeSuccess = function(evt) {
console.log("書き込み成功");
};
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt", true);
writer.onwrite = writeSuccess;
writer.write("サンプルテキスト");
Abort の例
var aborted = function(evt) {
console.log(evt.target.error);
};
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt");
writer.onabort = aborted;
writer.write("サンプルテキスト");
writer.abort();
詳細な例
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>連絡先の使用例</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// PhoneGapの読み込みの待機
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap準備完了
//
function onDeviceReady() {
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt");
writer.onwrite = writeSuccess;
writer.write("サンプルテキスト");
// ファイル名は'サンプルテキスト'に変更されました。
}
function writeSuccess() {
console.log("書き込み成功");
var paths = navigator.fileMgr.getRootPaths();
var writer = new FileWriter(paths[0] + "write.txt");
writer.seek(4);
writer.truncate(writer.position);
// ファイル名は'some'に変更されました。
}
function fail(evt) {
console.log(evt.target.error.code);
}
</script>
</head>
<body onload="onLoad()">
<h1>サンプル</h1>
<p>ファイルに書き込みます。</p>
</body>
</html>
FileTransfer
FileTransfer オブジェクトはファイルをサーバーにアップロードする際に使用します。
プロパティ
N/A
メソッド
- upload: サーバーにファイルを送信
詳細
FileTransfer
オブジェクトはマルチパート形式でHTTPサーバーにPOST処理を行いファイルをアップロードします。
このメソッドはHTTPとHTTPSの両方をサポートします。uploadメソッドに FileUploadOptions
オブジェクトを送ることで、任意のパラメータを追加できます。
アップロードが成功した場合 FileUploadResult
オブジェクトともにsuccessコールバック関数が呼ばれます。
エラーが発生した場合は FileTransferError
オブジェクトとともにerrorコールバックが呼ばれます。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
使用例
var win = function(r) {
console.log("コード = " + r.responseCode);
console.log("結果 = " + r.response);
console.log("送信バイト数 = " + r.bytesSent);
}
var fail = function(error) {
alert("エラーが発生しました: Code = " = error.code);
}
var options = new FileUploadOptions();
options.fileKey="file";
options.fileName="newfile.txt";
options.mimeType="text/plain";
var params = new Object();
params.value1 = "test";
params.value2 = "param";
options.params = params;
var paths = navigator.fileMgr.getRootPaths();
var ft = new FileTransfer();
ft.upload(paths[0] + "newfile.txt", "http://some.server.com/upload.php", win, fail, options);
詳細な使用例
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>連絡先の使用例</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// PhoneGapの読み込みを待機
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap準備完了
//
function onDeviceReady() {
var options = new FileUploadOptions();
options.fileKey="file";
options.fileName="newfile.txt";
options.mimeType="text/plain";
var params = new Object();
params.value1 = "test";
params.value2 = "param";
options.params = params;
var paths = navigator.fileMgr.getRootPaths();
var ft = new FileTransfer();
ft.upload(paths[0] + "newfile.txt", "http://some.server.com/upload.php", win, fail, options);
}
function win(evt) {
console.log("コード = " + r.responseCode);
console.log("結果 = " + r.response);
console.log("送信バイト数 = " + r.bytesSent);
}
function fail(evt) {
alert("エラーが発生しました。: コード = " = error.code);
}
</script>
</head>
<body onload="onLoad()">
<h1>サンプル</h1>
<p>ファイルを読み込みます。</p>
</body>
</html>
FileUploadOptions
FileUploadOptions
オブジェクトはuploadメソッドを実行する際、追加のパラメータを設定する場合に使用します。
プロパティ
- fileKey: フォーム要素の名前を指定します。デフォルトはfileです (DOMString)
- fileName: サーバーに保存する際のファイル名を指定します。デフォルトはimage.jpgです。 (DOMString)
- mimeType: データのMIME形式を指定します。デフォルトはimage/jpegです (DOMString)
- params: その他のHTTPリクエストで送信されるパラメータを指定します (Object)
詳細
FileUploadOptions
オブジェクトはuploadメソッドを実行する際、追加のパラメータを設定する場合に使用します。
FileUploadResult
FileUploadResult
オブジェクトは FileTransfer
オブジェクトの upload メソッドを呼び出し、それが成功した時に返されるオブジェクトです。
プロパティ
- bytesSent: 送信されたバイト数を表します (long)
- responseCode: サーバーから返されたHTTPのレスポンスコードを表します (long)
- response: サーバーから返されたHTTPレスポンスを表します (DOMString)
詳細
FileUploadResult
オブジェクトは FileTransfer
オブジェクトの upload メソッドを呼び出し、それが成功した時に返されるオブジェクトです。
FileError
FileError
オブジェクトはエラーが発生した場合にFileWriter/FileReaderのerrorプロパティ上にセットされます。
プロパティ
- code: 下記のエラーコードのいずれかがセットされます
定数
FileError.NOT_FOUND_ERR
FileError.SECURITY_ERR
FileError.ABORT_ERR
FileError.NOT_READABLE_ERR
FileError.ENCODING_ERR
FileError.NO_MODIFICATION_ALLOWED_ERR
FileError.INVALID_STATE_ERR
FileError.SYNTAX_ERR
詳細
FileError
オブジェクトはファイルの読み書き時に回避不能なエラーが発生した時に発行されます。
現在の状態が FileWriter.DONE または FileWriter.INIT である場合に abort メソッドを呼び出すと、 ABORT_ERR が発行されます。
FileTransferError
FileTransferError
オブジェクトはエラーが発生した時に投げられます。
プロパティ
- code: 定義済みのエラーコードのいずれかが格納されます (int)
定数
FileTransferError.FILE_NOT_FOUND_ERR
FileTransferError.INVALID_URL_ERR
FileTransferError.CONNECTION_ERR
詳細
FileTransferError
オブジェクトはファイルアップロード時にエラーが発生した場合に投げられます。