cordova-plugin-file

Этот плагин реализует API файлов, предоставляя чтение/запись файлов, находящихся на устройстве.

Этот плагин основан на нескольких спецификациях, включая: API файлов HTML5 http://www.w3.org/TR/FileAPI/

Разделы и расширения системы Последняя версия: http://www.w3.org/TR/2012/WD-file-system-api-20120417/ Хотя большая часть кода плагина была написана, когда действовала более ранняя спецификация: http://www.w3.org/TR/2011/WD-file-system-api-20110419/

Он также реализует спецификацию FileWriter: http://dev.w3.org/2009/dap/file-system/file-writer.html

Примечание Хотя спецификация W3C FileSystem устарела для веб-браузеров, API FileSystem поддерживаются в приложениях Cordova с этим плагином для платформ, указанных в списке Поддерживаемые платформы, за исключением платформы Браузер.

Чтобы получить несколько идей о том, как использовать плагин, ознакомьтесь с примером внизу этой страницы. Для дополнительных примеров (ориентированных на браузер) см. статью HTML5 Rocks о FileSystem FileSystem article.

Для обзора других вариантов хранения обратитесь к руководству по хранению Cordova storage guide.

Этот плагин определяет глобальный cordova.file объект.

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

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

Установка

cordova plugin add cordova-plugin-file

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

• Android
• iOS
• OS X
• Windows*
• Браузер

* Эти платформы не поддерживают FileReader.readAsArrayBuffer ни FileWriter.write(blob).

Где хранить файлы

Начиная с версии 1.2.0, предоставляются URL важных каталогов файловой системы. Каждый URL имеет вид file:///path/to/spot/ и может быть преобразован в DirectoryEntry с помощью window.resolveLocalFileSystemURL().

• cordova.file.applicationDirectory - Только для чтения каталог, где установлено приложение. (iOS, Android, BlackBerry 10, OSX, windows)

• cordova.file.applicationStorageDirectory - Корневой каталог песочницы приложения; в iOS и Windows это место является только для чтения (но определенные подкаталоги [например, /Documents в iOS или /localState в Windows] предназначены для чтения/записи). Все данные в нем являются частными для приложения. (iOS, Android, BlackBerry 10, OSX)

• cordova.file.dataDirectory - Постоянное и частное хранилище данных в песочнице приложения с использованием внутренней памяти (в Android, если вам нужно использовать внешнюю память, используйте .externalDataDirectory). В iOS этот каталог не синхронизируется с iCloud (используйте .syncedDataDirectory). (iOS, Android, BlackBerry 10, windows)

• cordova.file.cacheDirectory - Каталог для кэшированных файлов данных или любых файлов, которые ваше приложение может легко пересоздать. ОС может удалить эти файлы, когда на устройстве заканчивается место, но приложения не должны полагаться на ОС для удаления файлов из этого каталога. (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 - Временный каталог, который ОС может очистить по своему усмотрению. Не полагайтесь на ОС для очистки этого каталога; ваше приложение должно всегда удалять файлы по мере необходимости. (iOS, OSX, windows)

• cordova.file.syncedDataDirectory - Содержит файлы, специфичные для приложения, которые должны быть синхронизированы (например, с iCloud). (iOS, windows)

• cordova.file.documentsDirectory - Файлы, частные для приложения, но значимые для других приложений (например, файлы Office). Обратите внимание, что для OSX это каталог пользователя ~/Documents. (iOS, OSX)

• cordova.file.sharedDirectory - Файлы, доступные всем приложениям в целом (BlackBerry 10)

Схемы файловой системы

Хотя технически это деталь реализации, полезно знать, как свойства cordova.file.* отображаются на физические пути на реальном устройстве.

Схема файловой системы iOS

* Файлы сохраняются при перезапуске и обновлении приложения, но этот каталог может очищаться ОС по мере необходимости. Ваше приложение должно уметь пересоздавать любые удаленные данные.

** Файлы могут сохраняться при перезапуске приложения, но не полагайтесь на это. Файлы не гарантировано сохранятся при обновлении. Ваше приложение должно удалять файлы из этого каталога, когда это необходимо, так как ОС не гарантирует, когда (или даже если) эти файлы будут удалены.

*** ОС может очищать содержимое этого каталога по мере необходимости, но не полагайтесь на это. Вы должны очищать этот каталог, как это необходимо для вашего приложения.

Схема файловой системы Android

* ОС может периодически очищать этот каталог, но не полагайтесь на это поведение. Очищайте содержимое этого каталога соответствующим образом для вашего приложения. Если пользователь вручную очистит кэш, содержимое этого каталога удаляется.

** ОС не очищает этот каталог автоматически; вы несете ответственность за управление содержимым самостоятельно. Если пользователь вручную очистит кэш, содержимое каталога удаляется.

Примечание: Если внешний накопитель не может быть смонтирован, свойства cordova.file.external* являются null.

Макет файловой системы OS X

Примечание: Это макет для приложений, не использующих режим песочницы. Если вы включите режим песочницы, applicationStorageDirectory будут расположены ниже ~/Library/Containers/<bundle-id>/Data/Library/Application Support.

* Файлы сохраняются при перезапуске и обновлении приложения, но этот каталог может быть очищен ОС в любое время. Ваше приложение должно уметь восстанавливать любые данные, которые могут быть удалены. Вы должны очищать этот каталог соответствующим образом для вашего приложения.

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

Макет файловой системы Windows

* ОС может периодически очищать этот каталог

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

Местоположение постоянного хранилища Android

Существует несколько допустимых мест для хранения постоянных файлов на устройстве Android. См. эту страницу для подробного обсуждения различных возможностей.

Предыдущие версии плагина выбирали местоположение временных и постоянных файлов при запуске, в зависимости от того, утверждало ли устройство, что карта SD (или эквивалентный раздел хранения) смонтирована. Если карта SD была смонтирована, или если был доступен большой раздел внутреннего хранилища (например, на устройствах Nexus), то постоянные файлы хранились в корневом каталоге этого пространства. Это означало, что все приложения Cordova могли видеть все файлы, доступные на карте.

Если карта SD не была доступна, то предыдущие версии хранили данные в /data/data/<packageId>, что изолирует приложения друг от друга, но может привести к совместному использованию данных между пользователями.

Теперь можно выбрать, хранить ли файлы во внутреннем хранилище или использовать предыдущую логику, с предпочтением в файле конфигурации вашего приложения (config.xml). Для этого добавьте одну из этих двух строк в config.xml:

<preference name="AndroidPersistentFileLocation" value="Internal" />

<preference name="AndroidPersistentFileLocation" value="Compatibility" />

Без этой строки плагин File будет использовать Internal в качестве значения по умолчанию. Если тег предпочтения присутствует, и не является одним из этих значений, приложение не запустится.

Если ваше приложение уже было выпущено пользователям с использованием более старой (до 3.0.0) версии этого плагина и хранило файлы в постоянной файловой системе, то вы должны установить предпочтение в Compatibility , если в вашем config.xml нет указания местоположения для постоянной файловой системы. Переключение на расположение "Внутреннее" может означать, что существующие пользователи, которые обновят свое приложение, возможно, не смогут получить доступ к своим ранее сохранённым файлам, в зависимости от их устройства.

Если ваше приложение новое или никогда ранее не хранило файлы в постоянной файловой системе, то настройка Internal обычно рекомендуется.

Медленные рекурсивные операции для /android_asset

Перечисление каталогов активов очень медленно на Android. Вы можете ускорить его, добавив src/android/build-extras.gradle в корень вашего проекта Android (также требуется cordova-android@4.0.0 или выше).

Разрешение на запись во внешнее хранилище, когда оно не смонтировано в Marshmallow

Для работы с внешними файлами в Marshmallow приложениям необходимо запрашивать разрешения на чтение/запись. По умолчанию, ваше приложение имеет разрешение на запись в cordova.file.applicationStorageDirectory и cordova.file.externalApplicationStorageDirectory, и плагин не запрашивает разрешение на эти два каталога, если внешнее хранилище не смонтировано. Однако из-за ограничения, если внешнее хранилище не смонтировано, он запросит разрешение на запись в cordova.file.externalApplicationStorageDirectory.

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

• cordova.file.applicationStorageDirectory является только для чтения; попытка сохранения файлов в корневом каталоге завершится ошибкой. Используйте одно из других свойств cordova.file.* , определенных для iOS (только applicationDirectory и applicationStorageDirectory являются только для чтения).
• FileReader.readAsText(blob, encoding)
  • Параметр encoding не поддерживается, и всегда используется кодировка UTF-8.

Расположение постоянного хранилища iOS

Существует два допустимых местоположения для сохранения постоянных файлов на устройстве iOS: каталог Documents и каталог Library. Предыдущие версии плагина всегда сохраняли постоянные файлы только в каталоге Documents. Это имело побочный эффект, делая все файлы приложения видимыми в iTunes, что часто было нежелательно, особенно для приложений, обрабатывающих множество мелких файлов, а не создающих полные документы для экспорта, что является предполагаемым назначением каталога.

Теперь можно выбрать, сохранять ли файлы в каталоге documents или library, используя предпочтение в файле config.xml вашего приложения. Для этого добавьте одну из этих двух строк в config.xml:

<preference name="iosPersistentFileLocation" value="Library" />

<preference name="iosPersistentFileLocation" value="Compatibility" />

Без этой строки плагин File будет использовать Compatibility в качестве значения по умолчанию. Если тег предпочтения присутствует, и не является одним из этих значений, приложение не запустится.

Если ваше приложение уже было выпущено пользователям, используя более старую (до 1.0) версию этого плагина и сохранило файлы в постоянной файловой системе, то вы должны установить предпочтение в Compatibility. Переключение расположения на Library означало бы, что существующие пользователи, обновившие своё приложение, не смогут получить доступ к ранее сохранённым файлам.

Если ваше приложение новое или ранее никогда не сохраняло файлы в постоянной файловой системе, то значение Library рекомендуется по умолчанию.

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

Общие особенности и замечания

• Каждый браузер использует свою собственную изолированную файловую систему. IE и Firefox используют IndexedDB в качестве основы. Все браузеры используют обратную косую черту в качестве разделителя каталогов в пути.
• Элементы каталога должны создаваться последовательно. Например, вызов fs.root.getDirectory('dir1/dir2', {create:true}, successCallback, errorCallback) завершится ошибкой, если каталог dir1 не существует.
• Плагин запрашивает разрешение пользователя на использование постоянного хранилища при первом запуске приложения.
• Плагин поддерживает cdvfile://localhost (локальные ресурсы) только. То есть внешние ресурсы не поддерживаются через cdvfile.
• Плагин не следует "Ограничения именования File System API 8.3".
• Функция Blob и File close не поддерживается.
• FileSaver и BlobBuilder не поддерживаются этим плагином и не имеют заглушек.
• Плагин не поддерживает requestAllFileSystems. Эта функция также отсутствует в спецификации.
• Элементы в каталоге не будут удалены, если вы используете флаг create: true для существующего каталога.
• Файлы, созданные с помощью конструктора, не поддерживаются. Используйте вместо этого метод entry.file.
• Каждый браузер использует свой собственный формат для ссылок на blob URL.
• readAsDataURL функция поддерживается, но тип медиа в Chrome зависит от расширения имени файла, тип медиа в IE всегда пустой (что эквивалентно text-plain согласно спецификации), тип медиа в Firefox всегда application/octet-stream. Например, если содержимое является abcdefg , то Firefox возвращает data:application/octet-stream;base64,YWJjZGVmZw==, IE возвращает data:;base64,YWJjZGVmZw==, Chrome возвращает data:<mediatype depending on extension of entry name>;base64,YWJjZGVmZw==.
• toInternalURL возвращает путь в формате file:///persistent/path/to/entry (Firefox, IE). Chrome возвращает путь в формате cdvfile://localhost/persistent/file.

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

• Файловая система Chrome не готова сразу после события device ready. В качестве обходного решения вы можете подписаться на событие filePluginIsReady. Пример: javascript window.addEventListener('filePluginIsReady', function(){ console.log('File plugin is ready');}, false); Вы можете использовать функцию window.isFilePluginReadyRaised для проверки, было ли уже вызвано событие.
• Квоты файловой системы TEMPORARY и PERSISTENT window.requestFileSystem в Chrome не ограничены.
• Для увеличения квоты постоянного хранилища в Chrome необходимо вызвать метод window.initPersistentFileSystem. Квота постоянного хранилища по умолчанию составляет 5 МБ.
• Chrome требует аргумента запуска --allow-file-access-from-files для поддержки API через протокол file:///.
• File объект не будет изменён, если вы используете флаг {create:true} при получении существующего Entry.
• свойство events cancelable установлено в true в Chrome. Это противоречит спецификации.
• toURL функция в Chrome возвращает путь, начинающийся с filesystem:, в зависимости от хоста приложения. Например, filesystem:file:///persistent/somefile.txt, filesystem:http://localhost:8080/persistent/somefile.txt.
• toURL результат функции не содержит конечного слэша в случае записи в каталог. Однако Chrome правильно обрабатывает каталоги с URL, оканчивающимися на слэш.
• resolveLocalFileSystemURL метод требует, чтобы входной url имел префикс filesystem. Например, параметр url для resolveLocalFileSystemURL должен быть в формате filesystem:file:///persistent/somefile.txt , а не в формате file:///persistent/somefile.txt в Android.
• Устаревшая функция toNativeURL не поддерживается и не имеет заглушки.
• setMetadata функция не указана в спецификации и не поддерживается.
• INVALIDMODIFICATIONERR (код: 9) выбрасывается вместо SYNTAX_ERR(код: 8) при запросе несуществующей файловой системы.
• INVALIDMODIFICATIONERR (код: 9) выбрасывается вместо PATHEXISTSERR(код: 12) при попытке эксклюзивного создания файла или каталога, который уже существует.
• INVALIDMODIFICATIONERR (код: 9) выбрасывается вместо NOMODIFICATIONALLOWED_ERR(код: 6) при попытке вызвать removeRecursively на корневой файловой системе.
• INVALIDMODIFICATIONERR (код: 9) выбрасывается вместо NOTFOUNDERR(код: 1) при попытке переместить в каталог, которого не существует.

Особенности реализации на базе IndexedDB (Firefox и IE)

• . и .. не поддерживаются.
• IE не поддерживает режим file:///; поддерживается только режим размещения (http://localhost:xxxx).
• Размер файловой системы Firefox не ограничен, но каждое расширение размером 50 МБ запросит разрешение пользователя. IE10 позволяет до 10 МБ объединённого кеша AppCache и IndexedDB, используемого в реализации файловой системы, без запроса. После достижения этого уровня вас спросят, хотите ли вы увеличить его до максимум 250 МБ на сайт. Таким образом, параметр size для функции requestFileSystem не влияет на файловую систему в Firefox и IE.
• readAsBinaryString функция не указана в спецификации и не поддерживается в IE, и не имеет заглушки.
• file.type всегда равно null.
• Не следует создавать запись с использованием результата обратного вызова DirectoryEntry, который был удалён. В противном случае вы получите «висящую запись».
• Перед чтением файла, который был только что записан, необходимо получить новый экземпляр этого файла.
• setMetadata функция, которая не указана в спецификации, поддерживает только изменение поля modificationTime.
• copyTo и moveTo функции не поддерживают каталоги.
• Метаданные каталогов не поддерживаются.
• И Entry.remove, и directoryEntry.removeRecursively не завершаются ошибкой при удалении непустых каталогов — удаляемые каталоги очищаются вместе с содержимым.
• abort и truncate функции не поддерживаются.
• События прогресса не генерируются. Например, этот обработчик не будет выполнен: javascript writer.onprogress = function() { /*commands*/ };

Примечания по обновлению

В версии 1.0.0 этого плагина структуры FileEntry и DirectoryEntry были изменены, чтобы соответствовать опубликованной спецификации.

Предыдущие (до 1.0.0) версии плагина хранили абсолютный путь к файлу устройства в свойстве fullPath объектов Entry. Эти пути обычно выглядели так

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

Эти пути также возвращались методом toURL() объектов Entry.

С версии 1.0.0 атрибут fullPath — это путь к файлу, относительный к корню HTML-файловой системы. Таким образом, указанные выше пути теперь оба будут представлены объектом FileEntry со свойством fullPath

/path/to/file

Если ваше приложение работает с абсолютными путями устройства, и вы ранее получали эти пути через свойство fullPath объектов Entry, то вы должны обновить свой код, чтобы использовать entry.toURL() вместо этого.

Для обратной совместимости метод resolveLocalFileSystemURL() будет принимать абсолютный путь устройства и возвращать объект Entry , соответствующий ему, при условии, что этот файл существует в файловых системах TEMPORARY или PERSISTENT.

Это особенно было проблемой с плагином File-Transfer, который ранее использовал абсолютные пути устройства (и по-прежнему может их принимать). Он был обновлён для правильной работы с URL файловой системы, поэтому замена entry.fullPath на entry.toURL() должна решить любые проблемы с работой этого плагина с файлами на устройстве.

В версии 1.1.0 значение возвращаемое toURL() было изменено (см. CB-6394), чтобы возвращать абсолютный URL 'file://' где это возможно. Чтобы гарантировать URL 'cdvfile:', вы можете использовать toInternalURL() сейчас. Этот метод теперь возвращает URL файловой системы в формате

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

что позволяет однозначно идентифицировать файл.

Протокол cdvfile

Назначение

cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file может использоваться для платформенно-независимых путей к файлам. Пути cdvfile поддерживаются основными плагинами — например, вы можете скачать файл mp3 по пути cdvfile через cordova-plugin-file-transfer и воспроизвести его с помощью cordova-plugin-media.

*Примечание*: Подробную информацию о доступных корнях fs см. в разделах Где хранить файлы, Макеты файловых систем и Настройка плагина.

Чтобы использовать cdvfile в качестве тега src, вы можете преобразовать его в системный путь с помощью метода toURL() разрешенного объекта fileEntry, который можно получить с помощью resolveLocalFileSystemURL — см. примеры ниже.

Вы также можете использовать пути cdvfile:// напрямую в DOM, например:

<img src="cdvfile://localhost/persistent/img/logo.png" />

Примечание: Этот метод требует обновления правил Content Security:

• Добавьте схему cdvfile: к тегу мета Content-Security-Policy страницы index, например:
  • <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap:cdvfile:https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
• Добавьте <access origin="cdvfile://*" /> в config.xml.

Преобразование cdvfile:// в системный путь

resolveLocalFileSystemURL('cdvfile://localhost/temporary/path/to/file.mp4', function(entry) {
    var nativePath = entry.toURL();
    console.log('Native URI: ' + nativePath);
    document.getElementById('video').src = nativePath;

Преобразование системного пути в cdvfile://

resolveLocalFileSystemURL(nativePath, function(entry) {
    console.log('cdvfile URI: ' + entry.toInternalURL());

Использование cdvfile в основных плагинах

fileTransfer.download(uri, 'cdvfile://localhost/temporary/path/to/file.mp3', function (entry) { ...

var my_media = new Media('cdvfile://localhost/temporary/path/to/file.mp3', ...);
my_media.play();

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

• Использование путей cdvfile:// в DOM не поддерживается на платформе Windows (путь можно преобразовать в системный).

Список кодов ошибок и их значений

При возникновении ошибки будет использоваться один из следующих кодов.

Настройка плагина (необязательно)

Набор доступных файловых систем может настраиваться для каждой платформы. iOS и Android распознают тег в config.xml, который указывает имена файловых систем для установки. По умолчанию все корни файловых систем включены.

<preference name="iosExtraFilesystems" value="library,library-nosync,documents,documents-nosync,cache,bundle,root" />
<preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external,assets,root" />

Android

• files: Директория внутренней файловой системы приложения
• files-external: Директория внешней файловой системы приложения
• sdcard: Глобальная директория внешней файловой системы (это корень карты SD, если она установлена). Для использования этой директории требуется разрешение android.permission.WRITE_EXTERNAL_STORAGE.
• cache: Директория кеша приложения
• cache-external: Директория внешнего кеша приложения
• assets: Пакет приложения (только для чтения)
• root: Вся файловая система устройства
• applicationDirectory: Только чтение с ограниченным доступом. Копирование файлов в эту директорию возможно, но непосредственное чтение приведет к ошибке "файл не найден". Android также поддерживает специальную файловую систему под названием "documents", которая представляет собой поддиректорию "/Documents/" в файловой системе "files".

iOS

• library: Директория Library приложения
• documents: Директория Documents приложения
• cache: Директория Cache приложения
• bundle: Пакет приложения; местоположение самого приложения на диске (только для чтения)
• root: Вся файловая система устройства

По умолчанию, директории Library и Documents могут быть синхронизированы с iCloud. Вы также можете запросить две дополнительные файловые системы, library-nosync и documents-nosync, которые представляют собой специальную несинхронизированную директорию в файловой системе /Library или /Documents.

Пример: Создание файлов и директорий, запись, чтение и добавление файлов

Плагин File позволяет, например, сохранять файлы во временное или постоянное хранилище приложения (заключенное хранилище) и сохранять файлы в других местах, зависящих от платформы. Примеры кода в этом разделе демонстрируют различные задачи, включая:

• Доступ к файловой системе
• Использование кроссплатформенных URL-адресов Cordova для хранения файлов (см. Где хранить файлы для получения дополнительной информации)
• Создание файлов и директорий
• Запись в файлы
• Чтение файлов
• Добавление в файлы
• Отображение файла изображения

Создание постоянного файла

Перед использованием API плагина File вы можете получить доступ к файловой системе с помощью requestFileSystem. При этом вы можете запросить постоянное или временное хранилище. Постоянное хранилище не удаляется, пока пользователь не предоставит разрешение.

При получении доступа к файловой системе с помощью requestFileSystem, доступ предоставляется только для заключенной файловой системы (заключение ограничивает доступ приложением), а не для общего доступа к любому месту файловой системы на устройстве. (Чтобы получить доступ к местам файловой системы за пределами заключенного хранилища, используйте другие методы, такие как window.resolveLocalFileSystemURL, которые поддерживают платформозависимые места. Один пример этого приведен в разделе Добавление файла.)

Вот запрос к постоянному хранилищу.

Примечание При работе с клиентами WebView (вместо браузера) или с нативными приложениями (Windows) не нужно использовать requestQuota перед использованием постоянного хранилища.

window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {

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

        console.log("fileEntry is file?" + fileEntry.isFile.toString());
        // fileEntry.name == 'someFile.txt'
        // fileEntry.fullPath == '/someFile.txt'
        writeFile(fileEntry, null);

    }, onErrorCreateFile);

}, onErrorLoadFs);

Обратный вызов успеха получает объект FileSystem (fs). Используйте fs.root для возврата объекта DirectoryEntry, который вы можете использовать для создания или получения файла (вызвать getFile). В этом примере fs.root — это объект DirectoryEntry, представляющий постоянное хранилище в заключенной файловой системе.

Обратный вызов успеха для getFile получает объект FileEntry. Вы можете использовать его для выполнения операций записи и чтения файлов.

Создание временного файла

Вот пример запроса к временному хранилищу. Временное хранилище может быть удалено операционной системой, если на устройстве мало памяти.

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

    console.log('file system open: ' + fs.name);
    createFile(fs.root, "newTempFile.txt", false);

}, onErrorLoadFs);

При использовании временного хранилища вы можете создать или получить файл, вызвав getFile. Как и в примере с постоянным хранилищем, это даст вам объект FileEntry, который вы можете использовать для операций чтения или записи.

function createFile(dirEntry, fileName, isAppend) {
    // Creates a new file or returns the file if it already exists.
    dirEntry.getFile(fileName, {create: true, exclusive: false}, function(fileEntry) {

        writeFile(fileEntry, null, isAppend);

    }, onErrorCreateFile);

}

Запись в файл

После получения объекта FileEntry вы можете записать в файл, вызвав createWriter, который возвращает объект FileWriter в обратном вызове успеха. Вызовите метод write объекта FileWriter, чтобы записать в файл.

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...");
            readFile(fileEntry);
        };

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

        // If data object is not passed in,
        // create a new Blob instead.
        if (!dataObj) {
            dataObj = new Blob(['some file data'], { type: 'text/plain' });
        }

        fileWriter.write(dataObj);
    });
}

Чтение файла

Для чтения существующего файла также нужен объект FileEntry. Используйте свойство file объекта FileEntry для получения ссылки на файл, а затем создайте новый объект FileReader. Вы можете использовать методы, такие как readAsText, чтобы начать операцию чтения. Когда операция чтения завершена, this.result хранит результат операции чтения.

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);
}

Добавление в файл с помощью альтернативных методов

Конечно, часто вам нужно будет добавлять в существующие файлы, а не создавать новые. Вот пример этого. Этот пример показывает другой способ доступа к файловой системе с помощью window.resolveLocalFileSystemURL. В этом примере передайте кроссплатформенный URL-адрес файла Cordova, cordova.file.dataDirectory, в функцию. Обратный вызов успеха получает объект DirectoryEntry, который вы можете использовать для таких задач, как создание файла.

window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function (dirEntry) {
    console.log('file system open: ' + dirEntry.name);
    var isAppend = true;
    createFile(dirEntry, "fileToAppend.txt", isAppend);
}, onErrorLoadFs);

В дополнение к этому использованию, вы можете использовать resolveLocalFileSystemURL для получения доступа к некоторым местам файловой системы, которые не являются частью заключенной файловой системы. См. Где хранить файлы для получения дополнительной информации; многие из этих мест хранилища зависят от платформы. Вы также можете передавать кроссплатформенные места файловой системы в resolveLocalFileSystemURL с использованием протокола cdvfile.

Для операции добавления в функции createFile , которая вызывается в предшествующем коде (см. предыдущие примеры для фактического кода), нет ничего нового. createFile вызывает writeFile. В writeFile, вы проверяете, запрошена ли операция добавления.

После получения объекта FileWriter вызовите метод seek, и передайте индексное значение позиции, в которую нужно записать. В этом примере вы также проверяете, существует ли файл. После вызова seek вызовите метод write объекта FileWriter.

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

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

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

        // If we are appending data to file, go to the end of the file.
        if (isAppend) {
            try {
                fileWriter.seek(fileWriter.length);
            }
            catch (e) {
                console.log("file doesn't exist!");
            }
        }
        fileWriter.write(dataObj);
    });
}

Хранение существующего двоичного файла

Мы уже показали, как записать в файл, который вы только что создали в заключенной файловой системе. Что, если вам нужно получить доступ к существующему файлу и преобразовать его в то, что можно сохранить на устройстве? В этом примере вы получаете файл с помощью запроса xhr, а затем сохраняете его в кэше в заключенной файловой системе.

Прежде чем получить файл, получите ссылку на FileSystem с помощью requestFileSystem. Передав window.TEMPORARY в вызов метода (как и раньше), возвращаемый объект FileSystem (fs) представляет кэш в заключенной файловой системе. Используйте fs.root для получения объекта DirectoryEntry, который вам нужен.

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

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

}, onErrorLoadFs);

Для полноты изложения вот запрос xhr для получения объекта Blob изображения. В этом коде нет ничего специфичного для Cordova, кроме того, что вы передаете ссылку на объект DirectoryEntry, который вы уже получили, в качестве аргумента функции saveFile. Вы сохраните изображение blob и отобразите его позже после чтения файла (для проверки операции).

function getSampleFile(dirEntry) {

    var xhr = new XMLHttpRequest();
    xhr.open('GET', 'http://cordova.apache.org/static/img/cordova_bot.png', true);
    xhr.responseType = 'blob';

    xhr.onload = function() {
        if (this.status == 200) {

            var blob = new Blob([this.response], { type: 'image/png' });
            saveFile(dirEntry, blob, "downloadedImage.png");
        }
    };
    xhr.send();
}

Примечание Для безопасности Cordova 5 в предшествующем коде требуется добавить доменное имя http://cordova.apache.org в элемент тега мета Content-Security-Policy в файле index.html.

После получения файла скопируйте содержимое в новый файл. Текущий объект DirectoryEntry уже связан с кэшем приложения.

function saveFile(dirEntry, fileData, fileName) {

    dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {

        writeFile(fileEntry, fileData);

    }, onErrorCreateFile);
}

В writeFile вы передаете объект Blob в качестве данных dataObj и сохраните его в новом файле.

function writeFile(fileEntry, dataObj, isAppend) {

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

        fileWriter.onwriteend = function() {
            console.log("Successful file write...");
            if (dataObj.type == "image/png") {
                readBinaryFile(fileEntry);
            }
            else {
                readFile(fileEntry);
            }
        };

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

        fileWriter.write(dataObj);
    });
}

После записи в файл, прочитайте его и отобразите. Вы сохранили изображение как двоичные данные, поэтому можете прочитать его с помощью FileReader.readAsArrayBuffer.

function readBinaryFile(fileEntry) {

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

        reader.onloadend = function() {

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

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

        reader.readAsArrayBuffer(file);

    }, onErrorReadFile);
}

После чтения данных вы можете отобразить изображение с помощью такого кода. Используйте window.URL.createObjectURL для получения DOM-строки для изображения Blob.

function displayImage(blob) {

    // Displays image if result is a valid DOM string for an image.
    var elem = document.getElementById('imageFile');
    // Note: Use window.URL.revokeObjectURL when finished with image.
    elem.src = window.URL.createObjectURL(blob);
}

Отображение файла изображения

Для отображения изображения с помощью FileEntry, вы можете вызвать метод toURL.

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

Если вы используете некоторые платформенно-специфичные URI вместо FileEntry и хотите отобразить изображение, вам может потребоваться включить основную часть URI в элемент Content-Security-Policy в index.html. Например, в Windows 10, вы можете включить ms-appdata: в свой элемент . Вот пример.

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">

Создание каталогов

В этом коде вы создаете каталоги в корне приложения хранилища. Вы можете использовать этот код с любым записываемым хранилищем (то есть с любым DirectoryEntry). Здесь вы записываете в кэш приложения (предполагается, что вы использовали window.TEMPORARY для получения объекта FileSystem) передавая fs.root в эту функцию.

Этот код создает папку /NewDirInRoot/images в кэше приложения. Для платформенно-специфичных значений смотрите Схемы расположения файловой системы.

function createDirectory(rootDirEntry) {
    rootDirEntry.getDirectory('NewDirInRoot', { create: true }, function (dirEntry) {
        dirEntry.getDirectory('images', { create: true }, function (subDirEntry) {

            createFile(subDirEntry, "fileInNewSubDir.txt");

        }, onErrorGetDir);
    }, onErrorGetDir);
}

При создании подпапок вам необходимо создавать каждую папку отдельно, как показано в предыдущем коде.