Incorporamenti YouTube
Incorpora video e Shorts di YouTube nella documentazione con caricamento differito, tempi di avvio personalizzati e formato verticale 9:16.
Il componente <YouTube> incorpora video con caricamento differito, angoli arrotondati e senza l'ingombro dei video correlati. Al caricamento della pagina mostra una miniatura e un pulsante di riproduzione, quindi sostituisce questi elementi con il player YouTube completo quando l'utente fa clic.
Incorporare un video YouTube
Passa l'ID del video come prop id:
<YouTube id="dQw4w9WgXcQ" />L'iframe non viene caricato finché il visitatore non fa clic su Riproduci. La pagina rimane veloce perché il componente utilizza lite-youtube-embed: una miniatura e pochi kilobyte di CSS invece del bundle dell'iframe YouTube da oltre 800 KB.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | none | Obbligatorio. L'ID del video YouTube. |
title | string | "Play" / "YouTube Short" | Etichetta di accessibilità per l'incorporamento. Gli screen reader utilizzano questo testo. |
start | number | 0 | Avvia la riproduzione dopo questo numero di secondi dall'inizio del video. |
short | boolean | false | Esegue il rendering come YouTube Short verticale 9:16 invece che come video 16:9. |
Iniziare da un momento specifico
La prop start passa a un determinato timestamp (in secondi) quando inizia la riproduzione:
<YouTube id="dQw4w9WgXcQ" start={60} />La riproduzione inizia al minuto 1. I valori decimali vengono arrotondati per difetto ai secondi interi.
Trovare l'ID del video
L'ID del video è la stringa dopo v= in un URL YouTube.
youtube.com/watch?v=dQw4w9WgXcQ→ l'ID èdQw4w9WgXcQyoutu.be/dQw4w9WgXcQ→ l'ID èdQw4w9WgXcQ
Copia l'ID, non l'URL completo.
YouTube Shorts
Gli YouTube Shorts sono video verticali con proporzioni 9:16. Incorporare uno Short in un player standard 16:9 aggiunge spesse bande nere su entrambi i lati: il video viene compresso in un formato letterbox pensato per i contenuti orizzontali.
La prop short risolve il problema. Esegue il rendering dell'incorporamento in formato 9:16, centrato nella pagina e largo 360 px, con angoli arrotondati. Il risultato corrisponde all'aspetto degli Shorts sui dispositivi mobili.
Come incorporare uno Short
<YouTube id="_6HzLIJPH2A" short />Trovare l'ID dello Short
L'ID dello Short è il segmento del percorso dopo /shorts/ nell'URL:
youtube.com/shorts/_6HzLIJPH2A→ l'ID è_6HzLIJPH2A
Questi ID seguono lo stesso formato di 11 caratteri dei normali video YouTube. Puoi testare qualsiasi ID di Short anche con il componente <YouTube> standard, ma senza short il rendering avviene in formato 16:9 con bande nere.
Dettagli del rendering
| Dettaglio | Modalità di rendering |
|---|---|
| Larghezza | Limitata a 360 px e centrata (corrisponde alla larghezza del player mobile Shorts di YouTube) |
| Proporzioni | 9:16 tramite CSS aspect-ratio, in modo che il contenitore si adatti correttamente agli schermi più piccoli |
| Angoli | Arrotondati con border-radius per mantenere la coerenza con gli altri incorporamenti multimediali di Jamdesk |
| Video correlati | Disabilitati tramite rel=0, come negli incorporamenti standard |
Differenze di prestazioni
Gli incorporamenti YouTube standard utilizzano lite-youtube-embed, che inizialmente non carica alcun JavaScript di YouTube. La pagina mostra una miniatura; l'iframe del player completo viene caricato solo quando il visitatore fa clic su Riproduci.
Gli Shorts funzionano in modo diverso. Poiché lite-youtube-embed non supporta le proporzioni verticali, gli Shorts utilizzano un <iframe> diretto con loading="lazy". Il browser rimanda il caricamento finché l'iframe non si avvicina all'area visibile. Quando diventa visibile, il player YouTube completo viene inizializzato, inclusi script, stili e tutti gli altri elementi.
In una pagina con uno o due Shorts, la differenza è trascurabile. In una pagina con molti Shorts, gli iframe aggiuntivi hanno un impatto concreto. Se incorpori più di tre o quattro Shorts in una pagina, valuta di collegarti direttamente agli Shorts oppure di inserirli dietro una scheda per mantenere leggero il caricamento iniziale.
Utilizzare direttamente gli iFrame
Quando hai bisogno del pieno controllo sui parametri dell'incorporamento, puoi utilizzare un iframe non elaborato:
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/VIDEO_ID"
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>Il componente <YouTube> è la scelta predefinita migliore. Carica il player in modo differito, rimuove i video correlati e gestisce le proporzioni degli Shorts. Utilizza gli iframe non elaborati solo quando ti servono parametri di incorporamento che il componente non espone.