メインコンテンツへスキップ
バージョン: v8

@capacitor/filesystem

ファイルシステムAPIは、デバイス上のファイル操作のためのNodeJSに似たAPIを提供します。

インストール​

npm install @capacitor/filesystem
npx cap sync

Appleプライバシーマニフェスト要件​

Appleは、ユーザーのプライバシーを強化するために、アプリ開発者がAPIの使用理由を指定することを義務付けています。2024年5月1日までに、App Store Connectにアプリを提出する際にこれらの理由を含めることが必要になります。

アプリでこの特定のプラグインを使用する場合は、/ios/AppにPrivacyInfo.xcprivacyファイルを作成するか、VS Code拡張機能を使用してそれを生成し、使用理由を指定する必要があります。

これを行う方法の詳細については、Capacitorドキュメントを参照してください。

このプラグインの場合、必要なディクショナリーキーはNSPrivacyAccessedAPICategoryFileTimestampであり、推奨される理由はC617.1です。

PrivacyInfo.xcprivacyの例​

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>C617.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

iOS​

ファイルを「ファイル」アプリに表示させるには、Info.plistで次のキーをYESに設定する必要があります。

  • UIFileSharingEnabled（Application supports iTunes file sharing）
  • LSSupportsOpeningDocumentsInPlace（Supports opening documents in place）

ヘルプについては、iOSの設定を参照してください。

Android​

Directory.DocumentsまたはDirectory.ExternalStorageを使用する場合、Android 10以前では、このAPIには、AndroidManifest.xmlに次の権限を追加する必要があります。

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Android権限の設定の詳細については、権限の設定とAndroidガイドを参照してください。

Directory.ExternalStorageはAndroid 9以前でのみ使用可能であり、Directory.DocumentsはAndroid 11以降ではアプリによって作成されたファイル/フォルダへのアクセスのみを許可することに注意してください。

大きなファイルの処理には、AndroidManifest.xmlの<application>タグにandroid:largeHeap="true"を追加する必要がある場合があります。

ディレクトリとファイルの理解​

iOSとAndroidには、クラウドにバックアップされる特別なディレクトリや、ドキュメントの保存用のディレクトリなど、ファイル間の追加の分離レイヤーがあります。ファイルシステムAPIは、デバイス上の特定の特別なディレクトリに各操作をスコープするための簡単な方法を提供します。

さらに、ファイルシステムAPIは完全なfile://パスを使用するか、Androidでcontent://ファイルを読み取ることをサポートしています。完全なファイルパスを使用するには、directoryパラメーターを省略するだけです。

例​

import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';

const writeSecretFile = async () => {
  await Filesystem.writeFile({
    path: 'secrets/text.txt',
    data: 'This is a test',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });
};

const readSecretFile = async () => {
  const contents = await Filesystem.readFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });

  console.log('secrets:', contents);
};

const deleteSecretFile = async () => {
  await Filesystem.deleteFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
  });
};

const readFilePath = async () => {
  // Here's an example of reading a file with a full file path. Use this to
  // read binary data (base64 encoded) from plugins that return File URIs, such as
  // the Camera.
  const contents = await Filesystem.readFile({
    path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Documents/text.txt',
  });

  console.log('data:', contents);
};

API​

readFile(...)​

readFile(options: ReadFileOptions) => Promise<ReadFileResult>

ディスクからファイルを読み取ります。

パラメータ型
optionsReadFileOptions

戻り値: Promise<ReadFileResult>

以降 1.0.0

writeFile(...)​

writeFile(options: WriteFileOptions) => Promise<WriteFileResult>

デバイスの指定された場所にファイルを書き込みます。

パラメータ型
optionsWriteFileOptions

戻り値: Promise<WriteFileResult>

以降 1.0.0

appendFile(...)​

appendFile(options: AppendFileOptions) => Promise<void>

デバイスの指定された場所にファイルに追加します。

パラメータ型
optionsAppendFileOptions

以降 1.0.0

deleteFile(...)​

deleteFile(options: DeleteFileOptions) => Promise<void>

ディスクからファイル削除します。

パラメータ型
optionsDeleteFileOptions

以降 1.0.0

mkdir(...)​

mkdir(options: MkdirOptions) => Promise<void>

ディレクトリを作成します。

パラメータ型
optionsMkdirOptions

以降 1.0.0

rmdir(...)​

rmdir(options: RmdirOptions) => Promise<void>

ディレクトリを削除します。

パラメータ型
optionsRmdirOptions

以降 1.0.0

readdir(...)​

readdir(options: ReaddirOptions) => Promise<ReaddirResult>

ディレクトリからファイルのリストを返します（再帰的ではありません）。

パラメータ型
optionsReaddirOptions

戻り値: Promise<ReaddirResult>

以降 1.0.0

getUri(...)​

getUri(options: GetUriOptions) => Promise<GetUriResult>

パスとディレクトリの完全なファイルURIを返します。

パラメータ型
optionsGetUriOptions

戻り値: Promise<GetUriResult>

以降 1.0.0

stat(...)​

stat(options: StatOptions) => Promise<StatResult>

ファイルに関するデータを返します。

パラメータ型
optionsStatOptions

戻り値: Promise<StatResult>

以降 1.0.0

rename(...)​

rename(options: RenameOptions) => Promise<void>

ファイルまたはディレクトリの名前を変更します。

パラメータ型
optionsCopyOptions

以降 1.0.0

copy(...)​

copy(options: CopyOptions) => Promise<CopyResult>

ファイルまたはディレクトリをコピーします。

パラメータ型
optionsCopyOptions

戻り値: Promise<CopyResult>

以降 1.0.0

checkPermissions()​

checkPermissions() => Promise<PermissionStatus>

読み取り/書き込み権限を確認します。Androidでは、Directory.DocumentsまたはDirectory.ExternalStorageを使用する場合にのみ必要です。

戻り値: Promise<PermissionStatus>

以降 1.0.0

requestPermissions()​

requestPermissions() => Promise<PermissionStatus>

読み取り/書き込み権限を要求します。Androidでは、Directory.DocumentsまたはDirectory.ExternalStorageを使用する場合にのみ必要です。

戻り値: Promise<PermissionStatus>

以降 1.0.0

downloadFile(...)​

downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>

サーバーへのhttpリクエストを実行し、ファイルを指定された場所にダウンロードします。

パラメータ型
optionsDownloadFileOptions

戻り値: Promise<DownloadFileResult>

以降 5.1.0

addListener('progress', ...)​

addListener(eventName: 'progress', listenerFunc: ProgressListener) => Promise<PluginListenerHandle>

ファイルダウンロードの進捗イベントのリスナーを追加します。

パラメータ型
eventName'progress'
listenerFuncProgressListener

戻り値: Promise<PluginListenerHandle>

以降 5.1.0

removeAllListeners()​

removeAllListeners() => Promise<void>

このプラグインのすべてのリスナーを削除します。

以降 5.2.0

インターフェース​

ReadFileResult​

プロパティ型説明以降
datastring | Blobファイルに含まれるデータの表現 注：BlobはWebでのみ使用可能です。ネイティブでは、データは文字列として返されます。1.0.0

ReadFileOptions​

プロパティ型説明以降
pathstring読み取るファイルのパス1.0.0
directoryDirectoryファイルを読み取るDirectory1.0.0
encodingEncodingファイルを読み取るエンコーディング。指定しない場合、データはバイナリとして読み取られ、base64でエンコードされて返されます。Encoding.UTF8を渡して、データを文字列として読み取ります。1.0.0

WriteFileResult​

プロパティ型説明以降
uristringファイルが書き込まれたURI1.0.0

WriteFileOptions​

プロパティ型説明デフォルト以降
pathstring書き込むファイルのパス1.0.0
datastring | Blob書き込むデータ 注：BlobデータはWebでのみサポートされています。1.0.0
directoryDirectoryファイルを保存するDirectory1.0.0
encodingEncodingファイルを書き込むエンコーディング。指定しない場合、データはbase64でエンコードされて書き込まれます。Encoding.UTF8を渡して、データを文字列として書き込みます。1.0.0
recursiveboolean欠落している親ディレクトリを作成するかどうか。false1.0.0

AppendFileOptions​

プロパティ型説明以降
pathstring追加するファイルのパス1.0.0
datastring書き込むデータ1.0.0
directoryDirectoryファイルを保存するDirectory1.0.0
encodingEncodingファイルを書き込むエンコーディング。指定しない場合、データはbase64でエンコードされて書き込まれます。Encoding.UTF8を渡して、データを文字列として書き込みます。1.0.0

DeleteFileOptions​

プロパティ型説明以降
pathstring削除するファイルのパス1.0.0
directoryDirectoryファイルから削除するDirectory1.0.0

MkdirOptions​

プロパティ型説明デフォルト以降
pathstring新しいディレクトリのパス1.0.0
directoryDirectory新しいディレクトリを作成するDirectory1.0.0
recursiveboolean親ディレクトリが存在しない場合にも作成するかどうか。false1.0.0

RmdirOptions​

プロパティ型説明デフォルト以降
pathstring削除するディレクトリのパス1.0.0
directoryDirectoryディレクトリを削除するDirectory1.0.0
recursivebooleanディレクトリの内容を再帰的に削除するかどうかfalse1.0.0

ReaddirResult​

プロパティ型説明以降
ファイルFileInfo[]ディレクトリ内のファイルとディレクトリのリスト1.0.0

FileInfo​

プロパティ型説明以降
名前stringファイルまたはディレクトリの名前。
種類'file' | 'directory'ファイルの種類。4.0.0
サイズ数値ファイルのサイズ（バイト単位）。4.0.0
作成時刻数値作成時刻（ミリ秒）。Android 7以前のデバイスでは利用できません。4.0.0
最終変更時刻数値最終変更時刻（ミリ秒）。4.0.0
uristringファイルのURI。4.0.0

ReaddirOptions​

プロパティ型説明以降
pathstring読み取るディレクトリのパス1.0.0
directoryDirectoryファイル一覧を取得するDirectory1.0.0

GetUriResult​

プロパティ型説明以降
uristringファイルのURI1.0.0

GetUriOptions​

プロパティ型説明以降
pathstringURIを取得するファイルのパス1.0.0
directoryDirectoryファイルが存在するDirectory1.0.0

StatResult​

プロパティ型説明以降
種類'file' | 'directory'ファイルの種類。1.0.0
サイズ数値ファイルのサイズ（バイト単位）。1.0.0
作成時刻数値作成時刻（ミリ秒）。Android 7以前のデバイスでは利用できません。1.0.0
最終変更時刻数値最終変更時刻（ミリ秒）。1.0.0
uristringファイルのURI1.0.0

StatOptions​

プロパティ型説明以降
pathstringデータを取得するファイルのパス1.0.0
directoryDirectoryファイルが存在するDirectory1.0.0

CopyOptions​

プロパティ型説明以降
ソースstring既存のファイルまたはディレクトリ1.0.0
宛先string宛先のファイルまたはディレクトリ1.0.0
directoryDirectory既存のファイルまたはディレクトリを含むDirectory1.0.0
宛先ディレクトリDirectory宛先のファイルまたはディレクトリを含むDirectory。指定しない場合、'directory'パラメータを宛先として使用します。1.0.0

CopyResult​

プロパティ型説明以降
uristringファイルがコピーされたURI4.0.0

PermissionStatus​

プロパティ型
公開ストレージパーミッション状態

DownloadFileResult​

プロパティ型説明以降
pathstringファイルがダウンロードされたパス。5.1.0
blobBlobダウンロードされたファイルのblobデータ。これはWebでのみ利用可能です。5.1.0

DownloadFileOptions​

プロパティ型説明デフォルト以降
pathstringダウンロードされたファイルを移動するパス。5.1.0
directoryDirectoryファイルを書き込むディレクトリ。このオプションを使用する場合、filePathは絶対パスではなく相対パスにすることができます。デフォルトはDATAディレクトリです。5.1.0
進捗状況booleanダウンロードの進捗状況イベントを受信するオプションのリスナー関数。このオプションを使用する場合は、受信した各チャンクに対して進捗イベントをディスパッチする必要があります。Android/iOSでは、速度低下を防ぐために、チャンクは100msごとに調整されます。5.1.0
recursiveboolean欠落している親ディレクトリを作成するかどうか。false5.1.2

PluginListenerHandle​

プロパティ型
削除() => Promise<void>

ProgressStatus​

プロパティ型説明以降
URLstringダウンロード中のファイルのURL。5.1.0
バイト数数値これまでダウンロードされたバイト数。5.1.0
コンテンツの長さ数値このファイルのダウンロードする総バイト数。5.1.0

型エイリアス​

RenameOptions​

CopyOptions

PermissionState​

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

ProgressListener​

進捗状況イベントを受信するリスナー関数。

(progress: ProgressStatus): void

列挙型​

Directory​

メンバ値説明以降
ドキュメント'DOCUMENTS'ドキュメントディレクトリ。iOSではアプリのドキュメントディレクトリです。ユーザー生成コンテンツの保存に使用します。Androidではパブリックドキュメントフォルダなので、他のアプリからもアクセスできます。Android 10では、アプリが `AndroidManifest.xml` の `application` タグに `android:requestLegacyExternalStorage="true"` を追加してレガシー外部ストレージを有効にしない限りアクセスできません。Android 11以降では、アプリはアプリが作成したファイル/フォルダのみにアクセスできます。1.0.0
データ'DATA'データディレクトリ。iOSではドキュメントディレクトリを使用します。Androidではアプリケーションファイルを保持するディレクトリです。アプリケーションがアンインストールされると、ファイルは削除されます。1.0.0
ライブラリ'LIBRARY'ライブラリディレクトリ。iOSではライブラリディレクトリを使用します。Androidではアプリケーションファイルを保持するディレクトリです。アプリケーションがアンインストールされると、ファイルは削除されます。1.1.0
キャッシュ'CACHE'キャッシュディレクトリ。メモリが少ない場合に削除される可能性があるため、アプリ固有のファイルを簡単に再作成できるファイルを書き込むためにこのディレクトリを使用します。1.0.0
外部'EXTERNAL'外部ディレクトリ。iOSではドキュメントディレクトリを使用します。Androidでは、アプリケーションが独自の永続的なファイルを配置できるプライマリ共有/外部ストレージデバイス上のディレクトリです。これらのファイルはアプリケーション内部のものであり、通常、ユーザーにはメディアとして表示されません。アプリケーションがアンインストールされると、ファイルは削除されます。1.0.0
外部ストレージ'EXTERNAL_STORAGE'外部ストレージディレクトリ。iOSではドキュメントディレクトリを使用します。Androidではプライマリ共有/外部ストレージディレクトリです。Android 10では、アプリが `AndroidManifest.xml` の `application` タグに `android:requestLegacyExternalStorage="true"` を追加してレガシー外部ストレージを有効にしない限りアクセスできません。Android 11以降ではアクセスできません。1.0.0

エンコーディング​

メンバ値説明以降
UTF8'utf8'8ビットUCS変換形式1.0.0
ASCII'ascii'7ビットASCII、別名ISO646-US、別名Unicode文字セットの基本ラテンブロック。このエンコーディングはAndroidでのみサポートされています。1.0.0
UTF16'utf16'16ビットUCS変換形式。バイトオーダーはオプションのバイトオーダーマークによって識別されます。このエンコーディングはAndroidでのみサポートされています。1.0.0

目次

このページを編集