cordova-plugin-file-transfer

Этот плагин позволяет загружать и скачивать файлы.

Этот плагин определяет глобальные FileTransfer, FileUploadOptions конструкторы. Несмотря на то, что они находятся в глобальной области, они недоступны до события deviceready.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(FileTransfer);
}

Для получения нескольких идей, ознакомьтесь с примером пример внизу этой страницы или перейдите непосредственно к содержанию справочника.

Сообщайте о проблемах с этим плагином в следящей системе Apache Cordova.

Справочник

Установка

cordova plugin add cordova-plugin-file-transfer

Поддерживаемые платформы

Amazon Fire OS
Android
BlackBerry 10
Браузер
Firefox OS**
iOS
Windows Phone 7 и 8*
Windows

* Не поддерживает onprogress и abort()

** Не поддерживает onprogress

FileTransfer

Объект FileTransfer предоставляет способ загрузки файлов с помощью запросов HTTP POST или PUT в формате multipart и загрузки файлов.

Свойства

onprogress: Вызывается с ProgressEvent, когда передается новый фрагмент данных. (Функция)

Методы

upload: Отправка файла на сервер.
download: Загрузка файла с сервера.
abort: Прерывает текущую передачу.

upload

Параметры:

fileURL: URL файловой системы, представляющий файл на устройстве или URI данных. Для обратной совместимости это также может быть полный путь к файлу на устройстве. (См. Примечания по обратной совместимости ниже)
server: URL сервера, который должен принять файл, закодированный с помощью encodeURI().
successCallback: Обратный вызов, которому передается объект FileUploadResult. (Функция)
errorCallback: Обратный вызов, который выполняется, если произошла ошибка при получении FileUploadResult. Вызывается с объектом FileTransferError. (Функция)
options: Дополнительные параметры (Объект). Допустимые ключи:
- fileKey: Имя элемента формы. По умолчанию file. (DOMString)
- fileName: Имя файла для сохранения на сервере. По умолчанию image.jpg. (DOMString)
- httpMethod: HTTP-метод, который следует использовать — либо PUT, либо POST. По умолчанию POST. (DOMString)
- mimeType: Тип MIME данных для загрузки. По умолчанию image/jpeg. (DOMString)
- params: Набор необязательных пар ключ-значение для передачи в запросе HTTP. (Объект, ключ/значение — DOMString)
- chunkedMode: Флаг, указывающий, следует ли загружать данные в режиме потоковой передачи с разбивкой на фрагменты. По умолчанию true. (Boolean)
- headers: Карта заголовков имени/значения заголовка. Используйте массив для указания более одного значения. В iOS, FireOS и Android, если присутствует заголовок с именем Content-Type, данные в формате multipart form не будут использоваться. (Объект)
trustAllHosts: Дополнительный параметр, по умолчанию false. Если установлено значение true, он принимает все сертификаты безопасности. Это полезно, так как Android отказывается от самозаверенных сертификатов безопасности. Не рекомендуется для использования в производственной среде. Поддерживается в Android и iOS. (boolean)

Пример

// !! Assumes variable fileURL contains a valid URL to a text file on the device,
//    for example, cdvfile://localhost/persistent/path/to/file.txt

var win = function (r) {
    console.log("Code = " + r.responseCode);
    console.log("Response = " + r.response);
    console.log("Sent = " + r.bytesSent);
}

var fail = function (error) {
    alert("An error has occurred: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var options = new FileUploadOptions();
options.fileKey = "file";
options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
options.mimeType = "text/plain";

var params = {};
params.value1 = "test";
params.value2 = "param";

options.params = params;

var ft = new FileTransfer();
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);

Пример с заголовками загрузки и событиями прогресса (только для Android и iOS)

function win(r) {
    console.log("Code = " + r.responseCode);
    console.log("Response = " + r.response);
    console.log("Sent = " + r.bytesSent);
}

function fail(error) {
    alert("An error has occurred: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var uri = encodeURI("http://some.server.com/upload.php");

var options = new FileUploadOptions();
options.fileKey="file";
options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1);
options.mimeType="text/plain";

var headers={'headerParam':'headerValue'};

options.headers = headers;

var ft = new FileTransfer();
ft.onprogress = function(progressEvent) {
    if (progressEvent.lengthComputable) {
        loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
    } else {
        loadingStatus.increment();
    }
};
ft.upload(fileURL, uri, win, fail, options);

FileUploadResult

Объект FileUploadResult передается в обратный вызов успеха объекта FileTransfer методом upload().

Свойства

bytesSent: Количество байт, отправленных на сервер в рамках загрузки. (long)
responseCode: HTTP-код ответа, возвращенный сервером. (long)
response: HTTP-ответ, возвращенный сервером. (DOMString)
headers: HTTP-заголовки ответа сервера. (Объект)
- В настоящее время поддерживается только в iOS.

Особенности iOS

Не поддерживает responseCode или bytesSent.
Не поддерживает загрузку пустого файла с chunkedMode=true и multipartMode=false.

Особенности браузера

withCredentials: boolean, указывающий браузеру установить флаг withCredentials в XMLHttpRequest

Особенности Windows

Параметр options с пустым/нулевым значением исключается в операции загрузки из-за дизайна API Windows.
chunkedMode не поддерживается, и все загрузки устанавливаются в режим без разбивки на фрагменты.

download

Параметры:

source: URL сервера для загрузки файла, закодированный с помощью encodeURI().
target: URL файловой системы, представляющий файл на устройстве. Для обратной совместимости это также может быть полный путь к файлу на устройстве. (См. Примечания по обратной совместимости ниже)
successCallback: Обратный вызов, которому передается объект FileEntry. (Функция)
errorCallback: Обратный вызов, который выполняется, если произошла ошибка при получении FileEntry. Вызывается с объектом FileTransferError. (Функция)
trustAllHosts: Дополнительный параметр, по умолчанию false. Если установлено значение true, он принимает все сертификаты безопасности. Это полезно, так как Android отказывается от самозаверенных сертификатов безопасности. Не рекомендуется для использования в производственной среде. Поддерживается в Android и iOS. (boolean)
options: Дополнительные параметры, в настоящее время поддерживают только заголовки (такие как Authorization (Basic Authentication) и т. д.).

Пример

// !! Assumes variable fileURL contains a valid URL to a path on the device,
//    for example, cdvfile://localhost/persistent/path/to/downloads/

var fileTransfer = new FileTransfer();
var uri = encodeURI("http://some.server.com/download.php");

fileTransfer.download(
    uri,
    fileURL,
    function(entry) {
        console.log("download complete: " + entry.toURL());
    },
    function(error) {
        console.log("download error source " + error.source);
        console.log("download error target " + error.target);
        console.log("download error code" + error.code);
    },
    false,
    {
        headers: {
            "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
        }
    }
);

Особенности WP8

Запросы загрузки кэшируются внутренней реализацией. Чтобы избежать кэширования, передайте заголовок if-Modified-Since методу загрузки.

Особенности браузера

withCredentials: boolean, указывающий браузеру установить флаг withCredentials в XMLHttpRequest

abort

Прерывает текущую передачу. Обратный вызов onerror получает объект FileTransferError с кодом ошибки FileTransferError.ABORT_ERR.

Пример

// !! Assumes variable fileURL contains a valid URL to a text file on the device,
//    for example, cdvfile://localhost/persistent/path/to/file.txt

var win = function(r) {
    console.log("Should not be called.");
}

var fail = function(error) {
    // error.code == FileTransferError.ABORT_ERR
    alert("An error has occurred: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var options = new FileUploadOptions();
options.fileKey="file";
options.fileName="myphoto.jpg";
options.mimeType="image/jpeg";

var ft = new FileTransfer();
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
ft.abort();

FileTransferError

Объект FileTransferError передается в обратный вызов ошибки при возникновении ошибки.

Свойства

code: Один из предопределенных кодов ошибок, перечисленных ниже. (Число)
source: URL источника. (Строка)
target: URL назначения. (Строка)
http_status: HTTP-код состояния. Это свойство доступно только при получении кода состояния ответа от HTTP-соединения. (Число)
body Тело ответа. Это свойство доступно только при получении ответа от HTTP-соединения. (Строка)
exception: Либо e.getMessage, либо e.toString (Строка)

Константы

1 = FileTransferError.FILE_NOT_FOUND_ERR
2 = FileTransferError.INVALID_URL_ERR
3 = FileTransferError.CONNECTION_ERR
4 = FileTransferError.ABORT_ERR
5 = FileTransferError.NOT_MODIFIED_ERR

Особенности Windows

Реализация плагина основана на BackgroundDownloader/BackgroundUploader, что влечет за собой проблемы с задержкой на устройствах Windows (создание/запуск операции может занимать до нескольких секунд). Вы можете использовать XHR или HttpClient в качестве более быстрого варианта для небольших загрузок.

Примечания по обратной совместимости

Предыдущие версии этого плагина принимали только пути к файлам устройства как источник для загрузки или как целевой путь для скачивания. Эти пути обычно имели следующий формат:

/var/mobile/Applications/<application UUID>/Documents/path/to/file  (iOS)
/storage/emulated/0/path/to/file                                    (Android)

Для обратной совместимости эти пути все еще принимаются, и если ваше приложение записало такие пути в постоянное хранилище, их можно продолжать использовать.

Эти пути ранее были доступны в свойстве fullPath объектов FileEntry и DirectoryEntry, возвращаемых плагином File. Однако новые версии плагина File больше не отображают эти пути в JavaScript.

Если вы обновляетесь до новой (1.0.0 или более поздней) версии File, и ранее вы использовали entry.fullPath в качестве аргументов к download() или upload(), вам необходимо изменить свой код, чтобы использовать URL файловой системы вместо этого.

FileEntry.toURL() и DirectoryEntry.toURL() возвращают URL файловой системы вида:

cdvfile://localhost/persistent/path/to/file

которые могут использоваться вместо абсолютного пути к файлу в методах download() и upload().

Пример: загрузка и загрузка файлов

Используйте плагин File-Transfer для загрузки и загрузки файлов. В этих примерах мы демонстрируем несколько задач, таких как:

Загрузка двоичного файла в кэш приложения
Загрузка файла, созданного в корневом каталоге вашего приложения
Загрузка загруженного файла

Загрузка двоичного файла в кэш приложения

Используйте плагин File вместе с плагином File-Transfer, чтобы указать место для файлов, которые вы загружаете (место должно быть объектом FileEntry). Перед загрузкой файла создайте объект DirectoryEntry, используя resolveLocalFileSystemURL и вызвав fs.root в обработчике успешного завершения. Используйте метод getFile объекта DirectoryEntry для создания целевого файла.

window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {

    console.log('file system open: ' + fs.name);

    // Make sure you add the domain name to the Content-Security-Policy <meta> element.
    var url = 'http://cordova.apache.org/static/img/cordova_bot.png';
    // Parameters passed to getFile create a new file or return the file if it already exists.
    fs.root.getFile('downloaded-image.png', { create: true, exclusive: false }, function (fileEntry) {
        download(fileEntry, url, true);

    }, onErrorCreateFile);

}, onErrorLoadFs);

Примечание Для постоянного хранения передайте LocalFileSystem.PERSISTENT в requestFileSystem.

Когда у вас есть объект FileEntry, загрузите файл, используя метод download объекта FileTransfer. Третий аргумент функции download объекта FileTransfer — это обработчик успешного завершения, который вы можете использовать для вызова функции приложения readBinaryFile. В этом примере переменная entry — это новый объект FileEntry, который получает результат операции загрузки.

function download(fileEntry, uri, readBinaryData) {

    var fileTransfer = new FileTransfer();
    var fileURL = fileEntry.toURL();

    fileTransfer.download(
        uri,
        fileURL,
        function (entry) {
            console.log("Successful download...");
            console.log("download complete: " + entry.toURL());
            if (readBinaryData) {
              // Read the file...
              readBinaryFile(entry);
            }
            else {
              // Or just display it.
              displayImageByFileURL(entry);
            }
        },
        function (error) {
            console.log("download error source " + error.source);
            console.log("download error target " + error.target);
            console.log("upload error code" + error.code);
        },
        null, // or, pass false
        {
            //headers: {
            //    "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
            //}
        }
    );
}

Если вам нужно только отобразить изображение, используйте объект FileEntry, вызвав его функцию toURL().

function displayImageByFileURL(fileEntry) {
    var elem = document.getElementById('imageElement');
    elem.src = fileEntry.toURL();
}

В зависимости от требований вашего приложения, вам может потребоваться прочитать файл. Для работы с бинарными файлами FileReader поддерживает два метода: readAsBinaryString и readAsArrayBuffer. В этом примере используйте readAsArrayBuffer и передайте объект FileEntry в метод. После успешного чтения файла создайте объект Blob, используя результат чтения.

function readBinaryFile(fileEntry) {
    fileEntry.file(function (file) {
        var reader = new FileReader();

        reader.onloadend = function() {

            console.log("Successful file read: " + this.result);
            // displayFileData(fileEntry.fullPath + ": " + this.result);

            var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" });
            displayImage(blob);
        };

        reader.readAsArrayBuffer(file);

    }, onErrorReadFile);
}

После успешного чтения файла вы можете создать строку DOM URL, используя createObjectURL, а затем отобразить изображение.

function displayImage(blob) {

    // Note: Use window.URL.revokeObjectURL when finished with image.
    var objURL = window.URL.createObjectURL(blob);

    // Displays image if result is a valid DOM string for an image.
    var elem = document.getElementById('imageElement');
    elem.src = objURL;
}

Как вы видели ранее, вы можете вызвать FileEntry.toURL() вместо этого, чтобы просто отобразить загруженное изображение (пропустить чтение файла).

Загрузка файла

При загрузке файла с помощью плагина File-Transfer используйте плагин File для предоставления файлов для загрузки (опять же, они должны быть объектами FileEntry). Прежде чем вы сможете загрузить что-либо, создайте файл для загрузки, используя метод getFile объекта DirectoryEntry. В этом примере создайте файл в кэше приложения (fs.root). Затем вызовите функцию writeFile приложения, чтобы у вас был некоторый контент для загрузки.

function onUploadFile() {
    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {

        console.log('file system open: ' + fs.name);
        var fileName = "uploadSource.txt";
        var dirEntry = fs.root;
        dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {

            // Write something to the file before uploading it.
            writeFile(fileEntry);

        }, onErrorCreateFile);

    }, onErrorLoadFs);
}

В этом примере создайте некоторый простой контент, а затем вызовите функцию загрузки приложения.

function writeFile(fileEntry, dataObj) {
    // Create a FileWriter object for our FileEntry (log.txt).
    fileEntry.createWriter(function (fileWriter) {

        fileWriter.onwriteend = function () {
            console.log("Successful file write...");
            upload(fileEntry);
        };

        fileWriter.onerror = function (e) {
            console.log("Failed file write: " + e.toString());
        };

        if (!dataObj) {
          dataObj = new Blob(['file data to upload'], { type: 'text/plain' });
        }

        fileWriter.write(dataObj);
    });
}

Передайте объект FileEntry в функцию загрузки. Для выполнения фактической загрузки используйте функцию upload объекта FileTransfer.

function upload(fileEntry) {
    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
    var fileURL = fileEntry.toURL();

    var success = function (r) {
        console.log("Successful upload...");
        console.log("Code = " + r.responseCode);
        // displayFileData(fileEntry.fullPath + " (content uploaded to server)");
    }

    var fail = function (error) {
        alert("An error has occurred: Code = " + error.code);
    }

    var options = new FileUploadOptions();
    options.fileKey = "file";
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
    options.mimeType = "text/plain";

    var params = {};
    params.value1 = "test";
    params.value2 = "param";

    options.params = params;

    var ft = new FileTransfer();
    // SERVER must be a URL that can handle the request, like
    // http://some.server.com/upload.php
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
};

Загрузка загруженного файла

Чтобы загрузить изображение, которое вы только что загрузили, вам понадобится допустимый URL, который может обработать запрос, например, http://some.server.com/download.php. Опять же, обработчик успешного завершения для метода FileTransfer.download получает объект FileEntry. Главное отличие здесь от предыдущих примеров заключается в том, что мы вызываем FileReader.readAsText для чтения результата операции загрузки, потому что мы загрузили файл с текстовым содержимым.

function download(fileEntry, uri) {

    var fileTransfer = new FileTransfer();
    var fileURL = fileEntry.toURL();

    fileTransfer.download(
        uri,
        fileURL,
        function (entry) {
            console.log("Successful download...");
            console.log("download complete: " + entry.toURL());
            readFile(entry);
        },
        function (error) {
            console.log("download error source " + error.source);
            console.log("download error target " + error.target);
            console.log("upload error code" + error.code);
        },
        null, // or, pass false
        {
            //headers: {
            //    "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
            //}
        }
    );
}

В функции readFile вызовите метод readAsText объекта FileReader.

function readFile(fileEntry) {
    fileEntry.file(function (file) {
        var reader = new FileReader();

        reader.onloadend = function () {

            console.log("Successful file read: " + this.result);
            // displayFileData(fileEntry.fullPath + ": " + this.result);

        };

        reader.readAsText(file);

    }, onErrorReadFile);
}

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/7.x/reference/cordova-plugin-file-transfer/index.html