12k
All articles

Crie um gerenciador de arquivos desktop com Electron

Crie um gerenciador de arquivos seguro com Electron, renderer isolado, ponte IPC preload e handlers main para navegar, abrir, renomear e mover arquivos para a lixeira.

OpenReplay Team
OpenReplay Team
Crie um gerenciador de arquivos desktop com Electron

Um gerenciador de arquivos em Electron divide o trabalho entre três processos. O processo principal (main) executa todas as operações de sistema de arquivos e de shell, o script de preload expõe algumas funções nomeadas, e o renderer apenas desenha a lista e chama essas funções.

A maioria dos tutoriais de gerenciador de arquivos para Electron é de 2016 a 2021. Eles ativam o nodeIntegration, chamam require('fs') diretamente na página e recorrem ao remote. Código escrito dessa forma ou quebra nas versões atuais do Electron ou deixa uma brecha de segurança aberta. Este guia constrói um navegador de arquivos funcional usando o modelo atual: um renderer em sandbox, uma ponte de preload enxuta e handlers no processo principal que validam todos os caminhos que recebem. Se você nunca criou um app com Electron, leia primeiro Building Desktop Apps with Electron.

Principais conclusões

  • O módulo shell não funciona em um renderer com sandbox, então shell.openPath e shell.trashItem precisam rodar no processo principal, atrás de um canal ipcMain.handle.
  • shell.openPath não rejeita a promise em caso de falha. Ela é resolvida com uma mensagem de erro, e apenas uma string vazia indica que o arquivo foi aberto.
  • O fs.rename do Node sobrescreve um destino existente, então verifique se o nome de destino está livre antes de renomear.
  • Cada função do preload deve encapsular exatamente um canal IPC. Um invoke(channel, ...args) genérico permite que qualquer script da página chame todos os handlers que você registrar.
  • Trate todo caminho enviado pelo renderer como não confiável. Resolva-o no main, compare-o com a pasta escolhida pelo usuário e recuse qualquer coisa fora dela.

O que você vai construir: um gerenciador de arquivos em Electron

O app faz cinco coisas: lista uma pasta, abre subpastas e arquivos, mostra o tamanho e a data de modificação de cada entrada, renomeia entradas e as move para a lixeira. A tabela mostra onde cada operação é executada.

FuncionalidadeExecuta emAPICanal IPC
Escolher pasta raizMaindialog.showOpenDialogdialog:pickFolder
Listar pastaMainfs.readdir + fs.statfs:list
Abrir subpastaRenderer → Mainfs:list novamentefs:list
Abrir arquivoMainshell.openPathshell:open
RenomearMainfs.renamefs:rename
Mover para a lixeiraMainshell.trashItemshell:trash

Configuração do projeto e webPreferences seguras

Crie a estrutura do projeto com o template Vite do Electron Forge:

npx create-electron-app@latest my-app --template=vite

O Forge classifica seu suporte ao Vite como experimental. Se preferir uma opção mais conservadora, use --template=webpack.

De acordo com o checklist de segurança do Electron, a integração com Node vem desativada por padrão desde o Electron 5, o isolamento de contexto vem ativado desde o 12 e o sandbox desde o 20. Mesmo assim, defina as três opções explicitamente, para que ninguém que leia o código precise lembrar dos valores padrão:

mainWindow = new BrowserWindow({
  width: 960,
  height: 640,
  webPreferences: {
    preload: path.join(__dirname, 'preload.cjs'),
    contextIsolation: true, // preload and page get separate JS worlds
    nodeIntegration: false, // no require() in the page
    sandbox: true,          // renderer runs under Chromium's sandbox
  },
});
// keep the template's existing loadURL / loadFile lines below this

O template Vite do Forge 8 gera o script de preload como preload.cjs. Se o main.js gerado no seu projeto usar outro nome de arquivo, mantenha o que já está lá.

Desativar o isolamento de contexto também desativa o sandbox do renderer, independentemente do valor da opção sandbox. Um preload em sandbox só pode fazer require('electron') (ou electron/renderer / electron/common). A documentação de Process Sandboxing proíbe módulos nativos do Node, Buffer e arquivos locais, então o preload precisa ser um único arquivo ou ser empacotado (bundled) em um só.

Processo principal: handlers de sistema de arquivos e de shell

Em um gerenciador de arquivos com Electron, todo o trabalho privilegiado acontece no processo principal, em src/main.js. O módulo shell pode ser usado em um renderer, mas não funciona em um renderer com sandbox. Isso significa que abrir arquivos e enviá-los para a lixeira também passa pelo IPC.

const { app, BrowserWindow, ipcMain, dialog, shell } = require('electron');
const path = require('node:path');
const fs = require('node:fs/promises');

let mainWindow = null;
let rootDir = null; // set only by the folder picker

function assertSender(event) {
  if (BrowserWindow.fromWebContents(event.sender) !== mainWindow) {
    throw new Error('Untrusted sender');
  }
}

function insideRoot(target) {
  const rel = path.relative(rootDir, target);
  return rel === '' ||
    (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
}

async function resolveInRoot(p) {
  if (!rootDir) throw new Error('Pick a folder first');
  const abs = await fs.realpath(path.resolve(String(p)));
  if (!insideRoot(abs)) throw new Error('Path is outside the chosen folder');
  return abs;
}

// Realpath the parent only, so rename/trash act on a symlink, not its target
async function resolveEntry(p) {
  const abs = path.resolve(String(p));
  const parent = await resolveInRoot(path.dirname(abs));
  return path.join(parent, path.basename(abs));
}

function handle(channel, fn) {
  ipcMain.handle(channel, async (event, ...args) => {
    assertSender(event);
    return fn(...args);
  });
}

handle('fs:list', async (dir) => {
  const abs = await resolveInRoot(dir ?? rootDir);
  const dirents = await fs.readdir(abs, { withFileTypes: true });
  const settled = await Promise.allSettled(dirents.map(async (d) => {
    const full = path.join(abs, d.name);
    const st = await fs.stat(full);
    return { name: d.name, path: full, isDir: st.isDirectory(),
             isLink: d.isSymbolicLink(), size: st.size, mtimeMs: st.mtimeMs };
  }));
  const entries = settled.filter((r) => r.status === 'fulfilled').map((r) => r.value)
    .sort((a, b) => (b.isDir - a.isDir) || a.name.localeCompare(b.name));
  return { dir: abs, entries };
});

handle('fs:rename', async (target, newName) => {
  const name = String(newName).trim();
  if (!name || name === '.' || name === '..' || name.includes('/') || name.includes(path.sep)) {
    throw new Error('Invalid file name');
  }
  const src = await resolveEntry(target);
  const dest = path.join(path.dirname(src), name);
  if (!insideRoot(dest)) throw new Error('Path is outside the chosen folder');
  const taken = await fs.access(dest).then(() => true, () => false);
  if (taken) throw new Error(`"${name}" already exists`);
  await fs.rename(src, dest);
});

handle('shell:open', async (target) => {
  const err = await shell.openPath(await resolveInRoot(target));
  if (err) throw new Error(err);
});

handle('shell:trash', async (target) => {
  const abs = await resolveEntry(target);
  if (abs === rootDir) throw new Error('Cannot trash the root folder');
  await shell.trashItem(path.resolve(abs));
});

Veja o que cada parte do código do processo principal faz:

  • Listagem. fs.readdir com withFileTypes retorna objetos Dirent. O fs.stat acrescenta o tamanho e a data de modificação. O Promise.allSettled evita que um único symlink quebrado faça a listagem inteira falhar.
  • Apenas objetos simples. Cada entrada é mapeada para dados simples porque o IPC usa o algoritmo Structured Clone, e uma instância de fs.Stats perderia seus métodos no caminho.
  • Renomear. O fs.rename do Node substitui silenciosamente o newPath se ele já existir, e é por isso que o handler verifica antes. Existe uma pequena janela de tempo entre a verificação e a renomeação, o que é aceitável para uma ferramenta desktop.
  • Abrir. shell.openPath é resolvida com a mensagem de erro se a abertura falhar e com uma string vazia caso contrário. O handler converte uma string não vazia em um erro lançado.
  • Lixeira. shell.trashItem move o item para a lixeira da plataforma em vez de excluí-lo permanentemente. Ela rejeita a promise se ocorrer um erro ao excluir o item solicitado. A documentação do shell exige separadores nativos, e é por isso que o caminho passa por path.resolve().

Preload: uma API pequena e nomeada

O script de preload expõe cinco funções nomeadas para o renderer e nada além disso. Tutoriais antigos faziam assim. Não faça:

// Outdated pattern. Never ship this.
webPreferences: { nodeIntegration: true, contextIsolation: false }
const fs = require('fs'); // in the page

Este é o padrão atual, em src/preload.js:

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  listDir: (dir) => ipcRenderer.invoke('fs:list', dir),
  pickFolder: () => ipcRenderer.invoke('dialog:pickFolder'),
  openPath: (p) => ipcRenderer.invoke('shell:open', p),
  rename: (p, newName) => ipcRenderer.invoke('fs:rename', p, newName),
  trash: (p) => ipcRenderer.invoke('shell:trash', p),
});

Cada função do preload tem o nome do seu canal IPC fixo no código. Nunca escreva invoke: (...a) => ipcRenderer.invoke(...a), porque isso dá à página acesso a todos os handlers que você registrar. Observe também que, quando um handler registrado com ipcMain.handle lança um erro, o renderer recebe apenas a message do erro. Escreva mensagens que um usuário consiga entender. Se uma chamada IPC travar ou falhar sem explicação, Debugging and Troubleshooting Common Electron Issues explica como distinguir falhas do processo principal de falhas do renderer.

Renderer: listar, abrir, renomear, enviar para a lixeira

O renderer só mexe no DOM e em window.electronAPI. Nomes de arquivo podem conter marcação, então defina-os com textContent e nunca com innerHTML.

Primeiro, dê à página um lugar onde renderizar o conteúdo. Substitua o <body> do index.html do template por esta marcação, mantendo a tag <script> do template para src/renderer.js:

<body>
  <header>
    <button id="pick">Choose folder</button>
    <button id="up">Up</button>
    <span id="status" role="status"></span>
  </header>
  <ul id="list"></ul>
  <dialog id="rename-dialog">
    <form method="dialog">
      <label>New name <input id="rename-input" required></label>
      <button value="cancel" formnovalidate>Cancel</button>
      <button value="ok">Rename</button>
    </form>
  </dialog>
  <script type="module" src="/src/renderer.js"></script>
</body>

O Electron não implementa window.prompt(), então a caixa de renomeação é um <dialog>. Em seguida, substitua o conteúdo de src/renderer.js:

const api = window.electronAPI;
const list = document.querySelector('#list');
const status = document.querySelector('#status');
const renameDialog = document.querySelector('#rename-dialog');
const renameInput = document.querySelector('#rename-input');
let cwd = null;

function askName(current) {
  renameInput.value = current;
  renameDialog.returnValue = '';
  renameDialog.showModal();
  return new Promise((resolve) => {
    renameDialog.addEventListener('close', () =>
      resolve(renameDialog.returnValue === 'ok' ? renameInput.value : null), { once: true });
  });
}

const fmtSize = (n) => {
  const u = ['B', 'KB', 'MB', 'GB', 'TB']; let i = 0;
  while (n >= 1024 && i < u.length - 1) { n /= 1024; i++; }
  return `${n.toFixed(i ? 1 : 0)} ${u[i]}`;
};

async function run(fn) {
  try { status.textContent = ''; await fn(); }
  catch (err) { status.textContent = err.message; }
}

async function load(dir) {
  const res = await api.listDir(dir);
  cwd = res.dir;
  list.replaceChildren(...res.entries.map(row));
}

function button(label, onClick) {
  const b = document.createElement('button');
  b.textContent = label;
  b.addEventListener('click', (e) => { e.stopPropagation(); run(onClick); });
  return b;
}

function row(entry) {
  const li = document.createElement('li');
  const cells = [entry.isDir ? `${entry.name}/` : entry.name,
    entry.isDir ? '' : fmtSize(entry.size),
    new Date(entry.mtimeMs).toLocaleString()];
  for (const text of cells) {
    const span = document.createElement('span');
    span.textContent = text;
    li.append(span);
  }
  li.append(
    button('Rename', async () => {
      const name = await askName(entry.name);
      if (name && name !== entry.name) { await api.rename(entry.path, name); await load(cwd); }
    }),
    button('Trash', async () => {
      if (confirm(`Move "${entry.name}" to the trash?`)) { await api.trash(entry.path); await load(cwd); }
    }),
  );
  li.addEventListener('dblclick', () =>
    run(() => (entry.isDir ? load(entry.path) : api.openPath(entry.path))));
  return li;
}

document.querySelector('#up').addEventListener('click', () => run(() => load(`${cwd}/..`)));

Um clique duplo em uma pasta lista seu conteúdo. Um clique duplo em um arquivo o repassa ao sistema operacional. O botão Up envia cwd/... Ao chegar à raiz, o main recusa a requisição e a linha de status exibe o erro.

Seletor de pastas com dialog.showOpenDialog

A pasta raiz vem exclusivamente de um diálogo nativo no main e é armazenada exclusivamente no main. O renderer nunca envia uma raiz. Ele envia caminhos, e o main os valida em relação à raiz que já possui. Adicione este handler ao main.js:

handle('dialog:pickFolder', async () => {
  const { canceled, filePaths } = await dialog.showOpenDialog(mainWindow, {
    properties: ['openDirectory'],
  });
  if (canceled) return null;
  rootDir = await fs.realpath(filePaths[0]);
  return rootDir;
});

Na API dialog, a propriedade openDirectory é o que permite selecionar diretórios. Passar a janela como primeiro argumento a vincula ao diálogo como janela pai, o que torna o diálogo modal. A raiz passa pelo realpath uma única vez, aqui. Dessa forma, um symlink dentro da pasta que aponte para outro lugar é resolvido para fora da raiz e falha na verificação de insideRoot.

Conecte o seletor no renderer:

document.querySelector('#pick').addEventListener('click', () => run(async () => {
  const dir = await api.pickFolder();
  if (dir) await load(dir);
}));

Hardening: caminhos, remetentes e CSP

Três controles tornam este navegador de arquivos em Electron uma base segura para evoluir:

  1. Contenção de caminhos. Todo handler passa a entrada vinda do renderer por resolveInRoot ou resolveEntry. Ambas resolvem symlinks e usam path.relative para rejeitar qualquer coisa que tente sair da raiz ou que caia em outra unidade no Windows.
  2. Validação do remetente. O checklist de segurança recomenda validar o remetente das mensagens IPC, porque qualquer frame pode enviá-las. assertSender aceita chamadas apenas do webContents de mainWindow.
  3. Content Security Policy. Uma página carregada via file:// não pode receber a CSP como cabeçalho HTTP, então adicione uma meta tag ao index.html:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">

Opcionalmente, bloqueie a navegação e a abertura de novas janelas no main:

mainWindow.webContents.on('will-navigate', (e) => e.preventDefault());
mainWindow.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));

Conclusão

Agora você tem um gerenciador de arquivos seguro em Electron. O main controla o sistema de arquivos e a pasta raiz, o preload expõe cinco funções fixas e o renderer não consegue acessar nada que você não tenha entregado a ele. Estenda o app sempre da mesma forma: um novo handler no main, uma nova função no preload e as mesmas verificações de caminho e de remetente em cada um. Quando estiver pronto para distribuir, siga Packaging and Distributing Electron Apps. Se o consumo de recursos do Electron for uma preocupação para esse tipo de ferramenta, veja Comparing Electron and Tauri for Desktop Applications.

Perguntas frequentes

Por que prompt() lança um erro em um renderer do Electron?

O Electron não implementa window.prompt(), então chamá-lo lança um erro em vez de abrir um diálogo. As funções alert() e confirm() funcionam no Electron. Para pedir um novo nome de arquivo, use um campo de texto na própria página ou um elemento HTML dialog. Você também pode abrir uma pequena BrowserWindow modal a partir do processo principal e enviar o valor digitado de volta via IPC.

Como obtenho o caminho real de um arquivo arrastado para uma janela do Electron?

Chame webUtils.getPathForFile(file) no script de preload e exponha-o por meio do contextBridge. O Electron 32 removeu a propriedade não padrão File.path do objeto File da Web, então código que lê file.path não obtém mais um caminho. Envie o caminho retornado para um handler no processo principal e aplique a ele a mesma verificação de pasta raiz usada para qualquer outra entrada vinda do renderer.

Como fazer a lista de arquivos ser atualizada automaticamente quando os arquivos mudam no disco?

Monitore a pasta listada com fs.watch no processo principal e envie uma notificação para a página com mainWindow.webContents.send. No preload, encapsule ipcRenderer.on para que ele chame o callback do renderer sem o objeto de evento, porque repassar o evento expõe o ipcRenderer à página. Trate cada evento apenas como um sinal para executar fs:list novamente. O Node informa apenas 'rename' e 'change', e o nome do arquivo pode ser null.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.