Démarrage

1. Installer le package

   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. Synchroniser avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Utilisation

Importez le plugin et utilisez ses méthodes pour les opérations sur les fichiers :

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,
  });
};

Emplacements de répertoires

Le plugin fournit plusieurs constantes de répertoires :

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

Options d’encodage

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)

Référence API

writeFile(options)

Écrire des données dans un fichier.

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)

Lire le contenu d’un fichier.

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)

Ajouter des données à un fichier.

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

deleteFile(options)

Supprimer un fichier.

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

mkdir(options)

Créer un répertoire.

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

rmdir(options)

Supprimer un répertoire.

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

readdir(options)

Lister le contenu d’un répertoire.

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)

Obtenir les métadonnées d’un fichier ou d’un répertoire.

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

exists(options)

Vérifier si un fichier ou un répertoire existe.

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

copy(options)

Copier un fichier ou un répertoire.

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

rename(options) / move(options)

Renommer ou déplacer un fichier ou un répertoire.

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

truncate(options)

Tronquer un fichier à une taille spécifique.

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

getUri(options)

Obtenir l’URI natif pour un fichier.

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

getDirectories()

Obtenir tous les chemins de répertoires disponibles.

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

getFreeDiskSpace()

Obtenir l’espace disque disponible.

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

checkPermissions() / requestPermissions()

Gérer les permissions de stockage (Android).

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

Exemple complet

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;
  }
}

Notes de plateforme

iOS

• Nécessite iOS 13.0+
• Le répertoire Documents est visible dans l’application Fichiers
• Le répertoire Library est pour les fichiers de support de l’application
• Le cache peut être effacé lorsque le stockage de l’appareil est faible

Android

• Nécessite Android 6.0 (API 23)+
• Le stockage externe nécessite des permissions d’exécution sur les anciennes versions d’Android
• Le répertoire Documents correspond au répertoire des fichiers de l’application
• Utilisez le répertoire External pour l’accès au stockage partagé

Web

• Non pris en charge sur la plateforme web