Vincular arquivo JavaScript a arquivo HTML

Para adicionar JavaScript a uma página HTML, inclua um elemento <script>. Use o atributo src para carregar um arquivo .js separado ou escreva um script curto entre as tags de abertura e fechamento. Para a maioria dos scripts que precisam acessar o DOM da página, coloque o arquivo externo no <head> com defer; use async para scripts independentes cuja ordem de execução não importa.

Vincular um arquivo JavaScript externo com src

Crie um arquivo JavaScript e faça referência a ele no documento HTML. Por exemplo, se index.html e app.js estiverem no mesmo diretório, esta página carregará app.js:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>External script example</title>
  <script src="./app.js" defer></script>
</head>
<body>
  <h1 id="message">Waiting for JavaScript</h1>
</body>
</html>

O valor ./app.js é um caminho de URL resolvido em relação à URL do documento HTML, e não ao local do arquivo JavaScript no seu computador nem ao diretório de trabalho do servidor. Se o arquivo estiver em um subdiretório js ao lado da página, use ./js/app.js. Confira a grafia e o uso de maiúsculas e minúsculas: caminhos que funcionam em uma máquina de desenvolvimento que não diferencia maiúsculas de minúsculas podem falhar em um servidor que diferencia. Já uma barra inicial, como em /js/app.js, indica que o caminho começa na raiz da URL do site.

O atributo defer permite que o navegador baixe o arquivo enquanto analisa o HTML e o execute após concluir essa análise. Assim, o título já estará disponível quando o script tentar localizá-lo. Mantenha o arquivo separado quando várias páginas o compartilharem ou quando quiser manter o HTML e o JavaScript de forma independente.

Execute este exemplo:

console.log("JavaScript loaded");

Este pequeno exemplo de JavaScript ilustra, de forma independente, um script que produz uma mensagem no console do navegador. Na página, app.js pode usar document.querySelector("#message") e, se o elemento existir, definir seu textContent como "JavaScript is connected". Esse texto será exibido em inglês e permanece assim porque o exemplo é preservado sem alterações. Essa atualização protegida do DOM é uma adaptação para a página, não um resultado de execução alegado.

Adicionar JavaScript diretamente a uma página HTML

Para um comportamento simples usado em apenas uma página, escreva o JavaScript diretamente dentro de um elemento <script>. Coloque esse elemento depois da marcação de que ele precisa, geralmente logo antes de </body>:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

<body>
  <h1 id="message">Waiting for JavaScript</h1>
  <script>
    const message = document.querySelector("#message");
    if (message) {
      message.textContent = "Inline JavaScript is connected";
    }
  </script>
</body>

O navegador chega ao script depois de analisar o título, então a busca consegue encontrá-lo. O código em linha é prático para uma pequena ação específica da página; à medida que o código cresce, um arquivo externo fica mais fácil de reutilizar, armazenar em cache e manter. Não use document.write para atualizações comuns da página: depois da análise do documento, ele pode substituir a página inteira. Para alterar um elemento com segurança, use métodos do DOM, como textContent.

Escolher quando os scripts externos são executados

Um script externo comum no <head> pausa a análise do HTML enquanto é baixado e executado. Se ele tentar consultar imediatamente um elemento do corpo da página, esse elemento ainda não terá sido analisado. Um script próximo ao fim de <body> é executado depois que a marcação anterior foi analisada, o que pode ser adequado para uma página pequena; ainda assim, o navegador pausa a análise enquanto carrega e executa esse script.

Para arquivos que normalmente dependem do DOM, <script src="./app.js" defer></script> no <head> é uma opção padrão clara. Scripts externos com defer são baixados em paralelo à análise do HTML e, em seguida, executados após a análise, na ordem em que aparecem no documento. Se um arquivo com defer depender de outro, liste primeiro a dependência. defer se aplica a scripts externos; adicioná-lo a um script em linha não adia sua execução.

Use <script src="./analytics.js" async></script> quando o arquivo for independente, como um script de análise de dados autônomo. Ele é baixado em paralelo e executado assim que estiver pronto, o que pode ocorrer antes do fim da análise do HTML. Scripts com async não têm ordem de execução garantida e podem rodar antes que os elementos da página existam. Por isso, não use essa opção para scripts que dependem uns dos outros ou do DOM já analisado. async e defer se aplicam a scripts externos; nos navegadores modernos, se ambos estiverem presentes, o comportamento de async tem precedência.

Verificar o caminho do script e o comportamento da página

Se nada acontecer, confira primeiro o valor exato de src e onde a página HTML está sendo servida. Abra as ferramentas de desenvolvedor do navegador e examine, no painel Network, a solicitação do script: uma resposta de não encontrado geralmente indica um caminho, nome de arquivo ou uso de maiúsculas e minúsculas incorreto. O painel Console mostra erros de sintaxe e de execução do JavaScript. Depois de corrigir o problema, recarregue a página para consultar a solicitação e as mensagens atuais.

Se a solicitação for concluída, mas a página não mudar, verifique se o script procura o ID correto do elemento e se é executado depois que a marcação necessária existe. Adicione defer a um script externo que dependa do DOM e esteja no <head>, ou mova um script curto em linha para depois do elemento. Se vários scripts interagirem, prefira arquivos com defer listados na ordem das dependências, em vez de carregá-los com async. Um download bem-sucedido apenas confirma que o navegador encontrou o arquivo; não confirma que o script foi executado sem erros.

Perguntas frequentes

Onde devo colocar o link para um arquivo JavaScript? Para um script externo típico que usa o DOM da página, coloque-o no <head> com defer. Um script no fim do corpo também pode acessar a marcação anterior, enquanto um script comum no <head> é executado antes que o corpo seja analisado.

O que defer faz? Ele baixa um script externo sem pausar a análise do HTML e o executa depois que ela termina, na ordem em que os scripts com defer aparecem.

Uma página pode vincular vários arquivos JavaScript? Sim. Adicione um elemento <script src="..." defer></script> para cada arquivo. Os arquivos com defer são executados na ordem do documento; por isso, liste as dependências compartilhadas antes dos arquivos que as utilizam.

Qual é a diferença entre async e defer? Ambos permitem downloads em paralelo. defer espera a conclusão da análise do HTML e preserva a ordem do documento; async executa cada arquivo assim que estiver pronto e não preserva essa ordem.

Preciso de type="text/javascript"? Não. No HTML5, JavaScript é o tipo padrão de um elemento de script, então type não é necessário para JavaScript comum.