Native Folder Access

1Cosa fa questa funzione#

Questa funzione dГ alla tua web app un accesso controllato a una sola cartella Android scelta dall'utente tramite lo Storage Access Framework (SAF). Funziona bene per app HTML offline, editor, flussi di backup/ripristino e strumenti di importazione/esportazione.

NON dГ accesso illimitato alla memoria del dispositivo. L'utente sceglie esplicitamente una cartella e la tua app puГІ lavorare solo all'interno di quell'albero concesso.

2Attivalo nel generatore#

Nel Passaggio 4 del generatore, attiva 'Native Folder Access (SAF)'. Poi genera l'app.

Quando ГЁ attiva, il tuo sito ottiene un helper di alto livello in window.WebToApkFS oltre al bridge grezzo window.WebToApk.

вљ пёЏ Nota sulla memoria di Android 11+: su Android 11 e versioni successive, leggere la memoria condivisa richiede la speciale autorizzazione 'Accesso a tutti i file'. Quando la tua app generata si avvia per la prima volta e l'autorizzazione alla memoria ГЁ attiva, apre automaticamente le Impostazioni di Android per permettere all'utente di concederla. All'utente basta toccare l'interruttore nelle Impostazioni e tornare all'app: nessuna navigazione manuale.

3Verifica delle funzionalitГ sicura per il browser#

Proteggi sempre il tuo codice in modo che funzioni anche in Chrome/Safari, dove il bridge Android non esiste:

function canUseNativeFiles() {
  return !!(window.WebToApkFS && window.WebToApkFS.isAvailable());
}

if (canUseNativeFiles()) {
  console.log('Android native folder access available');
}

4Chiedi all'utente di scegliere una cartella#

Chiama requestAccess() da un clic su un pulsante o da un'altra azione chiara dell'utente. Apre il selettore di cartelle di Android e restituisce l'URI della cartella scelta.

async function connectFolder() {
  const result = await window.WebToApkFS.requestAccess();
  if (!result.success) {
    alert('Folder access was not granted');
    return false;
  }
  console.log('Granted folder:', result.folderUri);
  return true;
}

5Operazioni base sui file#

Una volta concesso l'accesso, puoi elencare le cartelle, creare directory, leggere file di testo, scrivere file di testo, rinominare voci ed eliminare voci.

// Create folders
window.WebToApkFS.mkdir('notes');
window.WebToApkFS.mkdir('notes/2026');

// Write a file
window.WebToApkFS.writeText('notes/2026/today.txt', 'Hello from offline app');

// Read it back
const text = window.WebToApkFS.readText('notes/2026/today.txt');
console.log(text);

// List folder contents
const entries = window.WebToApkFS.list('notes/2026');
console.log(entries);

6Rinomina ed elimina#

Rinomina cambia solo il nome finale della voce. Elimina supporta sia l'eliminazione non ricorsiva sia quella ricorsiva delle directory.

// Rename file or folder
window.WebToApkFS.rename('notes/2026/today.txt', 'journal.txt');

// Delete a single file
window.WebToApkFS.delete('notes/2026/journal.txt');

// Delete a folder tree
window.WebToApkFS.delete('notes/2026', { recursive: true });

7Buoni casi d'uso#

вњ… App offline di note o diario
вњ… Strumenti di importazione/esportazione CSV / JSON
вњ… Semplici backup e ripristini locali
вњ… Editor HTML statici che salvano contenuti dell'utente
вњ… App dashboard che esportano report come testo o CSV

8Limitazioni#

вљ пёЏ Funziona solo su Android. Non esisterГ nei normali browser desktop/mobile.

вљ пёЏ L'helper attuale ГЁ pensato per l'elenco delle cartelle e i file di testo. I flussi con file binari richiedono API aggiuntive.

вљ пёЏ L'accesso ГЁ limitato alla sola cartella concessa dall'utente.

⚠️ Chiama queste API dopo che la pagina è stata caricata, così l'helper è stato iniettato.

9Esempio completo e funzionante#

Questo esempio collega una cartella, crea una directory di lavoro, scrive un file JSON e mostra l'elenco della cartella:

async function setupWorkspace() {
  if (!window.WebToApkFS || !window.WebToApkFS.isAvailable()) {
    console.log('Native folder access not available in this browser');
    return;
  }

  if (!window.WebToApkFS.hasAccess()) {
    const granted = await window.WebToApkFS.requestAccess();
    if (!granted.success) return;
  }

  window.WebToApkFS.mkdir('workspace');
  window.WebToApkFS.writeText(
    'workspace/config.json',
    JSON.stringify({ updatedAt: new Date().toISOString(), mode: 'offline' }, null, 2)
  );

  const files = window.WebToApkFS.list('workspace');
  document.getElementById('output').textContent = JSON.stringify(files, null, 2);
}