跳至主要內容
版本：v8

@capacitor/filesystem

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（應用程式支援 iTunes 檔案共享）
  • LSSupportsOpeningDocumentsInPlace（支援原地開啟文件）

請參閱 設定 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 及更新版本上存取您的應用程式建立的檔案/資料夾。

處理大型檔案可能需要您將 android:largeHeap="true" 新增到 AndroidManifest.xml 中的 <application> 標籤。

了解目錄和檔案​

iOS 和 Android 在檔案之間有額外的隔離層，例如備份到雲端的特殊目錄，或用於儲存文件的目錄。Filesystem API 提供了一種簡單的方法，可將每個操作的範圍設定為裝置上的特定特殊目錄。

此外，Filesystem 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​

屬性類型描述自
filesFileInfo[]目錄內檔案和目錄的列表1.0.0

FileInfo​

屬性類型描述自
namestring檔案或目錄的名稱。
type'file' | 'directory'檔案的類型。4.0.0
sizenumber檔案的大小（以位元組為單位）。4.0.0
ctimenumber建立時間（以毫秒為單位）。在 Android 7 及更舊的裝置上不可用。4.0.0
mtimenumber上次修改時間（以毫秒為單位）。4.0.0
uristring檔案的 URI。4.0.0

ReaddirOptions​

屬性類型描述自
pathstring要讀取的目錄路徑1.0.0
directoryDirectory要列出檔案的 Directory1.0.0

GetUriResult​

屬性類型描述自
uristring檔案的 URI1.0.0

GetUriOptions​

屬性類型描述自
pathstring要取得 URI 的檔案路徑1.0.0
directoryDirectory檔案所在的 Directory1.0.0

StatResult​

屬性類型描述自
type'file' | 'directory'檔案的類型。1.0.0
sizenumber檔案的大小（以位元組為單位）。1.0.0
ctimenumber建立時間（以毫秒為單位）。在 Android 7 及更舊的裝置上不可用。1.0.0
mtimenumber上次修改時間（以毫秒為單位）。1.0.0
uristring檔案的 URI1.0.0

StatOptions​

屬性類型描述自
pathstring要取得資料的檔案路徑1.0.0
directoryDirectory檔案所在的 Directory1.0.0

CopyOptions​

屬性類型描述自
fromstring現有的檔案或目錄1.0.0
tostring目標檔案或目錄1.0.0
directoryDirectory包含現有檔案或目錄的 Directory1.0.0
toDirectoryDirectory包含目標檔案或目錄的 Directory。如果未提供，則會使用 'directory' 參數作為目標1.0.0

CopyResult​

屬性類型描述自
uristring檔案複製到的 URI4.0.0

PermissionStatus​

屬性類型
publicStoragePermissionState

DownloadFileResult​

屬性類型描述自
pathstring檔案下載到的路徑。5.1.0
blobBlob下載檔案的 blob 資料。這僅適用於網頁。5.1.0

DownloadFileOptions​

屬性類型描述預設自
pathstring下載的檔案應移動到的路徑。5.1.0
directoryDirectory要將檔案寫入的目錄。如果使用此選項，filePath 可以是相對路徑而不是絕對路徑。預設值為 DATA 目錄。5.1.0
progressboolean用於接收下載進度事件的可選監聽器函式。如果使用此選項，則應在接收到每個區塊時分派進度事件。為了避免速度變慢，在 Android/iOS 上會將區塊限制為每 100 毫秒一次。5.1.0
recursiveboolean是否建立任何遺失的父目錄。false5.1.2

PluginListenerHandle​

屬性類型
remove() => Promise<void>

ProgressStatus​

屬性類型描述自
urlstring正在下載的檔案的 URL。5.1.0
bytesnumber目前已下載的位元組數。5.1.0
contentLengthnumber此檔案要下載的總位元組數。5.1.0

類型別名​

RenameOptions​

CopyOptions

PermissionState​

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

ProgressListener​

接收進度事件的監聽器函式。

(progress: ProgressStatus): void

列舉​

Directory​

成員值描述自
Documents'DOCUMENTS'Documents 目錄。在 iOS 上，它是應用程式的 documents 目錄。使用此目錄來儲存使用者產生的內容。在 Android 上，它是 Public Documents 資料夾，因此可以從其他應用程式存取。除非應用程式透過在 AndroidManifest.xml 的 application 標籤中新增 android:requestLegacyExternalStorage="true" 來啟用舊版外部儲存空間，否則在 Android 10 上無法存取。在 Android 11 或更新版本上，應用程式只能存取應用程式建立的檔案/資料夾。1.0.0
Data'DATA'Data 目錄。在 iOS 上，它將使用 Documents 目錄。在 Android 上，它是保存應用程式檔案的目錄。當應用程式解除安裝時，檔案將會被刪除。1.0.0
Library'LIBRARY'Library 目錄。在 iOS 上，它將使用 Library 目錄。在 Android 上，它是保存應用程式檔案的目錄。當應用程式解除安裝時，檔案將會被刪除。1.1.0
Cache'CACHE'Cache 目錄。可能會在記憶體不足的情況下被刪除，因此請使用此目錄來寫入應用程式專用的檔案。您的應用程式可以輕鬆地重新建立這些檔案。1.0.0
External'EXTERNAL'外部目錄。在 iOS 上，它將使用 Documents 目錄。在 Android 上，它是主要共用/外部儲存裝置上應用程式可以放置其擁有的永久性檔案的目錄。這些檔案是應用程式內部的，通常不會以媒體形式向使用者顯示。當應用程式解除安裝時，檔案將會被刪除。1.0.0
ExternalStorage'EXTERNAL_STORAGE'外部儲存空間目錄。在 iOS 上，它將使用 Documents 目錄。在 Android 上，它是主要共用/外部儲存目錄。除非應用程式透過在 AndroidManifest.xml 的 application 標籤中新增 android:requestLegacyExternalStorage="true" 來啟用舊版外部儲存空間，否則在 Android 10 上無法存取。在 Android 11 或更新版本上無法存取。1.0.0

Encoding​

成員值描述自
UTF8'utf8'八位元 UCS 轉換格式1.0.0
ASCII'ascii'七位元 ASCII，又名 ISO646-US，又名 Unicode 字元集的基本拉丁區塊。此編碼僅在 Android 上支援。1.0.0
UTF16'utf16'十六位元 UCS 轉換格式，位元組順序由可選的位元組順序標記識別。此編碼僅在 Android 上支援。1.0.0

目錄

編輯此頁面