Native Folder Access

1O que este recurso faz#

Este recurso dá ao seu app web acesso controlado a uma pasta do Android escolhida pelo usuário, usando o Storage Access Framework (SAF). Funciona bem para apps HTML offline, editores, fluxos de backup/restauração e ferramentas de importação/exportação.

Ele NÃO dá acesso irrestrito ao armazenamento do dispositivo. O usuário escolhe explicitamente uma pasta, e seu app só pode trabalhar dentro dessa árvore autorizada.

2Ative no gerador#

Na Etapa 4 do gerador, ATIVE 'Acesso nativo a pastas (SAF)'. Depois, gere o app.

Quando ativado, seu site ganha um helper de alto nível em window.WebToApkFS, além da ponte bruta window.WebToApk.

⚠️ Observação sobre armazenamento no Android 11+: no Android 11 e superior, ler o armazenamento compartilhado exige a permissão especial 'Acesso a todos os arquivos'. Quando seu app gerado é aberto pela primeira vez e a permissão de armazenamento está ativada, ele abre automaticamente a tela de Configurações do Android para o usuário conceder essa permissão. O usuário só precisa tocar na chave nas Configurações e voltar ao app - sem navegação manual.

3Verificação de capacidade segura para o navegador#

Sempre proteja seu código para que ele continue funcionando no Chrome/Safari, onde a ponte do Android não existe:

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

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

4Peça ao usuário para escolher uma pasta#

Chame requestAccess() a partir de um clique em botão ou outra ação clara do usuário. Ela abre o seletor de pastas do Android e retorna o URI da pasta escolhida.

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

5Operações básicas com arquivos#

Depois que o acesso é concedido, você pode listar pastas, criar diretórios, ler arquivos de texto, gravar arquivos de texto, renomear itens e excluir itens.

// 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);

6Renomear e excluir#

Renomear altera apenas o nome final do item. Excluir oferece exclusão de diretórios tanto não recursiva quanto recursiva.

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

7Bons casos de uso#

✅ Apps offline de notas ou diário
✅ Ferramentas de importação e exportação de CSV / JSON
✅ Backup e restauração locais simples
✅ Editores de HTML estático que salvam o conteúdo do usuário
✅ Apps de painel que exportam relatórios em texto ou CSV

8Limitações#

⚠️ Isto é exclusivo do Android. Não existirá em navegadores comuns de desktop/celular.

⚠️ O helper atual foi pensado para listagem de pastas e arquivos de texto. Fluxos com arquivos binários exigem APIs adicionais.

⚠️ O acesso é restrito à única pasta que o usuário autorizou.

⚠️ Chame estas APIs depois que a página for carregada, para que o helper já tenha sido injetado.

9Exemplo completo e funcional#

Este exemplo conecta uma pasta, cria um diretório de trabalho, grava um arquivo JSON e exibe a listagem da pasta:

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