Monaca Docs
  • Monaca とは
  • 最初のアプリを作る
  • アプリをテストする
  • Monaca リリース情報
    • iOS プライバシーマニフェスト対応
    • 「ニフクラ mobile backend」終了に関するお知らせ
    • プラグイン uses-permission タグの重複修正機能
    • Cordova 12 の変更点
    • iOSストア版Monaca デバッガー配信停止と代替機能のご案内
    • iOS App Store への送信エラー (ITMS-90165)
    • cordova-custom-configのビルドエラー
    • Cordova 11 の変更点
    • Cordova 10 の変更点
    • Cordova 9.0 の変更点
    • 利用規約の変更
    • 新しい Monaca CLI と Localkit
    • CordovaからCapacitorへの移行
  • Monacaガイド
    • Monaca での開発の概要
    • Monaca クラウド IDE
      • 概要
      • Monaca クラウド IDE の機能
      • ターミナル機能
      • エディターのショートカット一覧
      • プロジェクトの構成
        • ファイル・フォルダー構成
        • JS/CSS コンポーネント
        • Cordova プラグイン
        • ユーザー Cordova プラグイン
      • バージョン管理
        • 概要
        • GitHub との連携
        • Git SSH との連携
      • Monaca CI
        • 概要
        • アプリ配信 / 配布サービス (デプロイサービス)
        • Appetize.ioへの配信
        • DeployGateへの配信
        • Firebase への配信
      • ビルド
        • iOS アプリのビルド
          • iOS アプリのビルド
          • Monaca と Xcode 間でのビルド設定の再利用
        • Android アプリのビルド
        • Windows アプリのビルド
        • Electron アプリのビルド
          • Windows アプリのビルド
        • PWA アプリのビルド
        • ビルド環境の設定
        • ビルド履歴一覧
        • 一般的なビルドとアップロードエラー
      • 配布方法
        • App Store での配布
          • App Store Connect ガイド
          • iOS アプリ アップロード機能
        • Google Play での配布
        • 公式ストア経由以外での配布
      • パッケージダウンロード機能
      • チュートリアル
    • Monaca Localkit
      • 概要
      • ペアリングとデバッグ
      • リモートビルドと配布申請
      • トラブルシューティング
        • インストール ( Windows の場合 )
        • インストール ( Mac OS X の場合 )
        • アンインストール時 ( Windows の場合 )
        • 不完全なファイル・フォルダー構成
        • プレビューウィンドウが更新されない
        • Error while installing
        • nodeのインストールが必要です
      • チュートリアル
    • Monaca CLI
      • 概要
      • Monaca CLI コマンド
      • ペアリングとデバッグ
      • リモートビルドと配布申請
      • トラブルシューティング ガイド
      • チュートリアル
    • Monaca デバッガー
      • 機能の概要
      • インストール方法
        • Android 向けの Monaca デバッガー
        • iOS 向け Monaca デバッガー
        • Android エミュレーター向け Monaca デバッガー
      • 使用例
      • iOS カスタムビルド版デバッガー
      • iOS シミュレータービルド
      • トラブルシューティング ガイド
      • チュートリアル
    • チームダッシュボード
    • クイックビューア
    • 他のプラットフォームからの移行
      • 移行時の確認ポイント
      • クラウドIDE プレビュー機能の設定
      • Angular からの移行
      • Ionic からの移行
      • React からの移行
      • Vue からの移行
      • Telerik からの移行
  • 🛠️アプリビルド
    • iOS ビルド
      • 秘密鍵とCSRの作成
      • 証明書の作成
      • プロビジョニング・プロファイルの更新
  • チュートリアル
    • Monaca クラウド IDE チュートリアル
      • パート 1 : プロジェクトの作成
      • パート 2 : Monaca クラウド IDE と Monaca デバッガーとの連携
      • パート 3 : Monaca アプリのビルド
      • パート 4 : Monaca アプリの配布申請
    • Monaca Localkit チュートリアル
      • パート 1 : プロジェクトの作成
      • パート 2 : Monaca Localkit と Monaca デバッガーとの連携
      • パート 3 : Monaca アプリのビルド
      • パート 4 : Monaca アプリの配布申請
    • Monaca CLI チュートリアル
      • パート 1 : プロジェクトの作成
      • パート 2 : Monaca CLI と Monaca デバッガーとの連携
      • パート 3 : Monaca アプリのビルド
      • パート 4 : Monaca アプリの配布申請
    • Electron アプリ開発
      • NPMパッケージの利用方法
      • Web APIの利用方法
    • バーコードスキャナープラグイン
    • Cordova Sqlite Storage プラグイン
    • Cordova Google Analytics プラグイン
    • Cordova Firebase プラグイン
    • Cordova In-app Purchase プラグイン
    • Cordova AppVersion プラグイン
    • Cordova Ionic Keyboard プラグイン
    • Cordova Social Sharing プラグイン
    • Phonegap Push プラグイン
  • APIの解説
    • Monaca API
      • Monaca クラウド & リモートビルド API
      • ユーティリティ
    • 基本プラグイン
      • Cordova 12.0
        • Battery プラグイン
        • Camera プラグイン
        • Device プラグイン
        • Device Motion プラグイン
        • Device Orientation プラグイン
        • Dialog プラグイン
        • File プラグイン
        • Geolocation プラグイン
        • InAppBrowser プラグイン
        • Media プラグイン
        • Media Capture プラグイン
        • Network Information プラグイン
        • Vibration プラグイン
        • StatusBar プラグイン
      • Cordova 11.0
        • Battery プラグイン
        • Camera プラグイン
        • Device プラグイン
        • Device Motion プラグイン
        • Device Orientation プラグイン
        • Dialog プラグイン
        • File プラグイン
        • Geolocation プラグイン
        • InAppBrowser プラグイン
        • Media プラグイン
        • Media Capture プラグイン
        • Network Information プラグイン
        • Splashscreen プラグイン
        • Vibration プラグイン
        • StatusBar プラグイン
      • Cordova 10.0
        • Battery プラグイン
        • Camera プラグイン
        • Device プラグイン
        • Device Motion プラグイン
        • Device Orientation プラグイン
        • Dialog プラグイン
        • File プラグイン
        • Geolocation プラグイン
        • InAppBrowser プラグイン
        • Media プラグイン
        • Media Capture プラグイン
        • Network Information プラグイン
        • Splashscreen プラグイン
        • Vibration プラグイン
        • StatusBar プラグイン
        • Whitelist プラグイン ( Android 専用 )
      • Cordova 9.0
        • バッテリー情報の取得 プラグイン
        • カメラ操作 プラグイン
        • 住所録の取得 プラグイン
        • 端末情報の取得 プラグイン
        • 端末のモーション検知 プラグイン
        • 端末のオリエンテーション検知 プラグイン
        • ダイアログの制御 プラグイン
        • ファイル操作 プラグイン
        • ファイル転送 プラグイン
        • 位置情報の取得 プラグイン
        • 表記の国際化対応 プラグイン
        • InAppBrowser プラグイン
        • メディア操作 プラグイン
        • メディアキャプチャー プラグイン
        • ネットワーク情報の取得 プラグイン
        • スプラッシュスクリーンの制御 プラグイン
        • バイブレーションの制御 プラグイン
        • ステータスバーの制御 プラグイン
        • ホワイトリストへの登録 プラグイン ( Android 専用 )
    • サードパーティー製プラグイン
      • AdvancedHTTPプラグイン
      • PhoneGap BarcodeScanner
      • Custom Config
      • Datepicker
      • Share ( Android 向け )
      • WebIntent ( Android 向け )
    • Monaca 提供プラグイン
      • アプリロジック暗号化 (Encrypt プラグイン)
      • In-App アップデーター (In-App Updater)
      • セキュア ストレージ
      • NFC リーダー
      • バーコードスキャナー
      • Androidビルドメモリサイズ設定
    • 外部サービス連携
      • Repro
      • AppsFlyer
    • 設定ファイル
      • Android
        • Android の設定
        • config.xml
        • AndroidManifest.xml
      • iOS
        • iOS の設定
        • config.xml
        • MonacaApp-info.plist
  • サンプル & Tips
    • Firestoreを利用する
    • サンプルアプリ
      • Twitter アプリ
      • Facebook アプリ
      • 広告 アプリ (AdMob)
      • Hello World アプリ
      • メモ帳アプリ
      • ブロック崩しゲーム
      • Flickrアプリ
      • TODO管理 アプリ
      • 電車図鑑アプリ
      • 時計アプリ
      • 誕生年の計算アプリ
      • おみくじ占いアプリ
      • RSS リーダーアプリ
    • 開発 Tips
      • 音楽の再生方法
      • スプラッシュ画像の制御方法
      • データベースの利用方法
  • Webpack5への更新
  • 機能
    • SNS 認証
    • プッシュ通知
    • データベース
  • 外部サービス連携ガイド
    • Firebase
      • アプリの登録と設定ファイルの取得
  • 移行ガイド
    • ニフクラ mobile backend
      • プッシュ通知
        • Firebaseサービスの設定
        • ソースコードの移行
      • データストア
        • ソースコードの移行
        • データの移行
        • データ移行スクリプト実行手順
      • 会員管理・認証
        • 会員管理 データの移行
        • Firebase Authentication パスワード再設定サンプル
        • Firebase Authenticationを使用したユーザー名認証の方法
      • スクリプト
        • Firebase Functions開発環境の作成
        • サンプル共通項目
        • サンプル1(GETサンプル)
        • サンプル2(POSTサンプル)
        • サンプル3(DELETEサンプル)
        • エミュレータでのテスト
      • ファイルストア
        • ファイルアップロード
        • ファイル検索
        • ファイル一覧表示
        • ファイル削除
  • FAQ
    • 概要
    • IDE
    • ビルド
    • リリース
    • 契約プラン
    • アプリケーション
    • 使用方法
    • Freeプラン
    • デバッガー
  • 対応環境
  • トラブルシューティング
    • プレビューログがリロードを繰り返す (Vue packages version mismatch error)
  • Monaca製品サイト
  • 運営会社
  • English
GitBook提供
このページ内
  • プラグイン ID
  • プラグインの追加方法
  • 対象プラットフォーム
  • ファイルの保存場所
  • ファイルシステムの概要
  • iOS のファイルシステムの概要
  • Android のファイルシステムの概要
  • 後方互換
  • Android 特有の動作
  • iOS 特有の動作
  • アップグレード時の注意点
  • cdvfile プロトコル
  • 目的
  • エラーコードの種類と解説
  • プラグインの設定 ( 任意 )
  • Android
  • iOS
  • サンプルコード : ファイルの作成、ディレクトリーの作成、ファイルへの書き込み、ファイルの読み込み、ファイルへの追記
  • 永続的なファイルの作成
  • 一時的に使用するファイルの作成
  • ファイルへの書き込み
  • ファイルの読み込み
  • ファイルへの追記 ( ファイルシステムへのアクセス時には、上記とは異なるメソッドを使用してみます )
  • 既存のバイナリーファイルの保存
  • 画像ファイルの表示
  • ディレクトリーの作成

役に立ちましたか?

  1. APIの解説
  2. 基本プラグイン
  3. Cordova 11.0

File プラグイン

前へDialog プラグイン次へGeolocation プラグイン

最終更新 1 年前

役に立ちましたか?

テスト環境 ( バージョン番号 ) :

このプラグインの詳細は、 をご確認ください。

このプラグインでは、独自の File API ( 以後、「 ファイル操作 API 」 と呼称します ) を使用して、端末内のファイルへアクセス ( 読み取り/書き込み ) します。このプラグインは、以下を含むいくつかの仕様に基づいています。

  • なお、このプラグインで使用されているコードのほとんどは、の仕様がまだサポートされていた頃に作成されたものです。

  • も実装しています。

W3C FileSystem仕様はWebブラウザでは推奨されていませんが、FileSystem APIは、このプラグインを使用することでCordovaアプリケーションにおいてブラウザプラットフォームを除き、 Supported Platforms にあるプラットフォームでサポートされます。

プラグインの使い方については、このページの下部にある sample を参照してください。 その他の例(ブラウザ中心)については、HTML5 Rocksの を参照してください。 他のストレージオプションの概要については、Cordovaの を参照してください。

このプラグインは、グローバルな cordova.file オブジェクトを定義します。 グローバルスコープでは、deviceready イベントの発火後まで使用できません。

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

プラグイン ID

cordova-plugin-file

プラグインの追加方法

対象プラットフォーム

  • Android

  • iOS

ファイルの保存場所

  • cordova.file.applicationDirectory - アプリのインストール先となる、読み取り専用のディレクトリーです。 ( iOS、Android、BlackBerry 10、OSX、windows )

  • cordova.file.applicationStorageDirectory - アプリのサンドボックス ( sandbox ) のルートディレクトリーです。iOS と Windows では、このディレクトリーは読み取り専用です ( ただし、iOS の /Documents、Windows の /localState など、特定のサブディレクトリーに関しては、読み取りと書き込みができます )。このディレクトリーに格納されているすべてのデータは、対象のアプリのみが利用できます。 ( iOS、Android、BlackBerry 10、OSX )

  • cordova.file.dataDirectory - アプリのサンドボックス ( sandbox ) 内の永続的およびプライベートなデータストレージです。内蔵のメモリーが使用されます。Android の場合、外部のメモリーが必要なときは、.externalDataDirectory を使用します。また、iOS の場合、このディレクトリーは、iCloud 間とは同期されません ( .syncedDataDirectory を使用します )。 ( iOS、Android、BlackBerry 10、windows )

  • cordova.file.cacheDirectory - キャッシュしたデータファイルまたは他のファイル ( アプリ側で再作成可能な、なんらかのファイル ) 用のディレクトリーです。端末側のストレージが不足する場合には、OS 側が、これらのファイルを削除します。ファイルの削除は、本来であれば、アプリ側で制御すべき処理です。 ( 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 - Temp ディレクトリーです。OS 側がコンテンツを自由に削除できますが、このような挙動に頼るのではなく、このディレクトリーの処理は、アプリ側で常に行うべきです。 ( 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 のファイルシステムの概要

端末上のパス

cordova.file.*

iosExtraFileSystems

r/w

永続性の有無

OS 側で削除

同期の有無

プライベート

/var/mobile/Applicati ons/<UUID>/

applicationStorageDirectory

r

N/A

N/A

N/A

Yes

appname.app/

applicationDirectory

bundle

r

N/A

N/A

N/A

Yes

www/

r

N/A

N/A

N/A

Yes

Documents/

documentsDirectory

documents

r/w

Yes

No

Yes

Yes

NoCloud/

documents-nosync

r/w

Yes

No

No

Yes

Cloud/

syncedDataDirectory

r/w

Yes

No

Yes

Yes

Caches/

cacheDirectory

cache

r/w

Yes*

Yes***

No

Yes

tmp/

tempDirectory

r/w

No**

Yes***

No

Yes

* アプリの再起動後・アップグレード後でも、このディレクトリーに置かれたファイルには影響が出ません。ただし、このディレクトリーのコンテンツの削除は、OS 側で、自由にできます。よって、削除された場合でも、アプリ側で再作成できる必要があります。

** アプリの再起動時でも、ごくまれな例外を除き、このディレクトリーに置かれたファイルには影響はでません。アップデート時には、ファイルは消去されてしまう場合があります。可能であれば、このディレクトリーのファイルは、アプリ側の任意のタイミングで削除できるようにしましょう。デフォルトのままだと、削除のタイミング、または、削除するか否かの決定は、OS 側で行われます。

*** このディレクトリーのコンテンツの削除は、必要に応じて、OS 側が行います。しかし、この OS 側の挙動に頼らずに、アプリが正常に動作するよう、開発者側で、必要に応じて削除できるようにしましょう。

Android のファイルシステムの概要

端末上のパス

cordova.file.*

AndroidExtraFileSystems

r/w

永続性の有無

OS 側で削除

プライベート

file:///android_asset/

applicationDirectory

assets

r

N/A

N/A

Yes

/data/data/<app-id>/

applicationStorageDirectory

r/w

N/A

N/A

Yes

cache

cacheDirectory

cache

r/w

Yes

Yes*

Yes

files

dataDirectory

files

r/w

Yes

No

Yes

Documents

documents

r/w

Yes

No

Yes

<sdcard>/

externalRootDirectory

sdcard

r/w***

Yes

No

No

Android/data/<app-id>/

externalApplicationStorageDirectory

r/w

Yes

No

No

cache

externalCacheDirectory

cache-external

r/w

Yes

No**

No

files

externalDataDirectory

files-external

r/w

Yes

No

No

* このディレクトリーのコンテンツの削除は、定期的に、OS 側で行われます。しかし、この OS 側の挙動に頼らずに、アプリが正常に動作するよう、開発者側で、必要に応じて削除しましょう。また、ディレクトリーのコンテンツまたはキャッシュの削除は、ユーザー側でも、手動で行えるべきです。

** このディレクトリーのコンテンツの削除は、OS 側では行われません。コンテンツの処理は、開発者側で行います。また、ディレクトリーのコンテンツまたはキャッシュの削除は、ユーザー側でも手動で行えるべきです。

*** API30より書き込みができなくなりました。

外部のストレージがマウントできない場合には、cordova.file.external\* プロパティは null になります。

後方互換

Android 特有の動作

Android の永続的な保存場所 ( Persistent Storage )

このプラグインの旧バーションでは、端末が SD カード ( または、同等のストレージ パーティション ) をマウントしたか否かを基準に、一時的なファイルと永続的なファイルの保存場所を、起動時に、プラグイン側で選択していました。SD カードがマウントされた場合、または、大容量の内部ストレージ パーティションが利用できた場合 ( 例 : Nexus 端末 ) には、その領域のルートに、永続性的なファイルを保存してました。このため、すべての Cordova アプリが、カード内のすべてのファイルを参照できました。[ 翻訳メモ : 「 マウント 」 とは、PC 周辺機器を端末側が 「 認識 」 して、使用可能な状態にあることを指します。]

SD カードが使用できなかった場合、旧バージョンのプラグインでは、/data/data/<packageId> 下に、データを保存してました。この場合、アプリ間ではデータの処理は個別化されましたが、ユーザー間ではデータの共有ができました。

現在では、アプリの config.xml ファイルの preference 設定を使用して、内部 ( Internal ) の保存場所を使用するか、または、以前の設定 ( Compatibility ) をそのまま使用して、ファイルを保存するか選択することができます。この設定を行うには、次の記述のいずれかを、config.xml ファイルに追加します。

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

この記述を追加しない場合、ファイル操作プラグイン ( File プラグイン ) では、デフォルトとして、Internal ( 内部 ) を使用します。なお、preference タグが存在する場合でも、上記の値のいずれかが設定されていなければ、アプリは起動しません。

このプラグインの旧バーション ( 3.0.0 より前 ) を実装したアプリの配布をすでに行っており、加えて、なんらかのファイルシステムにファイルを保存していた場合には、preference を Compatibility に設定する必要があります ( データの保存先となるファイルシステムを、config.xml で指定していないときも同様 )。Compatibility から Internal に変更した場合、既存のユーザーは、以前使用していたファイルへアクセスできないことがあります ( 端末により、動作は異なります )。

ここ最近で開発されたアプリの場合、または、永続的なファイルシステムにファイルを以前保存したことがなかった場合、Internal の設定を推奨します。

/android_asset に対して行う処理の問題点

Android の asset ディレクトリー内に置かれたファイル ( 群 ) の一覧を取得する処理は、時間がかかることは周知のとおりですが、Android プロジェクトのルートに src/android/build-extras.gradle を追加で置けば、この処理時間を短縮できます ( Android 向け Cordova の 4.0.0 以上が必要 )。

Marshmallow 上で外部ストレージがマウントされていない場合の 「 書き込み 」 パーミッション

iOS 特有の動作

  • cordova.file.applicationStorageDirectory は、読み取り専用です。このルートディレクトリーへファイルを保存しようとした場合、失敗します。よって、iOS がサポートしている他の cordova.file.* プロパティを使用します ( applicationDirectory と applicationStorageDirectory のみ、読み取り専用です )。

  • FileReader.readAsText(blob, encoding)

  • encoding パラメーターは使用できません。UTF-8 形式のエンコーディングが常に使用されます。

iOS の永続的な保存場所 ( Persistent Storage )

iOS 端末には、永続的なファイル ( persistent file ) の保存に使用できる場所が 2 つあります。1 つ目は Documents ディレクトリー、2 つ目は Library ディレクトリーです。このプラグインの旧バージョンでは、Documents ディレクトリーのみに、永続性的なファイルを保存していました。ただ、この方法を使用すると、iTunes では、アプリのファイルが、暴露されてしまう問題がありました。特に、エクスポートとは無関係なファイルを複数処理するアプリでは、問題となりました ( Documents ディレクトリーは、本来、エクスポートを行うドキュメントをまとめて置くために使用されます )。

現在では、アプリの config.xml ファイルの preference 設定を使用して、Documents ディレクトリーまたは Library ディレクトリーのいずれかに、ファイルを保存するか選択できます。この設定を行う場合、次の記述のいずれかを、config.xml ファイルに追加します。

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

この記述を追加しない場合、ファイル操作プラグイン ( File プラグイン ) では、デフォルトとして、Compatibility を使用します。なお、preference タグが存在する場合でも、上記の値のいずれかが設定されていなければ、アプリは起動しません。

旧バーション ( 1.0 より前 ) のプラグインを実装したアプリの配布をすでに行っている場合、加えて、そのとき、永続的なファイルシステム ( persistent filesystem ) にファイルを保存していた場合、preference を Compatibility に設定します。Library に場所を変更してしまうと、アプリをアップグレードしたときに、以前保存したファイルに、アクセスできなくなる場合があります。

ここ最近で開発されたアプリの場合、または、永続的なファイルシステムにファイルを以前保存したことがない場合、Library の設定を推奨します。

アップグレード時の注意点

公開されている仕様に近づくように、このプラグインの v1.0.0 から、FileEntry と DirectoryEntry の構造に修正を加えました。

以前のバーション ( 1.0.0 より前 ) のプラグインでは、Entry オブジェクトの fullPath プロパティ内に、「 端末固有のファイル保存場所への絶対パス ( device-absolute-file-location ) 」 を保存していました。典型的なパスは、次のようになっていました。

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

また、これらのパスは、Entry オブジェクトの toURL() メソッドを使用しても取得できました。

v1.0.0 では、*HTML ファイルシステムのルート構造に近似した*、ファイルへのパスが fullPath 属性には置かれます。よって、上記の 2 つのパスは、FileEntry オブジェクトの fullPath では、次のようになっています。

/path/to/file

現在でもアプリ側で 「 端末固有の絶対パス ( device-absolute-paths ) 」 を使用し、加えて、以前は、Entry オブジェクトの fullPath プロパティを使用して、これらの絶対パスを取得していた場合には、entry.toURL() を使用するように、コードを更新してください。

後方互換性 ( backwards compatibility ) に関して付け加えると、現在でも、resolveLocalFileSystemURL() メソッドに、「 端末固有の絶対パス ( device-absolute-paths ) 」 を渡せば、それに対応した Entry オブジェクトが返ってきます ( ただし、TEMPORARY または PERSISTENT ファイルシステムに、ファイルが存在していることが前提です )。

なお、ファイル転送プラグイン ( File Transfer プラグイン ) でも、「 端末固有の絶対パス ( device-absolute-paths ) 」 を以前使用していたため、同じような問題がありました ( 現在も使用できます )。現在では、ファイルシステムの URL ( FileSystem URL ) を使用し、支障なく動作するように更新されています。よって、このプラグインを使用する場合、entry.fullPath を entry.toURL() に置き換えれば、端末上のファイルを支障なく操作できるはずです。

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

この形式で、ファイルを、一意に識別できます。

v7.0.0 で、Android 用の toURL() の戻り値が更新され、アプリのコンテンツが file:// スキームから提供される場合、絶対パスとして file:// URL が返されるようになりました。

アプリのコンテンツが、http(s)://スキームから提供される場合、代わりにcdvfile形式のURLが返されます。cdvfile形式のURLは、内部メソッドtoInternalURL()から生成されます。

下記URLは、toInternalURL()が、ファイルシステムのURLを返す例です。

https://localhost/persistent/path/to/file

正しいURLが返されるように、常にtoURL()を使用することをお勧めします。

cdvfile プロトコル

Androidは対応していません。

目的

「 cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file 」 形式のファイルパスを使用できます。この形式は、プラットフォームには依存せず、多くのプラットフォームでサポートされています。また、基本 Cordova プラグイン ( Core Cordova プラグイン ) でも、この cdvfile 形式のパスがサポートされています。たとえば、ファイル転送プラグイン ( File Transfer プラグイン ) を使用して、mp3 ファイルを、cdvfile 形式で指定された場所へダウンロードすることができます。また、メディア操作プラグイン ( Media プラグイン ) を使用すれば、そのファイルを再生できます。

タグの src に cdvfile を使用する場合、取得した fileEntry の toURL() メソッドを使用すれば、cdvfile のパスをネイティブパス ( native path ) に変換することができます。fileEntry は、resolveLocalFileSystemURL を使用して取得できます。下に例を示しています。また、 cdvfile:// のパスをDOM内で直接使うこともできます。使用例です。

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

この方法を使用する場合には、次の Content Security ルールが追加で必要となります。

  • index ページの Content-Security-Policy の meta タグに、cdvfile: スキームを追加します。

<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:// からネイティブパス ( native path ) への変換

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

ネイティブパス ( native path ) から 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();

エラーコードの種類と解説

エラーが投げられた場合、次のいずれかのコードが使用されています。

コード

定数

1

NOT_FOUND_ERR

2

SECURITY_ERR

3

ABORT_ERR

4

NOT_READABLE_ERR

5

ENCODING_ERR

6

NO_MODIFICATION_ALLOWED_ERR

7

INVALID_STATE_ERR

8

SYNTAX_ERR

9

INVALID_MODIFICATION_ERR

10

QUOTA_EXCEEDED_ERR

11

TYPE_MISMATCH_ERR

12

PATH_EXISTS_ERR

プラグインの設定 ( 任意 )

使用するファイルシステムは、プラットフォーム毎に設定できます。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 カードであれば、SD カードのルートとなります)。使用する場合、android.permission.WRITE_EXTERNAL_STORAGEのパーミッション ( 許可 ) が必要です。

  • cache: アプリが使用する、キャッシュ用のディレクトリーです ( 内部)。

  • cache-external: アプリが使用する、キャッシュ用のディレクトリーです( 外部 )。

  • assets: アプリのバンドル(読み取り専用)

  • root: 端末のすべてのファイルシステム

他にも、Android では 「 documents 」 と呼ばれるファイルシステムが使用できます ( このファイルシステムは、「 files 」 ファイルシステム内の 「 /Documents/ 」 のサブディレクトリーです )。

iOS

  • library: アプリの Library ディレクトリーです。

  • documents: アプリの Documents ディレクトリーです。

  • cache: アプリの Cache ディレクトリーです。

  • bundle: bundle container です (ディスク上のアプリ本体の格納先、読み取り専用 )。

  • root: 端末のすべてのファイルシステム

デフォルトでは、 library と documents ディレクトリーは、iCloud と同期できます。また、library-nosync と documents-nosync の 2 つのファイルシステムも追加して使用できます。これらのファイルシステムは、それぞれ、 /Library と /Documents ファイルシステム下に置かれますが、同期の対象外となるディレクトリーです。

サンプルコード : ファイルの作成、ディレクトリーの作成、ファイルへの書き込み、ファイルの読み込み、ファイルへの追記

ファイル操作プラグインを使用して、一時的または永続的なストレージへ ( サンドボックス化された、アプリのストレージを使用 )、ならびに、プラットフォーム側が指定する、他のストレージへファイルを保存できます。下に例示しているコードでは、次の処理方法を確認できます。

永続的なファイルの作成

ファイル操作プラグイン提供の API を使用する前に、requestFileSystem を使用すれば、ファイルシステムへアクセスすることができます。また、requestFileSystem の実行時には、PERSISTENT または TEMPORARY のいずれかを指定できます。PERSISTENT にストレージを指定した場合、ユーザーの許可がない限り、ストレージの削除はできません。

requestFileSystem を使用してファイルシステムへアクセスした場合、サンドボックス化されたファイルシステムへのアクセスのみ許可され ( サンドボックス化した場合、対象のアプリのみ、ストレージにアクセス可能 )、端末上の他のファイルシステムへのアクセスはできません。サンドボックス化されたストレージ以外へアクセスする場合には、window.resolveLocalFileSystemURL などのメソッドを使用します ( 参考として、下の 「 ファイルへの追記 」 を参照のこと )。

次のコードでは、永続的なストレージを作成しています ( PERSISTENT を指定 )。

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 ) が渡されます。DirectoryEntry オブジェクトを返すように指定する場合には、fs.root を使用します。また、fs.root は、ファイルの作成/取得時にも使用できます ( getFile を実行 )。ここでは、fs.root は、DirectoryEntry オブジェクトであり、同時に、サンドボックス化されたファイルシステム内に作成された、永続的なストレージへのリファレンスとなります。

getFile の成功時のコールバックには、FileEntry オブジェクトが渡されます。FileEntry オブジェクトを使用して、ファイルへの書き込み・ファイルの読み込みを行います。

一時的に使用するファイルの作成

次の例では、一時的なストレージを作成しています ( TEMPORARY を指定 )。端末上のメモリーが少なくなった場合、OS 側がこのストレージを削除することもあります。

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 オブジェクトが渡されるので、FileWriter の write メソッドを実行して、ファイルへの書き込みを行います。

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 オブジェクトを使用します。最初に、FileEntry の file プロパティ を使用して、ファイルへのリファレンスを取得します。次に、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 を使用した追記方法を記します。ここでは、cordova.file.dataDirectory ( Cordova の File URL ) を使用します。成功時のコールバックに、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 へ渡す File URL には、*cdvfile プロトコル* 形式も使用できます。

追記処理における createFile 関数に関しても、先ほど解説した内容と異なる点はありません ( 「 一時的に使用するファイルの作成 」 を参照のこと )。createFile を実行し、次に、writeFile を実行します。writeFile では、追記処理であることを指定します。

FileWriter オブジェクトの取得後、seek メソッドを呼び出し、追記位置を指定します。また、ここでは、ファイルが存在するかも確認しています。seek の処理完了後、FileWriter の write メソッドを実行します。

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 リクエストを使用してファイルを取得し、サンドボックス化されたファイルシステムのキャッシュに、取得したファイルを保存します。

ファイルを取得する前に、requestFileSystem を使用して、ファイルシステム ( FileSystem ) へのリファレンスを取得します。以前と同じように、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);

getSampleFile 内の処理を記述します。ここでは、XHR リクエストを使用して、Blob 形式の画像を取得しています。saveFile 関数へ渡す引数として、以前に取得していた、DirectoryEntry のリファレンスを使用していること以外は、Cordova 固有のコードは特にありません。この後の処理で、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();
}

ファイルの取得後、新規作成したファイルへコンテンツをコピーします。下の 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);
}

データの読み込み後、次のようなコードを使用すれば、画像を表示できます。Blob 形式の画像 ( 表示用 ) を取得するため、 window.URL.createObjectURL を使用します。

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 の代わりに )、画像を表示させる場合、index.html の Content-Security-Policy 要素に、URI のホストを指定します。次に例を記します。

<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 ) であれば、次のコードを使用できます。ここでは、createDirectory に fs.root を渡して、アプリのキャッシュ用ディレクトリーを使用します ( FileSystem オブジェクトの取得時、window.TEMPORARY を設定したことを前提とします )。

次のコードでは、アプリのキャッシュ用ディレクトリー内に /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);
}

サブディレクトリーを作成する場合には、上記のコードのように、各フォルダーをそれぞれ作成する必要があります。

このプラグインを使用する場合には、Monaca クラウド IDE の [ Cordova プラグインの管理 ] 上で、File プラグインをにします。

v1.2.0 以降、ファイルシステムのディレクトリーへのパスを示す URL が使用できるようになりました。この URL の形式は、 です。また、window.resolveLocalFileSystemURL() を使用すれば、次のような DirectoryEntry に、この URL を変換することもできます。

Android 端末には、永続的なファイル ( persistent file ) の保存に使用できる場所が複数あります。さまざまな想定および用法に関しての議論は、 をご確認ください。

Marchmallow では、外部のストレージへの書き込みおよび外部のストレージからの読み込みを行う場合、ユーザー側に許可を求めることを必須要件にしています。なお、cordova.file.applicationStorageDirectory と cordova.file.externalApplicationStorageDirectory への書き込みに関しては、 でパーミッションがアプリ側に付与されているため、プラグイン側ではユーザー側に許可を求めませんが、外部のストレージがマウントされていないときだけ、通知の意味も込めて、ユーザー側の許可を求めます。また、同様に、なんらかの理由で外部のストレージがマウントされていない場合にも、cordova.file.externalApplicationStorageDirectory に書き込みを行ってよいか、プラグイン側からユーザー側に確認します。

v1.1.0 では、toURL() の戻り値は、可能であれば、file:// 形式の絶対 URL を返すように仕様が変わりました ( を参照のこと )。 cdvfile: 形式の URL を取得したい場合には、現在、toInternalURL() を使用できます。このメソッドでは、次の形式の ファイルシステム URL ( FileSystem URL ) を返します。

使用できるファイルシステムのルートに関しては、「 」、「 」、「 をご確認ください。

Cordova の FILE URL を使用した、 ( 詳細は、上記の 「 ファイルの保存場所 」 を参照のこと )

と の作成

Cordova 5 以降、セキュリティー上の理由により、次のコードの実行には、Content-Security-Policy 要素内で、 を設定する必要があります ( index.html 内 )。

7.0.0
こちらの原文 ( GitHub )
The HTML5 File API
The Directories and System extensions Latest
an earlier spec
FileWriter spec
FileSystem
storage guide
file:///path/to/spot/
こちらのページ ( 英語 )
デフォルト
CB-6394
http://cordova.apache.org
ファイルシステムの一覧 ( 外部サイト)
有効
ファイルの保存場所
プラグインの設定
ファイルシステムへのアクセス
ファイルの保存
ファイル
ディレクトリー
ファイルへの書き込み
ファイルの読み込み
ファイルへの追記
画像ファイルの表示