Como descontinuar o evento de descarregamento

Demián Renzulli

Barry Pollard

Publicado em: 10 de agosto de 2023. Última atualização: 28 de abril de 2026

O evento unload será gradualmente descontinuado com a mudança gradual do padrão para que os manipuladores unload parem de ser disparados nas páginas, a menos que uma página ative explicitamente a opção de reativá-los.

Cronograma de descontinuação

Observamos que o comportamento de descarregamento provavelmente estaria sujeito a mudanças já em janeiro de 2019, quando anunciamos nossa intenção de implementar um cache de avanço e retorno. Paralelamente ao trabalho de implementação, realizamos um grande contato que resultou em uma queda significativa no uso do descarregamento. Para complementar essa divulgação, também começamos a oferecer maneiras de testar o efeito da suspensão de uso do descarregamento no Chrome 115:

• Teste em ambiente real usando a API Permission-Policy para descarregamento no Chrome 115 (julho de 2023)
• Teste local ativando uma flag no Chrome 117 (setembro de 2023)

Ao longo de 2024, resolvemos vários problemas que impediam o início do lançamento e, ao longo de 2025, lançamos a descontinuação nos 50 principais sites.

Agora que concluímos a descontinuação dos 50 principais sites, recebemos mais aprovação para lançar isso em todas as origens, em mais de oito marcos (ou cerca de 32 semanas), conforme detalhado na tabela a seguir.

O lançamento completo é baseado em carregamentos de página (com consistência ao longo do tempo), em vez de usuários ou sites individuais, para evitar afetar usuários ou sites mais do que outros, conforme detalhado na intenção de descontinuar.

Note that we also offer a menu of opt-out options in case this deprecation timeline doesn't provide sufficient time to migrate away from unload. Nosso objetivo é usar essa descontinuação gradual para informar o cronograma da última fase (descontinuação definitiva do descarregamento), em que essas recusas serão removidas ou reduzidas.

Contexto

unload foi projetado para ser acionado quando o documento está sendo descarregado. Na teoria, ele pode ser usado para executar código sempre que um usuário sai de uma página ou como um callback de fim de sessão.

Os cenários em que esse evento foi mais usado incluem:

• Salvar dados do usuário: salve os dados antes de sair da página.
• Realização de tarefas de limpeza: fechamento de recursos abertos antes de abandonar a página.
• Envio de análises: envio de dados relacionados às interações do usuário no final da sessão.

No entanto, o evento unload não é confiável.

No Chrome e no Firefox para computador, unload é razoavelmente confiável, mas tem um impacto negativo no desempenho de um site, impedindo o uso do bfcache (cache de avanço e retorno).

Em navegadores para dispositivos móveis, o unload geralmente não é executado porque as guias são frequentemente colocadas em segundo plano e depois encerradas. Por isso, os navegadores priorizam o bfcache em dispositivos móveis em vez de unload, o que os torna ainda mais não confiáveis. O Safari também usa esse comportamento no computador.

A equipe do Chrome acredita que usar o modelo móvel de priorizar o bfcache em vez de unload no computador seria prejudicial, tornando-o menos confiável também, quando antes ele era razoavelmente confiável no Chrome (e no Firefox). Em vez disso, o objetivo do Chrome é remover completamente o evento unload. Até lá, ele vai continuar confiável no computador para quem desativou explicitamente a descontinuação.

Por que descontinuar o evento unload?

A descontinuação do unload é uma etapa fundamental em um reconhecimento muito maior da Web em que vivemos agora. O evento unload dá uma falsa sensação de controle do ciclo de vida do app, o que é cada vez mais falso na forma como navegamos na Web no mundo da computação moderna.

Os sistemas operacionais móveis costumam congelar ou descarregar páginas da Web para economizar memória, e os navegadores para computador também estão fazendo isso cada vez mais pelos mesmos motivos. Mesmo sem intervenções do sistema operacional, os usuários costumam trocar de guia e fechar as antigas sem "sair das páginas" formalmente.

Remover o evento unload como obsoleto é um reconhecimento de que nós, como desenvolvedores da Web, precisamos garantir que nosso paradigma corresponda ao do mundo real e não dependa de conceitos desatualizados que não são mais válidos, se é que algum dia foram.

Alternativas aos eventos de unload

Em vez de unload, recomendamos usar:

• visibilitychange: para determinar quando a visibilidade de uma página muda. Esse evento acontece quando o usuário muda de guia, minimiza a janela do navegador ou abre uma nova página. Considere o estado hidden como o último momento confiável para salvar dados de apps e dados do usuário.
• pagehide: para determinar quando o usuário saiu da página. Esse evento acontece quando o usuário sai da página, atualiza a página ou fecha a janela do navegador. O evento pagehide não é acionado quando a página é minimizada ou trocada para outra guia. Como pagehide não torna uma página inelegível para o cache de avanço e retorno, é possível que ela seja restaurada após o acionamento desse evento. Se você estiver limpando recursos neste evento, eles poderão precisar ser restaurados na restauração da página.

O evento beforeunload tem um caso de uso um pouco diferente de unload, já que é um evento cancelável. Geralmente é usado para avisar os usuários sobre mudanças não salvas ao sair da página. Esse evento também não é confiável, porque não é disparado se uma guia em segundo plano for encerrada. É recomendável limitar o uso de beforeunload e adicionar apenas condicionalmente. Em vez disso, use os eventos mencionados anteriormente para a maioria das substituições de unload.

Para mais detalhes, consulte esta dica sobre nunca usar o manipulador unload.

Detectar o uso de unload

Há diferentes ferramentas para ajudar você a encontrar ocorrências do evento unload nas páginas. Isso permite que os sites descubram se estão usando esse evento, seja no próprio código ou usando bibliotecas, e, portanto, podem ser afetados pela descontinuação futura.

Chrome DevTools

O Chrome DevTools inclui uma auditoria do back-forward-cache para ajudar você a identificar problemas que podem impedir que sua página se qualifique para o cache de avanço e retorno, incluindo o uso do manipulador unload.

Para testar o cache de avanço e retorno, siga estas etapas:

1. Na sua página, abra o DevTools e navegue até Application > Background services > cache de avanço e retorno.

2. Clique em Testar cache de avanço e retorno. O Chrome vai levar você automaticamente para chrome://terms/ e voltar para sua página. Se preferir, clique nos botões "Voltar" e "Avançar" do navegador.

Se a página não estiver qualificada para o cache de avanço e retorno, a guia Cache de avanço e retorno vai mostrar uma lista de problemas. Em Útil, você pode conferir se está usando unload:

API Reporting

A API Reporting pode ser usada em conjunto com uma política de permissões somente leitura para detectar o uso de unload pelos usuários do seu site.

Para mais detalhes, consulte Usar a API Reporting para encontrar descarregamentos.

API notRestoredReasons do Bfcache

A propriedade notRestoredReasons, adicionada à classe PerformanceNavigationTiming, informa se os documentos foram impedidos de usar o bfcache na navegação e por quê. Este é um exemplo de como fica o aviso do objeto de resposta de um listener unload atual:

{
   children: [],
   id: null,
   name: null,
   reasons: [
     {"reason", "unload-listener"}
   ],
   src: null,
   url: "https://www.example.com/page/"
}

Controlar o acesso a unload

O Chrome vai descontinuar gradualmente o evento unload. Enquanto isso, use diferentes ferramentas para controlar esse comportamento e se preparar para a descontinuação. Não confie nessas técnicas a longo prazo. Planeje migrar para as alternativas o mais rápido possível.

As opções a seguir permitem ativar ou desativar os manipuladores unload para testar como seu site funcionaria sem eles e se preparar para a descontinuação. Há diferentes tipos de políticas:

• Política de permissões: é uma API de plataforma para proprietários de sites controlarem o acesso a recursos no nível do site ou de uma página individual usando cabeçalhos HTTP.
• Políticas empresariais: ferramentas para administradores de TI configurarem o Chrome para a organização ou empresa. Eles podem ser configurados usando um painel de administrador, como o Google Admin Console.
• Flags do Chrome: permite que um desenvolvedor mude a configuração de descontinuação unload para testar o impacto em vários sites.

Política de permissões

Uma política de permissões foi adicionada no Chrome 115 para permitir que os sites desativem o uso de manipuladores unload e se beneficiem imediatamente do bfcache para melhorar o desempenho do site. Confira estes exemplos de como definir isso para seu site. Isso permite que os sites se antecipem à descontinuação do unload.

Esse período foi estendido no Chrome 117 para permitir que os sites fizessem o contrário e ativassem a opção de continuar tentando acionar os manipuladores unload como fazem agora, já que o Chrome vai mudar o padrão para que eles não sejam acionados no futuro. Confira estes exemplos de como continuar permitindo que os manipuladores de descarregamento sejam acionados no seu site. Embora incentivemos os proprietários de sites a deixar de usar manipuladores unload devido à falta de confiabilidade, planejamos oferecer suporte a essa recusa por um futuro considerável para sites que precisam usá-la. Além disso, a reativação não torna os manipuladores unload mais confiáveis em dispositivos móveis. Ela apenas restaura o status quo atual.

Política empresarial

As empresas que têm softwares que dependem do evento unload para funcionar corretamente podem usar a política ForcePermissionPolicyUnloadDefaultEnabled para evitar a descontinuação gradual em dispositivos sob controle delas. Ao ativar essa política, o unload vai continuar ativado por padrão para todas as origens. Uma página ainda pode definir uma política mais restrita se quiser. Assim como a recusa da Permissions Policy, essa é uma ferramenta para reduzir possíveis mudanças incompatíveis. Recomendamos que os proprietários de sites parem de depender de manipuladores unload, mas o Chrome planeja oferecer suporte a essa desativação corporativa por um futuro considerável para sites que precisam usá-la.

Flags do Chrome e chaves da linha de comando

Além da política empresarial, é possível desativar a descontinuação para usuários individuais usando as flags do Chrome e as opções de linha de comando:

Definir chrome://flags/#deprecate-unload como enabled vai mover adiante o padrão de descontinuação e impedir que os gerenciadores unload sejam disparados. Elas ainda podem ser substituídas site por site usando a política de permissões, mas vão continuar sendo acionadas por padrão.

Essas configurações também podem ser controladas por chaves de linha de comando.

Comparação de opções

A tabela a seguir resume os diferentes usos das opções discutidas anteriormente:

Conclusão

Os manipuladores unload estão sendo descontinuados. Eles não são confiáveis há muito tempo e não há garantia de que serão acionados em todos os casos em que um documento é destruído. Além disso, os manipuladores unload são incompatíveis com o bfcache.

Os sites que usam manipuladores unload precisam se preparar para essa descontinuação testando os manipuladores unload atuais, removendo ou migrando-os ou, como último recurso, adiando a descontinuação se for necessário mais tempo.

Agradecimentos

Agradecemos a Kenji Baheux, Fergal Daly, Adriana Jara e Jeremy Wagner pela ajuda na revisão deste artigo.

Imagem principal de Anja Bauermann no Unsplash