beforeunload

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

O evento beforeunload é disparado quando o window, o document e seus recursos estão prestes a ser descarregados.

Quando uma string é atribuída na propriedade returnValue do Event, uma caixa de díalogo aparecerá solicitando ao usuário uma confirmação para sair da página (veja exemplo abaixo). Quando nenhum valor é fornecido, o evento é processado silenciosamente.

Bubbles Não
Cancelable Sim
Target objects defaultView
Interface Event

Propriedades

Propriedade Tipo Descrição
target Somente leitura EventTarget O evento alvo (the topmost target in the DOM tree).
type Somente leitura DOMString O tipo de evento.
bubbles Somente leitura Boolean O evento é normalmente bubble?
cancelable Somente leitura Boolean É possível cancelar o evento?
returnValue DOMString O valor de retorno do evento (a mensagem que será exibida ao usuário).

Exemplos

js
window.addEventListener("beforeunload", function (event) {
  event.returnValue = "\\o/";
});

// equivalente a
window.addEventListener("beforeunload", function (event) {
  event.preventDefault();
});

Navegadores baseados no WebKit não seguem a especificação para caixas de diálogo. Um exemplo que funcionaria na maioria dos navegadores seria aproximadamente o seguinte:

js
window.addEventListener("beforeunload", function (e) {
  var confirmationMessage = "\\o/";

  e.returnValue = confirmationMessage; // Gecko, Trident, Chrome 34+
  return confirmationMessage; // Gecko, WebKit, Chrome <34
});

Notas

Quando este evento retorna um valor não vazio (non-void), é solicitada ao usuário uma confirmação para descarregar a página. Na maioria dos navegadores o valor retornado no evento é exibido como mensagem nessa confirmação. No Firefox 4 e versões anteriores a string retornada não é exibida para o usuário. Ao invés disso, o Firefox exibe a mensagem "Esta página está perguntanto se você deseja sair - é possível que as alterações feitas não sejam salvas." Veja Erro do Firefox 588292.

Desde 25 de maio de 2011 a especificação HTML5 define que chamadas aos métodos window.alert(), window.confirm() e window.prompt() serão ignoradas durante este evento. Para mais detalhes veja a especificação HTML5 (em inglês).

Note também que vários navegadores para celular ignoram o resultado deste evento (isso que dizer que eles não solicitam a confirmação do usuário). O Firefox possui uma configuração escondida em about:config que faz o mesmo. Em essência, isto significa que o usuário estará sempre confirmando que o documento pode ser descarregado.

Veja também