Jamdesk Documentation logo

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

PropTipoPadrãoDescrição
idstringnenhumObrigatória. O ID do vídeo do YouTube.
titlestring"Play" / "YouTube Short"Rótulo de acessibilidade da incorporação. Leitores de tela usam este texto.
startnumber0Inicia a reprodução a este número de segundos no vídeo.
shortbooleanfalseRenderiza 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 é dQw4w9WgXcQ
  • youtu.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

DetalheComo é renderizado
LarguraLimitada a 360px e centralizada (corresponde à largura do player de Shorts móvel do próprio YouTube)
Proporção9:16 via aspect-ratio em CSS, para que o contêiner escale bem em telas menores
CantosArredondados com border-radius, para manter consistência com outras incorporações de mídia do Jamdesk
Vídeos relacionadosDesativados 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.

O que vem a seguir?

Imagens

Imagens em Markdown, dimensões e legendas

Vídeos

Arquivos MP4 e WebM locais

iFrames

Vimeo, CodePen, Figma e outros