Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-file` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

npm install @capgo/capacitor-file
npx cap sync

Importieren

import { CapacitorFile } from '@capgo/capacitor-file';

Quickstart

import { CapacitorFile, FileSystemType } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestFileSystem({ type: FileSystemType.TEMPORARY });
console.log(result);

Beispiel: resolveLocalFileSystemURL

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.resolveLocalFileSystemURL({
  url: 'file:///data/user/0/com.example.app/files/report.pdf',
});
console.log(result);

Beispiel: getFile

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFile({ path: 'path/to/file' });
console.log(result);

Häufige Stolperfallen

• Berechtigungen: aufrufen checkPermissions() dann requestPermissions() bei Bedarf.
• Listener: Handles beim Unmounten von Screens entfernen.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

API Übersicht

requestFileSystem

Ein Dateisystem anfordern.

import { CapacitorFile, FileSystemType } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestFileSystem({ type: FileSystemType.TEMPORARY });
console.log(result);

resolveLocalFileSystemURL

Eine Datei-URL in einen Entry auflösen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.resolveLocalFileSystemURL({ url: 'https://example.com' });
console.log(result);

getFile

Einen Datei-Entry abrufen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFile({ path: 'path/to/file' });
console.log(result);

getDirectory

Einen Directory-Eintrag abrufen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getDirectory({ path: 'path/to/file' });
console.log(result);

readFile

Eine Datei als Text oder Base64 lesen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readFile({ path: 'path/to/file' });
console.log(result);

readAsDataURL

Eine Datei als Data URL lesen (Base64 mit MIME-Typ-Präfix).

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readAsDataURL({ path: 'path/to/file' });
console.log(result);

writeFile

Daten in eine Datei schreiben.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.writeFile({
  path: 'path/to/file',
  data: 'data',
});
console.log(result);

appendFile

Daten an eine Datei anhängen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.appendFile({
  path: 'path/to/file',
  data: 'data',
});
console.log(result);

deleteFile

Eine Datei löschen.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.deleteFile({ path: 'path/to/file' });

mkdir

Ein Verzeichnis erstellen.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.mkdir({ path: 'path/to/file' });

rmdir

Ein Verzeichnis löschen.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.rmdir({ path: 'path/to/file' });

readdir

Verzeichnisinhalt lesen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.readdir({ path: 'path/to/file' });
console.log(result);

stat

Metadaten einer Datei oder eines Verzeichnisses abrufen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.stat({ path: 'path/to/file' });
console.log(result);

getMetadata

Metadaten zu einer Datei oder einem Verzeichnis abrufen. Alias für stat().

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getMetadata({ path: 'path/to/file' });
console.log(result);

rename

Rename or move a file or directory.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.rename({
  from: 'from',
  to: 'to',
});

move

Verschiebt eine Datei oder ein Verzeichnis. Alias für rename().

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.move({
  from: 'from',
  to: 'to',
});

copy

Datei oder Verzeichnis kopieren.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.copy({
  from: 'from',
  to: 'to',
});
console.log(result);

exists

Prüfen, ob eine Datei oder ein Verzeichnis existiert.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.exists({ path: 'path/to/file' });
console.log(result);

getUri

Die URI einer Datei abrufen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getUri({ path: 'path/to/file' });
console.log(result);

truncate

Eine Datei auf eine bestimmte Größe kürzen.

import { CapacitorFile } from '@capgo/capacitor-file';

await CapacitorFile.truncate({ path: 'path/to/file' });

getDirectories

Alle bekannten Verzeichnisse des Dateisystems abrufen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getDirectories();
console.log(result);

getFreeDiskSpace

Den freien Speicherplatz in Bytes abrufen.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.getFreeDiskSpace();
console.log(result);

checkPermissions

Den aktuellen Berechtigungsstatus für Dateioperaionen prüfen. Auf Android wird dies für die Berechtigungen des externen Speichers geprüft. Auf iOS und im Web wird immer „granted“ zurückgegeben, da keine speziellen Berechtigungen erforderlich sind.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.checkPermissions();
console.log(result);

requestPermissions

Berechtigungen für Dateizugriffe anfordern. Unter Android werden hiermit die Berechtigungen für den externen Speicher angefordert, um auf Dateien außerhalb der privaten App-Verzeichnisse zuzugreifen. Unter iOS und im Web wird immer „granted“ zurückgegeben, da keine speziellen Berechtigungen erforderlich sind.

import { CapacitorFile } from '@capgo/capacitor-file';

const result = await CapacitorFile.requestPermissions();
console.log(result);

Typreferenz

RequestFileSystemOptions

Optionen zum Anfordern eines Dateisystems.

export interface RequestFileSystemOptions {
  /** The type of file system to request */
  type: FileSystemType;
  /** Requested size in bytes (may not be enforced on all platforms) */
  size?: number;
}

FileSystem

Repräsentiert ein Dateisystem.

export interface FileSystem {
  /** The name of the file system */
  name: string;
  /** The root directory of the file system */
  root: DirectoryEntry;
}

ResolveURLOptions

Optionen zum Auflösen einer URL in einen Eintrag.

export interface ResolveURLOptions {
  /** The URL to resolve (file:// or cdvfile://) */
  url: string;
}

Entry

Repräsentiert einen Datei- oder Verzeichniseintrag.

export interface Entry {
  /** True if this is a file */
  isFile: boolean;
  /** True if this is a directory */
  isDirectory: boolean;
  /** The name of the file or directory */
  name: string;
  /** The full path relative to the filesystem root */
  fullPath: string;
  /** The native file:// URI */
  nativeURL: string;
}

GetFileOptions

Optionen zum Abrufen einer Datei.

export interface GetFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the file */
  options?: GetOptions;
}

FileEntry

Repräsentiert einen Dateieintrag.

export interface FileEntry extends Entry {
  isFile: true;
  isDirectory: false;
}

GetDirectoryOptions

Optionen zum Abrufen eines Verzeichnisses.

export interface GetDirectoryOptions {
  /** Path to the directory */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the directory */
  options?: GetOptions;
}

DirectoryEntry

Stellt einen Verzeichniseintrag dar.

export interface DirectoryEntry extends Entry {
  isFile: false;
  isDirectory: true;
}

ReadFileOptions

Optionen zum Lesen einer Datei.

export interface ReadFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Encoding for text files (omit for binary/base64) */
  encoding?: Encoding;
  /** Byte offset to start reading from (default: 0) */
  offset?: number;
  /** Number of bytes to read (default: read to end of file) */
  length?: number;
}

ReadFileResult

Ergebnis des Lesens einer Datei.

export interface ReadFileResult {
  /** File contents as string (text) or base64 (binary) */
  data: string;
}

WriteFileOptions

Optionen zum Schreiben einer Datei.

export interface WriteFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Data to write (string for text, base64 for binary) */
  data: string;
  /** Encoding for text files */
  encoding?: Encoding;
  /** If true, append to existing file instead of overwriting */
  append?: boolean;
  /** Create intermediate directories if they don't exist */
  recursive?: boolean;
  /** Byte position to start writing at (for random access writes). If not specified, writes from beginning or appends based on 'append' flag */
  position?: number;
}

WriteFileResult

Ergebnis des Schreibvorgangs einer Datei.

export interface WriteFileResult {
  /** The URI of the written file */
  uri: string;
}

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Speicher- und Dateiverwaltung zu planen, verbinde es mit @capgo/capacitor-file verwenden für die native Funktionalität bei der Nutzung von @capgo/capacitor-file, @capgo/capacitor-data-storage-sqlite für die Implementierungsdetails in @capgo/capacitor-data-storage-sqlite, Mit @capgo/capacitor-data-storage-sqlite für die native Funktionalität in „@capgo/capacitor-data-storage-sqlite verwenden“, @capgo/capacitor-file für das Implementierungsdetail in @capgo/capacitor-file und @capgo/capacitor-uploader für das Implementierungsdetail in @capgo/capacitor-uploader.