ファイル転送プラグイン

非推奨プラグイン (Cordova 9.0 以降)
 cordova-plugin-file-transfer の移行については、こちらを参照ください。
テスト環境 ( バージョン番号 ) :1.7.0​
このプラグインの詳細は、 こちらの原文 ( GitHub ) をご確認ください。
このプラグインを使用して、ファイルのアップロードとダウンロードを行えます。
このプラグインでは、グローバルなコンストラクタ 「 FileTransfer 」 と 「 FileUploadOptions 」 を使用します。なお、グローバルスコープに属していますが、使用できるのは、deviceready イベントの発火後になります。
1
document.addEventListener("deviceready", onDeviceReady, false);
2
function onDeviceReady() {
3
    console.log(FileTransfer);
4
}
Copied!
廃止予定
​XMLHttpRequest で導入された新機能により、このプラグインは必要ありません。このプラグインから XMLHttpRequest の新機能へ移行する方法については、Cordova blog post を参照してください。
プラグイン ID
1
cordova-plugin-file-transfer
Copied!
プラグインの追加方法 ( Monaca 上での処理 )
ファイル転送 プラグイン は、 ファイル操作プラグイン に依存しているため、はじめに Monaca クラウド IDEで、File プラグインを [有効]() にし、 次に File Transfe プラグインを有効にしてください。
サポート対象のプラットフォーム
Android
iOS
API の解説
FileTransfer
FileTransfer オブジェクトを使用して、ファイルのアップロード ( HTTP MultiPart POST/PUT リクエストを使用 ) とダウンロードを行います。
プロパティ
onprogress: データの送受信時に、ProgressEventを渡して呼び出す関数。 (Function)
メソッド
upload: サーバーにファイルを送信するときに使用します。
download: サーバーからファイルをダウンロードするときに使用します。
abort: 実行中の送受信を中止するときに使用します。
upload
パラメーター:
fileURL: 端末上のファイルの位置または data URIを指し示すファイルシステムの URL。
後方互換性を考慮する場合には、端末上のファイルへのフルパス ( fullpath ) を使用することもできます ( このページ内の[ 後方互換性に関するメモ書き ]も併せてご確認ください )。
server: ファイルを受け取るサーバーの URL ( encodeURI()を使用して、エンコード)。
successCallback: FileUploadResultオブジェクトを渡して実行するコールバック関数。 (Function)
errorCallback: FileUploadResultを取得するときにエラーが発生した場合に実行されるコールバック関数。FileTransferErrorオブジェクトを渡して呼び出します。(Function)
options: 任意のパラメーター。使用できる key は、次のとおりです。(Object)
fileKey: form 要素の name 属性。デフォルトは、file です。(DOMString)
fileName: サーバーにファイルを保存するときに使用するファイル名。デフォルトは、image.jpgです。 (DOMString)
httpMethod: 使用する、HTTP の method 属性。PUT または POSTを使用します。デフォルトは、POST です。 (DOMString)
mimeType: アップロードするデータの MIMEタイプ。デフォルトは、image/jpeg です。 (DOMString)　
params: HTTP リクエスト内に任意で設定する key と valueの組み合わせ (Object)
chunkedMode: チャンク/チャンクド形式のストリーミング ( chunked
streaming mode )を使用して、データのアップロードを行うか否かの設定。デフォルトは、trueです。 (Boolean)
headers: ヘッダーのプロパティ名とその値の組み合わせ。値が複数ある場合には、ハッシュを使用します。iOS、Android では、Content-Type が記述されている場合には、マルチパートフォームデータ形式 ( multipartform data ) は使用されません。 (Object)
trustAllHosts: 任意のパラメーター。デフォルトは falseです。true に設定した場合、すべてのセキュリティー証明書を許可します。正式リリース版または商用のアプリには推奨しません。Android と iOS で使用できます。 (boolean)
例
1
// !! Assumes variable fileURL contains a valid URL to a text file on the device,
2
//    for example, cdvfile://localhost/persistent/path/to/file.txt
3
​
4
var win = function (r) {
5
    console.log("Code = " + r.responseCode);
6
    console.log("Response = " + r.response);
7
    console.log("Sent = " + r.bytesSent);
8
}
9
​
10
var fail = function (error) {
11
    alert("An error has occurred: Code = " + error.code);
12
    console.log("upload error source " + error.source);
13
    console.log("upload error target " + error.target);
14
}
15
​
16
var options = new FileUploadOptions();
17
options.fileKey = "file";
18
options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
19
options.mimeType = "text/plain";
20
​
21
var params = {};
22
params.value1 = "test";
23
params.value2 = "param";
24
​
25
options.params = params;
26
​
27
var ft = new FileTransfer();
28
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
Copied!
例 アップロード時の Headers と ProgressEvent の使用例 ( Android と iOS 専用 )
1
function win(r) {
2
    console.log("Code = " + r.responseCode);
3
    console.log("Response = " + r.response);
4
    console.log("Sent = " + r.bytesSent);
5
}
6
​
7
function fail(error) {
8
    alert("An error has occurred: Code = " + error.code);
9
    console.log("upload error source " + error.source);
10
    console.log("upload error target " + error.target);
11
}
12
​
13
var uri = encodeURI("http://some.server.com/upload.php");
14
​
15
var options = new FileUploadOptions();
16
options.fileKey="file";
17
options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1);
18
options.mimeType="text/plain";
19
​
20
var headers={'headerParam':'headerValue', 'headerParam2':'headerValue2'};
21
​
22
options.headers = headers;
23
​
24
var ft = new FileTransfer();
25
ft.onprogress = function(progressEvent) {
26
    if (progressEvent.lengthComputable) {
27
        loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
28
    } else {
29
        loadingStatus.increment();
30
    }
31
};
32
ft.upload(fileURL, uri, win, fail, options);
Copied!
download
パラメーター:
source: ファイルのダウンロード元となるサーバーの URL (encodeURI() を使用して、エンコード )。
target: 端末上のファイルの位置を指し示す、ファイルシステムの URL( Filesystem URL
)。後方互換性を考慮する場合には、ここには、端末上のファイルへのフルパスを使用することもできます　(後方互換性に関しては、下の後方互換性に関するメモ書を参照のこと )。
successCallback: FileEntryオブジェクトを渡して実行するコールバック。(Function)
errorCallback: FileEntryの取得時にエラーが発生した場合に実行されるコールバック。FileTransferError オブジェクトを渡して実行します。 (Function)
trustAllHosts: 任意のパラメーター。デフォルトは falseです。true に設定した場合、すべてのセキュリティー証明書を許可します。正式リリース版または商用のアプリには推奨しません。Android と iOS で使用できます。 (boolean)
options: 任意のパラメーター。現時点では、headersのみ使用できます ( BASIC 認証などを指定できる Authorizationヘッダーなどを設定できます )。
例
1
// !! Assumes variable fileURL contains a valid URL to a path on the device,
2
//    for example, cdvfile://localhost/persistent/path/to/downloads/
3
​
4
var fileTransfer = new FileTransfer();
5
var uri = encodeURI("http://some.server.com/download.php");
6
​
7
fileTransfer.download(
8
    uri,
9
    fileURL,
10
    function(entry) {
11
        console.log("download complete: " + entry.toURL());
12
    },
13
    function(error) {
14
        console.log("download error source " + error.source);
15
        console.log("download error target " + error.target);
16
        console.log("download error code" + error.code);
17
    },
18
    false,
19
    {
20
        headers: {
21
            "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
22
        }
23
    }
24
);
Copied!
abort
実行中のファイルの送受信を中止します。 FileTransferError オブジェクトを使用して、失敗時のコールバックが呼び出されます。このオブジェクトには、 FileTransferError.ABORT_ERR エラーコードが格納されています。
例
1
// !! Assumes variable fileURL contains a valid URL to a text file on the device,
2
//    for example, cdvfile://localhost/persistent/path/to/file.txt
3
​
4
var win = function(r) {
5
    console.log("Should not be called.");
6
}
7
​
8
var fail = function(error) {
9
    // error.code == FileTransferError.ABORT_ERR
10
    alert("An error has occurred: Code = " + error.code);
11
    console.log("upload error source " + error.source);
12
    console.log("upload error target " + error.target);
13
}
14
​
15
var options = new FileUploadOptions();
16
options.fileKey="file";
17
options.fileName="myphoto.jpg";
18
options.mimeType="image/jpeg";
19
​
20
var ft = new FileTransfer();
21
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
22
ft.abort();
Copied!
FileUploadResult
FileUploadResult オブジェクトは、FileTransfer オブジェクトの upload() メソッドの成功時のコールバックに渡されます。
プロパティ
bytesSent: アップロード時に、サーバーに送られたバイト ( byte )数 (long)
responseCode: サーバーから返ってきた HTTP レスポンスコード (long)
response: サーバーから返ってきた HTTP レスポンス (DOMString)
headers: サーバーから返ってきた HTTP レスポンスのヘッダー (Object)
現時点では、iOS 上でのみ使用できます。
iOS 特有の動作
responseCode または bytesSent は使用できません。
chunkedMode=true と multipartMode=falseに設定している場合、空ファイルのアップロードはできません。
FileTransferError
エラー発生時、FileTransferError オブジェクトが失敗時のコールバックに渡されます。
プロパティ
code: 後述のエラーコードのいずれか (Number)
source: ソースへの URL (String)
target: ターゲットへの URL (String)
http_status: HTTP ステータスコード。HTTP接続の状態を示すレスポンスコードを受け取った場合のみ、この属性を使用できます。(Number)
body : レスポンスのボディー。HTTP接続の状態を示すレスポンスコードを受け取った場合のみ、この属性を使用できます。(String)
exception: e.getMessage または e.toString のいずれか (String)
iOS 特有の動作
exception は、定義されません。
定数
1 = FileTransferError.FILE_NOT_FOUND_ERR
2 = FileTransferError.INVALID_URL_ERR
3 = FileTransferError.CONNECTION_ERR
4 = FileTransferError.ABORT_ERR
5 = FileTransferError.NOT_MODIFIED_ERR
後方互換性に関するメモ書き
このプラグインの以前のバージョンでは、アップロード時のソースまたはダウンロード時のターゲットには、ファイルの保存場所への端末固有の絶対パス ( device-absolute-file-location ) を使用していました。典型的なパスの形式は、次のとおりでした。
1
/var/mobile/Applications/<application UUID>/Documents/path/to/file  (iOS)
2
/storage/emulated/0/path/to/file                                    (Android)
Copied!
後方互換性を考慮して、これらの形式のパスは今でも使用できます。また、永続的なストレージに、これらのパスを保存して使用していた場合でも、継続して、これらの形式のパスを使用できます。
以前は、これらのパスは、ファイル操作プラグイン ( File プラグイン ) が返す FileEntry と DirectoryEntry オブジェクトの fullPath プロパティ内で、JavaScript 側にも暴露されていました。新しいバーションのファイル操作プラグイン ( File プラグイン ) では、この問題も解消され、JavaScript 側へは暴露されません。
ファイル操作プラグイン ( File プラグイン ) のバージョンを 1.0.0 以降にアップグレードして、加えて、以前は、download() または upload() への引数に entry.fullPath を使用していた場合には、代わりに、ファイルシステムの URL ( Filesystem URL ) を使用するように、コードを変更する必要があります。
FileEntry.toURL() と DirectoryEntry.toURL() では、ファイルシステムの URL ( Filesystem URL ) を、次の形式で返します。
1
cdvfile://localhost/persistent/path/to/file
Copied!
download() と upload() の両メソッド内において、ファイルへの絶対パスを指定する代わりに、この URL を使用できます。
サンプルコード : ファイルのダウンロードとアップロード
ファイル転送プラグインを使用して、ファイルのアップロードとダウンロードを行います。ここでは、次の処理を行います。
​アプリのキャッシュ用ディレクトリーへ、バイナリーファイルをダウンロード​
​ファイルのアップロード​
​ファイルのダウンロード​
アプリのキャッシュ用ディレクトリーへ、バイナリーファイルをダウンロード
ファイル操作プラグイン ( File プラグイン ) とファイル転送プラグインを併用して、 target の作成/取得とファイルのダウンロードを行います ( ダウンロード時の target とは、「 端末上のファイルの位置を指し示す、ファイルシステムの URL 」 であり、この例では、FileEntry オブジェクトを指します )。ファイルをダウンロードする前に、resolveLocalFileSystemURL を使用して、 DirectoryEntry オブジェクトを作成/取得します。成功時のコールバックでは、DirectoryEntry の fs.root.getFile メソッドを使用して、ダウンロード先となるファイル ( FileEntry ) を作成/取得します。
1
window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
2
​
3
    console.log('file system open: ' + fs.name);
4
​
5
    // Make sure you add the domain name to the Content-Security-Policy <meta> element.
6
    var url = 'http://cordova.apache.org/static/img/cordova_bot.png';
7
    // Parameters passed to getFile create a new file or return the file if it already exists.
8
    fs.root.getFile('downloaded-image.png', { create: true, exclusive: false }, function (fileEntry) {
9
        download(fileEntry, url, true);
10
​
11
    }, onErrorCreateFile);
12
​
13
}, onErrorLoadFs);
Copied!
永続的なストレージを使用する場合には、requestFileSystem の実行時に、LocalFileSystem.PERSISTENT を指定します。
FileEntry オブジェクトの作成/取得後、 FileTransfer オブジェクトの download メソッドを使用して、ファイルを ダウンロード します。 FileTransfer の download メソッドの第三引数は、成功時のコールバックです。このコールバック内で、readBinaryFile 関数を使用しています。また、ここで使用している変数 entry には、 download の処理結果として受けとった、新規の FileEntry オブジェクトが格納されています。
1
function download(fileEntry, uri, readBinaryData) {
2
​
3
    var fileTransfer = new FileTransfer();
4
    var fileURL = fileEntry.toURL();
5
​
6
    fileTransfer.download(
7
        uri,
8
        fileURL,
9
        function (entry) {
10
            console.log("Successful download...");
11
            console.log("download complete: " + entry.toURL());
12
            if (readBinaryData) {
13
              // Read the file...
14
              readBinaryFile(entry);
15
            }
16
            else {
17
              // Or just display it.
18
              displayImageByFileURL(entry);
19
            }
20
        },
21
        function (error) {
22
            console.log("download error source " + error.source);
23
            console.log("download error target " + error.target);
24
            console.log("upload error code" + error.code);
25
        },
26
        null, // or, pass false
27
        {
28
            //headers: {
29
            //    "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
30
            //}
31
        }
32
    );
33
}
Copied!
画像を単に表示する場合には、次のように、 FileEntry を渡して、 FileEntry 自身の toURL() 関数を呼び出します。
1
function displayImageByFileURL(fileEntry) {
2
    var elem = document.getElementById('imageElement');
3
    elem.src = fileEntry.toURL();
4
}
Copied!
バイナリーファイルの読み込み後に、なんらかの処理をする場合、FileReader の readAsBinaryString と readAsArrayBuffer の 2 つのメソッドを使用できます。ここでは、readAsArrayBuffer を使用し、FileEntry オブジェクトをこのメソッドに渡します。ファイルの読み込み後は、その処理結果を使用して、 Blob オブジェクトを作成します。
画像をBlob URL形式で表示する場合は、デフォルトのContent-Security-Policyの<meta>要素に img-src blob:;を追加する必要があります。
1
function readBinaryFile(fileEntry) {
2
    fileEntry.file(function (file) {
3
        var reader = new FileReader();
4
​
5
        reader.onloadend = function() {
6
​
7
            console.log("Successful file read: " + this.result);
8
            // displayFileData(fileEntry.fullPath + ": " + this.result);
9
​
10
            var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" });
11
            displayImage(blob);
12
        };
13
​
14
        reader.readAsArrayBuffer(file);
15
​
16
    }, onErrorReadFile);
17
}
Copied!
ファイルの読み込み後、createObjectURL を使用すれば、DOM 上で使用できる URL を取得できます。次に、この URL を使用して、画像を表示します。
1
function displayImage(blob) {
2
​
3
    // Note: Use window.URL.revokeObjectURL when finished with image.
4
    var objURL = window.URL.createObjectURL(blob);
5
​
6
    // Displays image if result is a valid DOM string for an image.
7
    var elem = document.getElementById('imageElement');
8
    elem.src = objURL;
9
}
Copied!
上記で示したように、ダウンロードした画像を単に表示するのであれば、FileEntry.toURL() を使用することもできます。
ファイルのアップロード
ファイル転送プラグインを使用してファイルをアップロードする場合、アップロード対象となるファイルを取得するときには、ファイル操作プラグイン ( File プラグイン ) を使用します ( ダウンロード時と同じく、ファイルは、 FileEtnry オブジェクトとなります )。アップロード前に、 DirectoryEntry の getFile を使用して、アップロード用のファイルを作成/取得します。ここでは、アプリのキャッシュ用ディレクトリー ( fs.root ) 内にファイルを作成しています。次に、アップロードするコンテンツを渡して、 writeFile 関数を実行します。
1
function onUploadFile() {
2
    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
3
​
4
        console.log('file system open: ' + fs.name);
5
        var fileName = "uploadSource.txt";
6
        var dirEntry = fs.root;
7
        dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {
8
​
9
            // Write something to the file before uploading it.
10
            writeFile(fileEntry);
11
​
12
        }, onErrorCreateFile);
13
​
14
    }, onErrorLoadFs);
15
}
Copied!
この例では、 FileWrite オブジェクトを作成/取得して、次に、 upload 関数を実行しています。
1
function writeFile(fileEntry, dataObj) {
2
    // Create a FileWriter object for our FileEntry (log.txt).
3
    fileEntry.createWriter(function (fileWriter) {
4
​
5
        fileWriter.onwriteend = function () {
6
            console.log("Successful file write...");
7
            upload(fileEntry);
8
        };
9
​
10
        fileWriter.onerror = function (e) {
11
            console.log("Failed file write: " + e.toString());
12
        };
13
​
14
        if (!dataObj) {
15
          dataObj = new Blob(['file data to upload'], { type: 'text/plain' });
16
        }
17
​
18
        fileWriter.write(dataObj);
19
    });
20
}
Copied!
ここでは、 upload 関数へ FileEntry オブジェクトを渡しています。なお、実際のアップロード処理には、 FileTransfer オブジェクトの upload 関数を使用します。
1
function upload(fileEntry) {
2
    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
3
    var fileURL = fileEntry.toURL();
4
​
5
    var success = function (r) {
6
        console.log("Successful upload...");
7
        console.log("Code = " + r.responseCode);
8
        // displayFileData(fileEntry.fullPath + " (content uploaded to server)");
9
    }
10
​
11
    var fail = function (error) {
12
        alert("An error has occurred: Code = " + error.code);
13
    }
14
​
15
    var options = new FileUploadOptions();
16
    options.fileKey = "file";
17
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
18
    options.mimeType = "text/plain";
19
​
20
    var params = {};
21
    params.value1 = "test";
22
    params.value2 = "param";
23
​
24
    options.params = params;
25
​
26
    var ft = new FileTransfer();
27
    // SERVER must be a URL that can handle the request, like
28
    // http://some.server.com/upload.php
29
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
30
};
Copied!
ファイルのダウンロード ( ここでは、先ほどの例で使用したファイルをダウンロードします )
先ほどアップロードしたテキストを、今度は、ダウンロードします ( 「 ファイルのアップロード 」 を参照のこと )。必要なものは、有効な URL です ( ダウンロード元を指す URL、たとえば、http://some.server.com/download.php )。 FileTransfer.download メソッドの成功時のハンドラーには、 FileEntry オブジェクトが渡されます。上記のダウンロードの例 ( 「 バイナリーファイルのダウンロード 」 を参照のこと ) と異なる点として、ここでは、ダウンロードの処理結果を読み込むときに、 FileReader.readAsText を使用しています。これは、先ほどのアップロードの例 ( 「 ファイルのアップロード 」 を参照のこと ) では、テキスト形式のコンテンツとして、ファイルがアップロードされているためです。
1
function download(fileEntry, uri) {
2
​
3
    var fileTransfer = new FileTransfer();
4
    var fileURL = fileEntry.toURL();
5
​
6
    fileTransfer.download(
7
        uri,
8
        fileURL,
9
        function (entry) {
10
            console.log("Successful download...");
11
            console.log("download complete: " + entry.toURL());
12
            readFile(entry);
13
        },
14
        function (error) {
15
            console.log("download error source " + error.source);
16
            console.log("download error target " + error.target);
17
            console.log("upload error code" + error.code);
18
        },
19
        null, // or, pass false
20
        {
21
            //headers: {
22
            //    "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
23
            //}
24
        }
25
    );
26
}
Copied!
readFile 関数内で、FileReader オブジェクトの readAsText メソッドを実行します。
1
function readFile(fileEntry) {
2
    fileEntry.file(function (file) {
3
        var reader = new FileReader();
4
​
5
        reader.onloadend = function () {
6
​
7
            console.log("Successful file read: " + this.result);
8
            // displayFileData(fileEntry.fullPath + ": " + this.result);
9
​
10
        };
11
​
12
        reader.readAsText(file);
13
​
14
    }, onErrorReadFile);
15
}
Copied!
関連項目:
​サードパーティー製プラグイン​
​基本プラグイン​
前
ファイル操作プラグイン
次
位置情報の取得プラグイン
最終更新 2mo ago
リンクのコピー
廃止予定
プラグイン ID
プラグインの追加方法 ( Monaca 上での処理 )
サンプルコード : ファイルのダウンロードとアップロード
アプリのキャッシュ用ディレクトリーへ、バイナリーファイルをダウンロード
ファイルのアップロード
ファイルのダウンロード ( ここでは、先ほどの例で使用したファイルをダウンロードします )