API de Referência
APIs

preload - This feature is available in the latest Canary

Canary

A função preload está atualmente disponível apenas nos canais Canary e experimentais do React. Saiba mais sobre os canais de lançamento do React aqui.

Note

Os frameworks baseados em React frequentemente gerenciam o carregamento de recursos para você, então talvez você não precise chamar esta API você mesmo. Consulte a documentação do seu framework para detalhes.

preload permite que você busque de forma antecipada um recurso, como uma folha de estilos, uma fonte ou um script externo que você espera usar.

preload("https://example.com/font.woff2", {as: "font"});

Referência

preload(href, options)

Para pré-carregar um recurso, chame a função preload de react-dom.

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/font.woff2", {as: "font"});
  // ...
}

Veja mais exemplos abaixo.

A função preload fornece ao navegador uma dica de que ele deve começar a baixar o recurso dado, o que pode economizar tempo.

Parâmetros

  • href: uma string. A URL do recurso que você deseja baixar.
  • options: um objeto. Contém as seguintes propriedades:
    • as: uma string obrigatória. O tipo de recurso. Seus valores possíveis são audio, document, embed, fetch, font, image, object, script, style, track, video, worker.
    • crossOrigin: uma string. A política de CORS a ser usada. Seus valores possíveis são anonymous e use-credentials. É obrigatória quando as é definido como "fetch".
    • referrerPolicy: uma string. O cabeçalho Referrer a ser enviado ao buscar. Seus valores possíveis são no-referrer-when-downgrade (o padrão), no-referrer, origin, origin-when-cross-origin e unsafe-url.
    • integrity: uma string. Um hash criptográfico do recurso, para verificar sua autenticidade.
    • type: uma string. O tipo MIME do recurso.
    • nonce: uma string. Um nonce criptográfico para permitir o recurso ao usar uma Política de Segurança de Conteúdo rigorosa.
    • fetchPriority: uma string. Sugere uma prioridade relativa para buscar o recurso. Os valores possíveis são auto (o padrão), high e low.
    • imageSrcSet: uma string. Para ser usado apenas com as: "image". Especifica o conjunto de fontes da imagem.
    • imageSizes: uma string. Para ser usado apenas com as: "image". Especifica os tamanhos da imagem.

Retornos

preload não retorna nada.

Ressalvas

  • Múltiplas chamadas equivalentes a preload têm o mesmo efeito que uma única chamada. Chamadas a preload são consideradas equivalentes de acordo com as seguintes regras:
    • Duas chamadas são equivalentes se tiverem o mesmo href, exceto:
    • Se as for definido como image, duas chamadas são equivalentes se tiverem o mesmo href, imageSrcSet e imageSizes.
  • No navegador, você pode chamar preload em qualquer situação: enquanto renderiza um componente, em um Effect, em um manipulador de eventos etc.
  • Na renderização do lado do servidor ou ao renderizar Componentes do Servidor, preload só tem efeito se você chamá-lo enquanto renderiza um componente ou em um contexto assíncrono originado da renderização de um componente. Quaisquer outras chamadas serão ignoradas.

Uso

Pré-carregando ao renderizar

Chame preload ao renderizar um componente se você souber que ele ou seus filhos usarão um recurso específico.

Exemplos de pré-carregamento

Example 1 of 4:
Pré-carregando um script externo 

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/script.js", {as: "script"});
  return ...;
}

Se você quiser que o navegador comece a executar o script imediatamente (em vez de apenas baixá-lo), use preinit em vez disso. Se você quiser carregar um módulo ESM, use preloadModule.

Pré-carregando em um manipulador de eventos

Chame preload em um manipulador de eventos antes de transitar para uma página ou estado onde recursos externos serão necessários. Isso inicia o processo mais cedo do que se você o chamasse durante a renderização da nova página ou estado.

import { preload } from 'react-dom';

function CallToAction() {
  const onClick = () => {
    preload("https://example.com/wizardStyles.css", {as: "style"});
    startWizard();
  }
  return (
    <button onClick={onClick}>Iniciar Assistente</button>
  );
}
PreviouspreinitModule
NextpreloadModule