Iniziare

1. Installa il pacchetto

   npm

   npm i @capgo/capacitor-file

   pnpm

   pnpm add @capgo/capacitor-file

   yarn

   yarn add @capgo/capacitor-file

   bun

   bun add @capgo/capacitor-file

2. Sincronizza con i progetti nativi

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Utilizzo

Importa il plugin e usa i suoi metodi per operazioni sui file:

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

// Write a text file
const writeFile = async () => {
  const result = await CapacitorFile.writeFile({
    path: 'my-file.txt',
    directory: Directory.Documents,
    data: 'Hello, World!',
    encoding: Encoding.UTF8,
    recursive: true, // Create parent directories if needed
  });
  console.log('File written to:', result.uri);
};

// Read a text file
const readFile = async () => {
  const result = await CapacitorFile.readFile({
    path: 'my-file.txt',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });
  console.log('File contents:', result.data);
};

// Check if file exists
const checkExists = async () => {
  const result = await CapacitorFile.exists({
    path: 'my-file.txt',
    directory: Directory.Documents,
  });
  console.log('File exists:', result.exists);
};

// Delete a file
const deleteFile = async () => {
  await CapacitorFile.deleteFile({
    path: 'my-file.txt',
    directory: Directory.Documents,
  });
};

Posizioni Directory

Il plugin fornisce diverse costanti di directory:

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

// Available directories
Directory.Documents  // User-visible documents (backed up)
Directory.Data       // Private app data storage
Directory.Library    // App support files (iOS) / files (Android)
Directory.Cache      // Temporary cache (may be cleared by OS)
Directory.External   // External storage (Android only)
Directory.Application // Read-only app bundle

Opzioni di Codifica

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

Encoding.UTF8   // UTF-8 text encoding
Encoding.ASCII  // ASCII text encoding
Encoding.UTF16  // UTF-16 text encoding
// Omit encoding for binary data (returns base64)

Riferimento API

writeFile(options)

Scrivi dati in un file.

const result = await CapacitorFile.writeFile({
  path: 'folder/file.txt',
  directory: Directory.Documents,
  data: 'File content',
  encoding: Encoding.UTF8,
  recursive: true,  // Create directories if needed
  append: false,    // Overwrite existing file
  position: 0,      // Byte position for random access writes
});
// Returns: { uri: string }

readFile(options)

Leggi il contenuto di un file.

const result = await CapacitorFile.readFile({
  path: 'file.txt',
  directory: Directory.Documents,
  encoding: Encoding.UTF8,
  offset: 0,    // Start reading from byte offset
  length: 100,  // Read only this many bytes
});
// Returns: { data: string }

appendFile(options)

Aggiungi dati a un file.

await CapacitorFile.appendFile({
  path: 'file.txt',
  directory: Directory.Documents,
  data: '\nNew line',
  encoding: Encoding.UTF8,
});

deleteFile(options)

Elimina un file.

await CapacitorFile.deleteFile({
  path: 'file.txt',
  directory: Directory.Documents,
});

mkdir(options)

Crea una directory.

await CapacitorFile.mkdir({
  path: 'my-folder/sub-folder',
  directory: Directory.Documents,
  recursive: true,  // Create parent directories
});

rmdir(options)

Elimina una directory.

await CapacitorFile.rmdir({
  path: 'my-folder',
  directory: Directory.Documents,
  recursive: true,  // Delete contents recursively
});

readdir(options)

Elenca il contenuto di una directory.

const result = await CapacitorFile.readdir({
  path: '',  // Empty for root of directory
  directory: Directory.Documents,
});
// Returns: { entries: Entry[] }
// Each entry has: { name, isFile, isDirectory, fullPath, nativeURL }

stat(options)

Ottieni i metadati di un file o directory.

const result = await CapacitorFile.stat({
  path: 'file.txt',
  directory: Directory.Documents,
});
// Returns: { type, size, mtime, ctime, uri }

exists(options)

Controlla se un file o directory esiste.

const result = await CapacitorFile.exists({
  path: 'file.txt',
  directory: Directory.Documents,
});
// Returns: { exists: boolean, type?: 'file' | 'directory' }

copy(options)

Copia un file o directory.

const result = await CapacitorFile.copy({
  from: 'source.txt',
  to: 'destination.txt',
  directory: Directory.Documents,
  toDirectory: Directory.Documents,
});
// Returns: { uri: string }

rename(options) / move(options)

Rinomina o sposta un file o directory.

await CapacitorFile.rename({
  from: 'old-name.txt',
  to: 'new-name.txt',
  directory: Directory.Documents,
  toDirectory: Directory.Documents,
});

truncate(options)

Tronca un file a una dimensione specifica.

await CapacitorFile.truncate({
  path: 'file.txt',
  directory: Directory.Documents,
  size: 100,  // Truncate to 100 bytes
});

getUri(options)

Ottieni l’URI nativo per un file.

const result = await CapacitorFile.getUri({
  path: 'file.txt',
  directory: Directory.Documents,
});
// Returns: { uri: string }

getDirectories()

Ottieni tutti i percorsi delle directory disponibili.

const dirs = await CapacitorFile.getDirectories();
// Returns paths for: documents, data, cache, external, etc.

getFreeDiskSpace()

Ottieni lo spazio su disco disponibile.

const result = await CapacitorFile.getFreeDiskSpace();
console.log('Free space:', result.free, 'bytes');

checkPermissions() / requestPermissions()

Gestisci i permessi di archiviazione (Android).

const status = await CapacitorFile.checkPermissions();
if (status.publicStorage !== 'granted') {
  await CapacitorFile.requestPermissions();
}

Esempio Completo

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

export class FileService {
  async saveJson(filename: string, data: object): Promise<void> {
    await CapacitorFile.writeFile({
      path: filename,
      directory: Directory.Documents,
      data: JSON.stringify(data, null, 2),
      encoding: Encoding.UTF8,
      recursive: true,
    });
  }

  async loadJson<T>(filename: string): Promise<T | null> {
    try {
      const { exists } = await CapacitorFile.exists({
        path: filename,
        directory: Directory.Documents,
      });

      if (!exists) return null;

      const result = await CapacitorFile.readFile({
        path: filename,
        directory: Directory.Documents,
        encoding: Encoding.UTF8,
      });

      return JSON.parse(result.data) as T;
    } catch (error) {
      console.error('Failed to load JSON:', error);
      return null;
    }
  }

  async listFiles(folder: string = ''): Promise<string[]> {
    const result = await CapacitorFile.readdir({
      path: folder,
      directory: Directory.Documents,
    });

    return result.entries
      .filter(entry => entry.isFile)
      .map(entry => entry.name);
  }

  async deleteAll(folder: string): Promise<void> {
    const { exists } = await CapacitorFile.exists({
      path: folder,
      directory: Directory.Documents,
    });

    if (exists) {
      await CapacitorFile.rmdir({
        path: folder,
        directory: Directory.Documents,
        recursive: true,
      });
    }
  }

  async copyToBackup(filename: string): Promise<string> {
    const timestamp = Date.now();
    const backupName = `backup/${timestamp}-${filename}`;

    const result = await CapacitorFile.copy({
      from: filename,
      to: backupName,
      directory: Directory.Documents,
      toDirectory: Directory.Documents,
    });

    return result.uri;
  }
}

Note sulla Piattaforma

iOS

• Richiede iOS 13.0+
• La directory Documents è visibile nell’app Files
• La directory Library è per i file di supporto dell’app
• La cache può essere cancellata quando lo spazio di archiviazione del dispositivo è basso

Android

• Richiede Android 6.0 (API 23)+
• L’archiviazione esterna richiede permessi di runtime sulle versioni Android più vecchie
• La directory Documents mappa alla directory files dell’app
• Usa la directory External per l’accesso all’archiviazione condivisa

Web

• Non supportato sulla piattaforma web