Incorporações do YouTube
Incorpore vídeos e Shorts do YouTube na sua documentação. Player com carregamento lento, horários de início personalizados e Shorts verticais 9:16.
O componente <YouTube> incorpora vídeos com carregamento lento, cantos arredondados e sem a poluição de vídeos relacionados. Ao carregar a página, ele exibe uma miniatura e um botão de play. O player completo do YouTube só é carregado após o clique.
Incorporar um vídeo do YouTube
Passe o ID do vídeo como a prop id:
<YouTube id="dQw4w9WgXcQ" />
Nenhum iframe é carregado até que o visitante clique em play. O componente usa o lite-youtube-embed: uma imagem de miniatura e alguns kilobytes de CSS, em vez do pacote de iframe do YouTube com mais de 800KB.
Propriedades
| Prop | Tipo | Padrão | Descrição |
|---|---|---|---|
id | string | nenhum | Obrigatória. O ID do vídeo do YouTube. |
title | string | "Play" / "YouTube Short" | Rótulo de acessibilidade da incorporação. Leitores de tela usam este texto. |
start | number | 0 | Inicia a reprodução a este número de segundos no vídeo. |
short | boolean | false | Renderiza como um YouTube Short vertical 9:16 em vez de um vídeo 16:9. |
Iniciar em um momento específico
A prop start pula para um marco de tempo (em segundos) quando a reprodução começa:
<YouTube id="dQw4w9WgXcQ" start={60} />
A reprodução começa no minuto 1. Valores decimais são arredondados para baixo até segundos inteiros.
Encontrar o ID do vídeo
O ID do vídeo é a string após v= em uma URL do YouTube.
youtube.com/watch?v=dQw4w9WgXcQ→ o ID édQw4w9WgXcQyoutu.be/dQw4w9WgXcQ→ o ID édQw4w9WgXcQ
Copie o ID, não a URL completa.
YouTube Shorts
Os YouTube Shorts são vídeos verticais com proporção 9:16. Incorporar um Short em um player 16:9 padrão adiciona barras pretas grossas dos dois lados.
A prop short resolve isso. Ela renderiza a incorporação em 9:16, centralizada na página com 360px de largura e cantos arredondados. O resultado corresponde à forma como os Shorts aparecem no celular.
Como incorporar um Short
<YouTube id="_6HzLIJPH2A" short />
Encontrar o ID do Short
O ID do Short é o segmento do caminho após /shorts/ na URL:
youtube.com/shorts/_6HzLIJPH2A→ o ID é_6HzLIJPH2A
Esses IDs seguem o mesmo formato de 11 caracteres dos vídeos regulares do YouTube. Sem short, o componente <YouTube> renderiza um Short em 16:9 com barras pretas.
Detalhes de renderização
| Detalhe | Como é renderizado |
|---|---|
| Largura | Limitada a 360px e centralizada (corresponde à largura do player de Shorts móvel do próprio YouTube) |
| Proporção | 9:16 via aspect-ratio em CSS, para que o contêiner escale bem em telas menores |
| Cantos | Arredondados com border-radius, para manter consistência com outras incorporações de mídia do Jamdesk |
| Vídeos relacionados | Desativados via rel=0, igual às incorporações padrão |
Diferença de desempenho
As incorporações padrão do YouTube usam o lite-youtube-embed. Ele não carrega JavaScript do YouTube antecipadamente. A página exibe uma imagem de miniatura. O iframe do player completo só é carregado quando um visitante clica em play.
O lite-youtube-embed não consegue renderizar proporções verticais. Os Shorts usam um <iframe> direto com loading="lazy". O navegador adia o carregamento até que o iframe se aproxime da área visível. O player completo do YouTube (scripts, estilos e tudo mais) é inicializado quando o iframe fica visível.
Um ou dois Shorts em uma página fazem diferença negligenciável. Muitos Shorts adicionam peso por causa dos iframes extras. Crie links para eles ou coloque-os atrás de uma aba quando a página tiver mais de três ou quatro Shorts. Isso mantém o carregamento inicial leve.
Usar iFrames diretamente
Use um iframe puro para ter controle total sobre os parâmetros da incorporação:
<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
/>
O componente <YouTube> é o padrão recomendado. Ele faz carregamento lento do player, remove vídeos relacionados e renderiza Shorts em 9:16. Use iframes puros apenas quando precisar de parâmetros de incorporação que o componente não expõe.
