jQuery / Método / .load() - Carregar HTML em um elemento

No jQuery, .load(url, complete) busca HTML de forma assíncrona e substitui o conteúdo interno dos alvos. Adicione espaço e seletor, como .load("fragment.html #card", complete), para inserir uma parte. Trate o resultado no callback, sem presumir que chegou na linha seguinte.

Alvo, retorno e preparação

O alvo da API de .load() é um contêiner existente. O exterior permanece e o conteúdo muda. Uma seleção vazia não envia requisição. O retorno é o objeto jQuery original, não jqXHR nem a string HTML recebida.

Use o arquivo completo do download oficial: slim exclui Ajax. Ajax comunica sem reabrir a página inteira. .load(url) para HTML difere do antigo atalho de evento de carregamento de imagens.

Crie dois arquivos em uma pasta nova de prática. Abra via HTTP, não file://. A política de mesma origem compara esquema, host e porta; ambos usam um servidor aqui. Não misture localhost, 127.0.0.1 ou portas diferentes.

Exemplo completo com dois arquivos

Salve primeiro fragment.html em UTF-8. O cartão e o parágrafo externo são distintos. O script inofensivo só conta execuções; não o substitua por código externo arbitrário.

<section id="card">
  <h2>Local fragment</h2>
  <p>This card came from fragment.html.</p>
  <button type="button" class="fragment-action">Count a delegated click</button>
</section>
<p id="outside">Outside the selected card</p>
<script>window.fragmentRuns = (window.fragmentRuns || 0) + 1;</script>

Salve load-demo.html na mesma pasta. #panel existe antes da requisição. Os controles são desabilitados até concluir para evitar duplicatas e restauração durante requisições. this em complete identifica cada alvo receptor.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Load local HTML into a target</title>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
  <style>
    body { font: 16px/1.6 sans-serif; max-width: 760px; margin: 24px auto; padding: 16px; }
    button { font: inherit; margin: 4px; max-width: 100%; }
    #panel { padding: 12px; border: 1px solid teal; min-height: 60px; }
    pre { white-space: pre-wrap; overflow-wrap: anywhere; }
  </style>
</head>
<body>
  <h1>Load a complete response or selected fragment</h1>
  <button type="button" id="selected">Load #card only</button>
  <button type="button" id="whole">Load whole fragment</button>
  <button type="button" id="error">Request missing file</button>
  <button type="button" id="reset">Reset</button>
  <div id="panel">Initial content</div>
  <p id="clicks">delegated clicks=0</p>
  <pre id="status" aria-live="polite">Ready</pre>
  <script>
    $(function () {
      let busy = false, clicks = 0;
      window.fragmentRuns = 0;
      function load(url) {
        if (busy) return;
        busy = true;
        $("#selected, #whole, #error, #reset").prop("disabled", true);
        $("#status").text("Loading...");
        $("#panel").load(url, function (response, textStatus, xhr) {
          if (textStatus === "error") $(this).text("Load failed; try again.");
          $("#status").text(`status=${textStatus}; HTTP=${xhr.status}\nscript runs=${window.fragmentRuns}`);
          busy = false;
          $("#selected, #whole, #error, #reset").prop("disabled", false);
        });
      }
      $("#selected").on("click", function () { load("fragment.html #card"); });
      $("#whole").on("click", function () { load("fragment.html"); });
      $("#error").on("click", function () { load("missing-fragment.html"); });
      $("#panel").on("click.loadLesson", ".fragment-action", function () { clicks++; $("#clicks").text(`delegated clicks=${clicks}`); });
      $("#reset").on("click", function () {
        $("#panel").text("Initial content"); window.fragmentRuns = 0; clicks = 0;
        $("#clicks").text("delegated clicks=0"); $("#status").text("Ready");
      });
    });
  </script>
</body>
</html>

Saída inicial antes da requisição:

Ready

Com Python 3 instalado, abra um terminal na pasta e execute isto. Se python não for encontrado, confira instalação e caminho. Se 8000 estiver ocupada, use 8001 e altere também o endereço no navegador.

python -m http.server 8000 --bind 127.0.0.1

Com o servidor ativo, abra http://127.0.0.1:8000/load-demo.html. Também é preciso Internet para a rede de distribuição de conteúdo (CDN) do jQuery. Ao terminar, pare o servidor com Ctrl+C. O exemplo executou com 3.7.1, 4.0.0, Windows Edge e Python http.server; somente a porta de verificação foi trocada por uma disponível.

Comparar fragmento, resposta inteira e erro

1. Load #card only insere Local fragment e o cartão. status=success; HTTP=200, script runs=0. O parágrafo externo não aparece.
2. Count a delegated click aumenta delegated clicks por um manipulador registrado uma vez em #panel.
3. Load whole fragment inclui o parágrafo externo e aumenta script runs em um, conforme o comportamento explicado abaixo.
4. Request missing file produz status=error; HTTP=404. Exibe texto fixo com .text(), não HTML da resposta de erro.
5. Load #card only permite tentar novamente. Reset restaura conteúdo e contadores sem registrar outra delegação.

O espaço de "fragment.html #card" introduz um seletor no cliente, diferente do hash "fragment.html#card". O próprio #card e seus filhos entram em #panel. Todo o HTML é baixado antes de selecionar, sem redução automática do volume. Sem correspondência, o conteúdo pode ficar vazio apesar do sucesso HTTP.

Scripts, eventos e GET versus POST

A API documenta que scripts podem executar durante processamento sem seletor; com seletor adicionado, blocos script são removidos antes da inserção. Os botões verificam isso pelo contador. Não é sanitização de todo HTML perigoso. Insira conteúdo confiável e inicialize em complete ou função explícita.

Manipuladores diretos dos filhos antigos não passam automaticamente aos novos. O exemplo delega a partir de #panel mantido. Repetir os mesmos id em vários alvos gera duplicatas: confira modelos. complete executa por alvo; evite duplicar trabalho global.

Dados como objeto fazem usar POST; nos demais casos, GET. O servidor estático Python serve esta prática HTML GET, não um backend POST. Confira o servidor antes de adicionar objeto. Inserir HTML também difere de analisar JSON.

Leitura antecipada ou requisição ausente

Confira requisição, status e resposta em Network. Ler #panel logo após load pode mostrar conteúdo antigo; ações posteriores pertencem a complete. URLs relativas dependem da página atual: confira pastas e servidor.

Sem requisição, confira .length, arquivo completo e erros de script. Outras origens podem exigir permissões adequadas do servidor; não desative a segurança do navegador. Para cancelamento, timeout e controle detalhado, use jQuery.ajax() que retorna a requisição. Não espere .abort() no retorno de load.