Recarregar a página com JavaScript: location.reload()
Recarregar uma página com JavaScript
JavaScript location.reload(): atualize uma página do jeito certo | We.Inc
Recarregue a página com location.reload(), compare com history.go(0), replace e meta refresh, gere código de atualização temporizada e entenda o que reload(true) faz de verdade.
Chame location.reload() para recarregar a página atual, exatamente como faz o botão de recarregar do navegador. Ele não recebe argumentos padrão. A forma antiga reload(true), que servia para pular o cache, é um parâmetro fora do padrão que o MDN lista como suportado só no Firefox, então os outros navegadores ignoram o true. history.go(0) também recarrega.
Formas de atualizar ou mudar a página
Código
O que acontece
Adiciona uma entrada no histórico?
location.reload()
Recarrega a URL atual
Não
history.go(0) or history.go()
Mesmo resultado que location.reload()
Não
location.replace(url)
Carrega a url e substitui a entrada atual
Não, o Voltar pula a página antiga
location.assign(url)
Carrega a url como um novo passo
Sim
<meta http-equiv="refresh" content="30">
Recarrega depois de 30 segundos, sem script
Não
Recarregar é uma linha de código, mas os motivos para isso variam: pegar dados novos, resetar um estado travado, atualizar um dashboard em um intervalo ou forçar uma nova versão do site. Este guia mostra a chamada padrão, o que as variações mais antigas realmente fazem e como evitar recarregar quando tudo o que você precisa é buscar dados novos.
Escolha um método de atualização e um intervalo no gerador.
A caixa de código se atualiza com um trecho pronto para colar para esse método.
Use os botões para testar location.reload() e history.go(0) nesta página. Os dois a recarregam.
Leia a seção sobre cache antes de contar com um reload para mostrar arquivos recém-publicados.
O location.reload() não retorna nada, e o código depois dele ainda pode rodar por um instante antes de a página ser descarregada, então coloque-o por último.
Antes de recarregar uma página com formulário, avise sobre dados não salvos com um listener beforeunload; o navegador mostra a própria mensagem genérica dele, não a sua.
Uma atualização temporizada em uma aba escondida gasta dados e bateria. Confira document.visibilityState e pule o reload enquanto a aba estiver em segundo plano.
Em uma single page app, buscar os dados de novo ou resetar o estado costuma ser mais rápido e mantém a posição de rolagem, o que foi digitado e o foco.
Perguntas frequentes
O location.reload(true) limpa o cache?
Não de forma confiável. O argumento forceGet não faz parte do padrão HTML, e o MDN observa que só o Firefox o suporta. Os outros navegadores o ignoram e fazem um reload normal. Para garantir que as pessoas recebam arquivos novos, coloque versão nas URLs dos seus arquivos ou defina headers Cache-Control adequados.
Qual a diferença entre location.reload() e location.href = location.href?
O reload() sempre recarrega o documento atual. Atribuir o href inicia uma navegação para essa URL, e quando a URL contém um #fragmento o navegador só rola até o fragmento, então nada é recarregado. Use reload() quando o que você quer é recarregar.
Como atualizo uma página a cada 30 segundos?
Sem script, adicione <meta http-equiv="refresh" content="30"> ao head. Com script, setTimeout(() => location.reload(), 30000). Use a atualização automática com moderação: o MDN avisa que atualizações inesperadas podem desorientar as pessoas e entrar em conflito com as orientações da WCAG sobre tempo.
Um script pode recarregar uma página de outro site?
Não. Chamar reload no Location de outra origem lança uma DOMException SecurityError, então um script dentro de um iframe de outro site não pode recarregar a página pai, e a página pai não pode recarregá-lo desse jeito.
Como recarrego a página só uma vez?
Marque que você já recarregou, por exemplo com uma flag no sessionStorage ou um parâmetro de query como ?r=1, e confira antes de chamar o reload. Sem essa proteção, um código que recarrega no carregamento cria um loop infinito.
Recarregar versus buscar dados novos
Um reload completo joga fora a página inteira: o DOM, todas as variáveis, menus abertos, o que foi digitado e geralmente a posição de rolagem. Esse é o reset certo quando a página está em um estado ruim ou uma nova versão precisa carregar.
Quando você só precisa de números novos em um dashboard, chame fetch, atualize a parte da página que mudou e deixe o resto. É mais rápido, usa menos dados e não faz a tela piscar.
Por que um reload ainda pode mostrar arquivos antigos
Um reload normal deixa o navegador revalidar com o servidor os arquivos em cache, mas arquivos servidos com um tempo de cache longo ainda podem vir direto do cache. Código que tenta forçar uma atualização completa a partir do JavaScript não resolve isso em todos os navegadores.
A solução confiável fica no servidor e no build: coloque um hash do conteúdo nos nomes dos arquivos de script e de estilo para que cada deploy ganhe URLs novas, e sirva o HTML com um tempo de cache curto ou com no-cache para que ele sempre aponte para os arquivos mais recentes.
Código de reload para colar
Um botão de recarregar
O handler de clique chama o reload padrão sem argumento.
Atualizar em um intervalo, mas só com a aba visível
Abas escondidas são puladas, e uma aba que volta depois do intervalo recarrega na hora.
Recarregar exatamente uma vez
A flag no sessionStorage sobrevive ao reload na mesma aba, então o segundo carregamento a pula.
Avisar antes de recarregar com alterações não salvas
Os navegadores só mostram o aviso depois que a pessoa interagiu com a página, e usam as próprias palavras.
Gerador de código de atualização
Escolha como e com que frequência a página deve atualizar, depois copie o trecho.
Método
Recarregar agora
Timer em JavaScript
Timer, só com a aba visível
Meta refresh em HTML
A cada {n} segundos
Trecho
Teste nesta página
location.reload()
history.go(0)
Os dois botões recarregam esta página. Tudo o que foi digitado acima será perdido.