Salta ai contenuti

Precaricamento

I tempi di caricamento delle pagine giocano un ruolo importante nell’usabilità e nel piacere generale di un sito. Il precaricamento opzionale di Astro porta i benefici di navigazioni tra pagine quasi istantanee alla tua applicazione a pagine multiple (MPA) mentre i tuoi visitatori interagiscono con il sito.

Abilitare il precaricamento

Sezione intitolata Abilitare il precaricamento

Puoi abilitare il precaricamento con la configurazione prefetch:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  prefetch: true
});

Uno script di precaricamento verrà aggiunto a tutte le pagine del tuo sito. Puoi quindi aggiungere l’attributo data-astro-prefetch a qualsiasi link <a /> nel tuo sito per abilitare il precaricamento. Quando passi il mouse sopra il link, lo script recupererà la pagina in background.

<a href="/about" data-astro-prefetch>

Nota che il precaricamento funziona solo per i link all’interno del tuo sito, non per i link esterni.

Configurazione del precaricamento

Sezione intitolata Configurazione del precaricamento

La configurazione prefetch accetta anche un “oggetto opzioni” per personalizzare ulteriormente il precaricamento.

Strategie di precaricamento

Sezione intitolata Strategie di precaricamento

Astro supporta 4 strategie di precaricamento per vari casi d’uso:

  • hover (default): Prefetch quando passi il mouse sopra o metti a fuoco il link.
  • tap: Prefetch poco prima di cliccare sul link.
  • viewport: Prefetch mentre i link entrano nel viewport.
  • load: Prefetch di tutti i link della pagina dopo il caricamento della pagina.

Puoi specificare una strategia per un singolo link passandolo all’attributo data-astro-prefetch:

<a href="/about" data-astro-prefetch="tap">About</a>

Ogni strategia è ottimizzata per prefetchare solo quando necessario e risparmiare banda ai tuoi utenti. Per esempio:

  • Se un visitatore sta usando la modalità risparmio dati o ha una connessione lenta, il precaricamento passerà alla strategia tap.
  • Passare velocemente il mouse o scorrere sui link non li precaricherà.
  • I link che usano le strategie viewport o load vengono precaricati con priorità inferiore per evitare di intasare la rete.

Strategia di precaricamento predefinita

Sezione intitolata Strategia di precaricamento predefinita

La strategia di precaricamento predefinita quando si aggiunge l’attributo data-astro-prefetch è hover. Per cambiarla, puoi configurare prefetch.defaultStrategy nel tuo file astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  prefetch: {
    defaultStrategy: 'viewport'
  }
});
Sezione intitolata Precaricamento di tutti i link di default

Se vuoi precaricare tutti i link, inclusi quelli senza l’attributo data-astro-prefetch, puoi impostare prefetch.prefetchAll a true:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  prefetch: {
    prefetchAll: true
  }
});

Puoi quindi escludere il precaricamento per singoli link impostando data-astro-prefetch="false":

<a href="/about" data-astro-prefetch="false">About</a>

La strategia di precaricamento predefinita per tutti i link può essere cambiata con prefetch.defaultStrategy come mostrato nella sezione Strategia di precaricamento predefinita.

Precarica programmaticamente

Sezione intitolata Precarica programmaticamente

Siccome alcune navigazioni potrebbero non apparire sempre come link <a />, puoi anche precaricare programmaticamente con l’API prefetch() dal modulo astro:prefetch:

<button id="btn">Cliccami</button>


<script>
  import { prefetch } from 'astro:prefetch';


  const btn = document.getElementById('btn');
  btn.addEventListener('click', () => {
    prefetch('/about');
  });
</script>

Puoi inoltre configurare la priorità del precaricamento passando l’opzione with:

// Precaricamento con `fetch()`, che ha una priorità più alta.
prefetch('/about', { with: 'fetch' });


// Precaricamento con `<link rel="prefetch">`, che ha una priorità inferiore
// e viene pianificato manualmente dal browser. (default)
prefetch('/about', { with: 'link' });

L’API prefetch() include la stessa rilevazione di modalità risparmio dati e connessione lenta in modo che il precaricamento avvenga solo quando necessario.

Per ignorare il rilevamento di connessioni lente, puoi usare l’opzione ignoreSlowConnection:

// Precarica anche in modalità risparmio dati o connessione lenta
prefetch('/about', { ignoreSlowConnection: true });

Assicurati di importare prefetch() solo negli script lato client poiché fa affidamento sulle API del browser.

Usarlo con le View Transitions

Sezione intitolata Usarlo con le View Transitions

Quando usi le View Transitions in una pagina, il precaricamento verrà abilitato di default. Imposta una configurazione predefinita di { prefetchAll: true } che abilita il precaricamento per tutti i link nella pagina.

Puoi personalizzare la configurazione di precaricamento in astro.config.mjs per sovrascrivere il valore di default. Per esempio:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  // Disabilita completamente il precaricamento
  prefetch: false
});
astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  // Mantieni il precaricamento, ma solo per i link con `data-astro-prefetch`
  prefetch: {
    prefetchAll: false
  }
});

Migrazione da @astrojs/prefetch

Sezione intitolata Migrazione da @astrojs/prefetch

L’integrazione @astrojs/prefetch è stata deprecata nella v3.5.0 e verrà rimossa completamente. Usa le seguenti istruzioni per passare al precaricamento integrato di Astro che sostituisce questa integrazione.

  1. Rimuovi l’integrazione @astrojs/prefetch e abilita la configurazione prefetch in astro.config.mjs:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import prefetch from '@astrojs/prefetch';
    

    export default defineConfig({
      integrations: [prefetch()],
      prefetch: true
    });

  2. Converti dalle opzioni di configurazione di @astrojs/prefetch:

    • L’integrazione deprecata usava l’opzione selector per specificare quali link dovrebbero essere precaricati quando entrano nel viewport.

      Aggiungi invece data-astro-prefetch="viewport" a questi singoli link

      <a href="/about" data-astro-prefetch="viewport">

    • L’integrazione deprecata usava l’opzione intentSelector per specificare quali link dovrebbero essere precaricati quando venivano passati sopra col mouse o messi a fuoco.

      Aggiungi data-astro-prefetch o data-astro-prefetch="hover" a questi singoli link:

      <!-- Puoi omettere il valore se `defaultStrategy` è impostato a `hover` (default) -->
      <a href="/about" data-astro-prefetch>
      

      <!-- Altrimenti, puoi definire esplicitamente la strategia di precaricamento -->
      <a href="/about" data-astro-prefetch="hover">

    • L’opzione throttles di @astrojs/prefetch non è più necessaria poiché la nuova funzionalità di prefetch pianificherà e precaricherà in modo ottimale automaticamente.