Como descontinuar o evento de descarregamento

Demián Renzulli

Barry Pollard

Publicado em 10 de agosto de 2023, última atualização: 29 de junho de 2026

O evento unload será gradualmente descontinuado, mudando o padrão para que os manipuladores unload parem de ser acionados nas páginas, a menos que uma página ative explicitamente a reativação deles.

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 de unload usage. Para complementar esse alcance, também começamos a oferecer maneiras de testar o efeito da descontinuação do descarregamento no Chrome 115:

• Teste em campo 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 da implantação e, ao longo de 2025, lançamos a descontinuação nos 50 principais sites:

Em 2026, começamos a lançar essa opção para todas as origens, em mais de oito marcos (ou cerca de 32 semanas), conforme detalhado na tabela a seguir.

A implantação completa é baseada em carregamentos de páginas (com consistência ao longo do tempo), em vez de usuários ou sites individuais, para evitar o impacto em usuários ou sites mais do que outros, conforme detalhado na Intenção de descontinuação.

Também oferecemos um menu de opções de desativação caso esse cronograma de descontinuação não ofereça tempo suficiente para migrar do descarregamento.

Contexto

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

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

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

No entanto, o evento unload é extremamente 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, já que as guias são frequentemente colocadas em segundo plano e depois encerradas. Por esse motivo, os navegadores optam por priorizar o bfcache em dispositivos móveis em vez de unload, tornando-os ainda mais não confiáveis. O Safari também usa esse comportamento no computador.

A equipe do Chrome acredita que o uso do modelo para dispositivos móveis de priorizar o bfcache em vez de unload no computador seria prejudicial tornando-o mais não confiável também, quando antes ele era razoavelmente confiável no Chrome (e no Firefox). Em vez disso, o objetivo do Chrome é remover o evento unload completamente. Até então, ele vai permanecer confiável no computador no Chrome 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, que é cada vez mais falsa de como navegamos na Web no mundo da computação moderna.

Os sistemas operacionais para dispositivos móveis congelam ou descarregam páginas da Web com frequência para conservar a 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 próprios usuários costumam alternar guias e encerrar guias antigas sem "sair das páginas" formalmente.

A remoção do evento unload como obsoleto é um reconhecimento de que nós, como desenvolvedores da Web, precisamos garantir que nosso paradigma corresponda ao mundo real e não dependa de conceitos desatualizados que não são mais verdadeiros, se é que já foram.

Alternativas a eventos unload

Em vez de unload, é recomendável usar:

• visibilitychange: para determinar quando a visibilidade de uma página muda. Esse evento acontece quando o usuário troca de guia, minimiza a janela do navegador ou abre uma nova página. Considere o hidden estado como o último momento confiável para salvar dados do app 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, recarrega 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. Note que, como pagehide não torna uma página inelegível para o cache de avanço e retorno, é possível que uma página seja restaurada após esse evento ser disparado. Se você estiver limpando recursos nesse evento, eles poderão ter que ser restaurados na restauração da página.

O evento beforeunload tem um caso de uso ligeiramente diferente de unload, já que é um evento cancelável. Ele é usado com frequência para alertar os usuários sobre mudanças não salvas ao sair. Esse evento também não é confiável, já que não será acionado se uma guia em segundo plano for encerrada. É recomendável limitar o uso de beforeunload e adicioná-lo apenas condicionalmente. Em vez disso, use os eventos mencionados anteriormente para a maioria das substituições de unload.

Para mais detalhes, consulte este conselho 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 back-forward-cache auditoria para ajudar a identificar problemas que podem impedir que sua página seja qualificada para o cache de avanço e retorno, incluindo o uso do gerenciador unload.

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

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

2. Clique em Test back/forward cache . O Chrome vai levar você automaticamente para chrome://terms/ e voltar para a página. Como alternativa, clique nos botões de avanço e retorno do navegador.

Se a página não for qualificada para o cache de avanço e retorno, a guia Back/forward cache vai mostrar uma lista de problemas. Em Actionable, 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 dos 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 a resposta do objeto de aviso de um listener unload existente se parece:

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

Controlar o acesso a unload

O Chrome está descontinuando o evento unload gradualmente. Enquanto isso, você pode usar diferentes ferramentas para controlar esse comportamento e se preparar para a descontinuação futura. Lembre-se de que você não deve confiar nessas técnicas a longo prazo e planejar a migração para as alternativas o mais rápido possível.

As opções a seguir permitem ativar ou desativar manipuladores unload para testar como seu site funcionaria sem eles, para que você possa se preparar para a descontinuação futura. 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, em um site ou em 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. Elas podem ser configuradas usando um painel de administrador, como o Google Admin Console.
• Chrome flags: isso permite que um desenvolvedor individual 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 ao 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. Consulte estes exemplos de como definir isso para seu site. Isso permite que os sites fiquem à frente da descontinuação unload.

Isso foi estendido no Chrome 117 para permitir que os sites façam o contrário e ativem a opção de continuar tentando acionar unload manipuladores como fazem agora, à medida que o Chrome muda o padrão para que eles não sejam acionados no futuro. Consulte estes exemplos de como continuar permitindo que os manipuladores de descarregamento sejam acionados no seu site. Embora incentivemos os proprietários de sites a parar de usar manipuladores unload devido à falta de confiabilidade, planejamos oferecer suporte a essa desativação por um futuro considerável para sites que precisam usá-la. 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 unload evento para funcionar corretamente podem usar a ForcePermissionPolicyUnloadDefaultEnabled política para impedir a descontinuação gradual de dispositivos sob controle. Ao ativar essa política, unload vai continuar sendo ativado por padrão para todas as origens. Uma página ainda pode definir uma política mais rigorosa, se quiser. Assim como a desativação da política de permissões, essa é uma ferramenta para atenuar possíveis mudanças interruptivas. Mais uma vez, incentivamos os proprietários de sites a parar de depender de manipuladores unload, mas o Chrome planeja oferecer suporte a essa desativação empresarial por um futuro considerável para sites que precisam usá-la.

Chrome flags e chaves de linha de comando

Além da política empresarial, você pode desativar a descontinuação para usuários individuais usando as flags do Chrome e as chaves 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. Eles ainda podem ser substituídos site a site usando a política de permissões, mas vão continuar sendo acionados 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 são nã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 futura testando os manipuladores unload existentes, removendo ou migrando-os ou, como último recurso, atrasando a descontinuação se mais tempo for necessário.

Agradecimentos

Agradecemos a Kenji Baheux, Fergal Daly, Adriana Jara e Jeremy Wagner pelo feedback útil da revisão.

Imagem principal de Anja Bauermann no Unsplash