Video

Apresentação

O componente Video permite a exibição de conteúdo de vídeo em diferentes formatos, incluindo vídeos locais, vídeos do YouTube e vídeos do Vimeo. Ele oferece controles personalizáveis e suporte a diferentes configurações de reprodução. O componente estende BaseComponent e fornece métodos públicos para controle programático através de refs.

Quando usar

Para exibir vídeos locais em formatos como MP4
Para incorporar vídeos do YouTube
Para incorporar vídeos do Vimeo
Quando precisar de controles personalizados de vídeo
Para criar uma experiência de vídeo responsiva
Quando precisar controlar o vídeo programaticamente através de refs

Forma básica de uso

import { Video } from 'eitri-luminus';

// Vídeo local básico
<Video
  source="/caminho/do/video.mp4"
  width="100%"
  height="400px"
  controls
/>

// Vídeo do YouTube (aceita ID ou URL completa)
<Video
  youTubeId="dQw4w9WgXcQ"
  width="100%"
  height="400px"
/>

// Vídeo do YouTube usando URL completa
<Video
  youTubeId="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  width="100%"
  height="400px"
/>

// Vídeo do Vimeo (só é usado quando YouTube não está presente)
<Video
  vimeoId="148751763"
  width="100%"
  height="400px"
/>

// Vídeo com thumbnail e autoplay
<Video
  source="/caminho/do/video.mp4"
  thumbnail="/caminho/da/thumbnail.jpg"
  autoPlay
  muted
  width="100%"
  height="400px"
/>

Propriedades

Propriedade	Tipo	Descrição
`source`	`string`	URL do arquivo de vídeo local (apenas para vídeos locais)
`width`	`string \| number`	Largura do vídeo
`height`	`string \| number`	Altura do vídeo
`controls`	`boolean`	Exibe os controles de vídeo (play, pause, volume, etc)
`autoPlay`	`boolean`	Inicia a reprodução automaticamente
`muted`	`boolean`	Inicia o vídeo sem som
`thumbnail`	`string`	URL da imagem de preview do vídeo (apenas para vídeos locais)
`type`	`string`	Tipo do arquivo de vídeo (ex: 'video/mp4') - apenas para vídeos locais
`youTubeId`	`string`	ID do vídeo do YouTube ou URL completa do YouTube para incorporação. O componente detecta automaticamente se é uma URL e extrai o ID. Formatos suportados: `VIDEO_ID`, `https://www.youtube.com/watch?v=VIDEO_ID`, `https://youtu.be/VIDEO_ID`, `https://www.youtube.com/embed/VIDEO_ID`. Tem prioridade sobre Vimeo. Quando fornecido, todos os métodos de controle funcionam.
`vimeoId`	`string`	ID do vídeo do Vimeo para incorporação. Só é usado quando `youTubeId` não está presente. Quando fornecido, todos os métodos de controle funcionam.
`loop`	`boolean`	Reproduz o vídeo em loop
`playsInline`	`boolean`	Reproduz o vídeo inline (padrão: true)

Eventos

O componente Video suporta eventos do elemento HTML <video> para vídeos locais e eventos compatíveis para vídeos do YouTube e Vimeo. Todos os eventos recebem um objeto React.SyntheticEvent<HTMLVideoElement, Event>.

Nota: Alguns eventos são específicos de vídeos locais (como onLoadStart, onLoadedData, onLoadedMetadata, onCanPlay, onCanPlayThrough, onProgress, onSeeking, onSeeked, onWaiting, onPlaying, onVolumeChange, onRateChange, onDurationChange, onAbort, onSuspend, onStalled, onEmptied). Para vídeos do YouTube e Vimeo, os eventos principais (onPlay, onPause, onEnded, onTimeUpdate, onError) são mapeados e funcionam normalmente.

Eventos de Carregamento

onLoadStart: Disparado quando o navegador começa a buscar o vídeo
onLoadedData: Disparado quando os dados do vídeo foram carregados
onLoadedMetadata: Disparado quando os metadados foram carregados (duração, dimensões, etc)
onCanPlay: Disparado quando o vídeo pode começar a reproduzir
onCanPlayThrough: Disparado quando o vídeo pode reproduzir até o fim sem pausar

Eventos de Reprodução

onPlay: Disparado quando a reprodução começa
onPause: Disparado quando a reprodução é pausada
onEnded: Disparado quando a reprodução termina
onPlaying: Disparado quando o vídeo começa a reproduzir após estar pausado ou esperando
onWaiting: Disparado quando o vídeo está esperando por mais dados

Eventos de Tempo

onTimeUpdate: Disparado quando o tempo de reprodução atualiza
onSeeking: Disparado quando o usuário está buscando uma nova posição
onSeeked: Disparado quando a busca por uma nova posição foi concluída
onDurationChange: Disparado quando a duração do vídeo muda

Eventos de Progresso

onProgress: Disparado durante o carregamento do vídeo

Eventos de Controle

onVolumeChange: Disparado quando o volume ou estado de mudo muda
onRateChange: Disparado quando a velocidade de reprodução muda

Eventos de Erro

onError: Disparado quando ocorre um erro no carregamento ou reprodução
onAbort: Disparado quando o carregamento foi abortado
onSuspend: Disparado quando o carregamento foi suspenso
onStalled: Disparado quando o carregamento travou
onEmptied: Disparado quando o elemento de vídeo foi esvaziado

Exemplo de uso de eventos

<Video
  source="/video.mp4"
  onPlay={(e) => console.log('Vídeo iniciado')}
  onPause={(e) => console.log('Vídeo pausado')}
  onTimeUpdate={(e) => {
    const video = e.currentTarget;
    console.log(`Tempo atual: ${video.currentTime}s`);
  }}
  onEnded={(e) => console.log('Vídeo terminou')}
  onError={(e) => console.error('Erro no vídeo', e)}
/>

Controle através de Ref

O componente Video estende BaseComponent e expõe métodos públicos que podem ser acessados através de uma ref. Isso permite controle programático completo do vídeo.

Criando uma ref

import React, { useRef } from 'react';
import { Video } from 'eitri-luminus';

function MyComponent() {
  const videoRef = useRef(null);

  return (
    <Video
      ref={videoRef}
      source="/video.mp4"
    />
  );
}

Métodos disponíveis

Reprodução

play(): Promise<void> - Reproduz o vídeo
pause(): void - Pausa o vídeo
load(): void - Recarrega o vídeo

Tempo

getCurrentTime(): number - Retorna o tempo atual de reprodução em segundos
setCurrentTime(time: number): void - Define o tempo de reprodução em segundos
getDuration(): number - Retorna a duração total do vídeo em segundos

Estado

getPaused(): boolean - Retorna se o vídeo está pausado
getEnded(): boolean - Retorna se o vídeo terminou

Áudio

getMuted(): boolean - Retorna se o vídeo está mudo
setMuted(muted: boolean): void - Define se o vídeo está mudo
getVolume(): number - Retorna o volume do vídeo (0.0 a 1.0)
setVolume(volume: number): void - Define o volume do vídeo (0.0 a 1.0)

Utilitários

getVideoElement(): HTMLVideoElement | HTMLIFrameElement | null - Retorna o elemento DOM do vídeo (método privado - removido da API pública)

Exemplos de uso com ref

Controle básico (Play/Pause)

import React, { useRef } from 'react';
import { Video, Button, View } from 'eitri-luminus';

function VideoPlayer() {
  const videoRef = useRef(null);

  const handlePlay = () => {
    videoRef.current?.play();
  };

  const handlePause = () => {
    videoRef.current?.pause();
  };

  return (
    <View>
      <Video
        ref={videoRef}
        source="/video.mp4"
        className="w-full"
      />
      <View className="flex gap-2 mt-4">
        <Button onClick={handlePlay}>Play</Button>
        <Button onClick={handlePause}>Pause</Button>
      </View>
    </View>
  );
}

Controle de tempo

import React, { useRef } from 'react';
import { Video, Button, View } from 'eitri-luminus';

function VideoWithSeek() {
  const videoRef = useRef(null);

  const jumpToTime = (seconds: number) => {
    videoRef.current?.setCurrentTime(seconds);
  };

  const getCurrentTime = () => {
    const time = videoRef.current?.getCurrentTime();
    console.log(`Tempo atual: ${time}s`);
  };

  return (
    <View>
      <Video
        ref={videoRef}
        source="/video.mp4"
        className="w-full"
      />
      <View className="flex gap-2 mt-4">
        <Button onClick={() => jumpToTime(30)}>Ir para 30s</Button>
        <Button onClick={() => jumpToTime(60)}>Ir para 1min</Button>
        <Button onClick={getCurrentTime}>Tempo Atual</Button>
      </View>
    </View>
  );
}

Controle de volume

import React, { useRef } from 'react';
import { Video, Button, View } from 'eitri-luminus';

function VideoWithVolume() {
  const videoRef = useRef(null);

  const toggleMute = () => {
    const isMuted = videoRef.current?.getMuted();
    videoRef.current?.setMuted(!isMuted);
  };

  const setVolume = (volume: number) => {
    videoRef.current?.setVolume(volume);
  };

  return (
    <View>
      <Video
        ref={videoRef}
        source="/video.mp4"
        className="w-full"
      />
      <View className="flex gap-2 mt-4">
        <Button onClick={toggleMute}>Alternar Mudo</Button>
        <Button onClick={() => setVolume(0.5)}>Volume 50%</Button>
        <Button onClick={() => setVolume(1.0)}>Volume 100%</Button>
      </View>
    </View>
  );
}

Monitoramento de estado

import React, { useRef, useState, useEffect } from 'react';
import { Video, View, Text } from 'eitri-luminus';

function VideoMonitor() {
  const videoRef = useRef(null);
  const [status, setStatus] = useState('');

  useEffect(() => {
    const interval = setInterval(() => {
      if (videoRef.current) {
        const paused = videoRef.current.getPaused();
        const currentTime = videoRef.current.getCurrentTime();
        const duration = videoRef.current.getDuration();
        const volume = videoRef.current.getVolume();
        const muted = videoRef.current.getMuted();

        setStatus(`
          Estado: ${paused ? 'Pausado' : 'Reproduzindo'}
          Tempo: ${currentTime.toFixed(1)}s / ${duration.toFixed(1)}s
          Volume: ${(volume * 100).toFixed(0)}%
          Mudo: ${muted ? 'Sim' : 'Não'}
        `);
      }
    }, 100);

    return () => clearInterval(interval);
  }, []);

  return (
    <View>
      <Video
        ref={videoRef}
        source="/video.mp4"
        className="w-full"
      />
      <Text render="pre" className="mt-4">
        {status}
      </Text>
    </View>
  );
}

Controle de vídeo do YouTube

import React, { useRef } from 'react';
import { Video, Button, View } from 'eitri-luminus';

function YouTubeVideoPlayer() {
  const videoRef = useRef(null);

  const handlePlay = () => {
    videoRef.current?.play();
  };

  const handlePause = () => {
    videoRef.current?.pause();
  };

  const handleSeek = (seconds: number) => {
    videoRef.current?.setCurrentTime(seconds);
  };

  const handleToggleMute = () => {
    const isMuted = videoRef.current?.getMuted();
    videoRef.current?.setMuted(!isMuted);
  };

  return (
    <View>
      <Video
        ref={videoRef}
        youTubeId="aZ-dqY9UWEo"
        width="100%"
        height="400px"
        className="w-full rounded-lg"
      />
      <View className="flex gap-2 mt-4">
        <Button onClick={handlePlay}>Play</Button>
        <Button onClick={handlePause}>Pause</Button>
        <Button onClick={() => handleSeek(10)}>Ir para 10s</Button>
        <Button onClick={() => handleSeek(30)}>Ir para 30s</Button>
        <Button onClick={handleToggleMute}>Alternar Mudo</Button>
      </View>
    </View>
  );
}

Controle de vídeo do Vimeo

import React, { useRef } from 'react';
import { Video, Button, View } from 'eitri-luminus';

function VimeoVideoPlayer() {
  const videoRef = useRef(null);

  const handlePlay = () => {
    videoRef.current?.play();
  };

  const handlePause = () => {
    videoRef.current?.pause();
  };

  const handleSeek = (seconds: number) => {
    videoRef.current?.setCurrentTime(seconds);
  };

  const handleToggleMute = () => {
    const isMuted = videoRef.current?.getMuted();
    videoRef.current?.setMuted(!isMuted);
  };

  return (
    <View>
      <Video
        ref={videoRef}
        vimeoId="148751763"
        width="100%"
        height="400px"
        className="w-full rounded-lg"
      />
      <View className="flex gap-2 mt-4">
        <Button onClick={handlePlay}>Play</Button>
        <Button onClick={handlePause}>Pause</Button>
        <Button onClick={() => handleSeek(10)}>Ir para 10s</Button>
        <Button onClick={() => handleSeek(30)}>Ir para 30s</Button>
        <Button onClick={handleToggleMute}>Alternar Mudo</Button>
      </View>
    </View>
  );
}

Observações sobre refs

Todos os métodos funcionam tanto com vídeos locais quanto com vídeos do YouTube e Vimeo
Quando um youTubeId é fornecido, o componente carrega automaticamente a API do YouTube e permite controle completo
Quando um vimeoId é fornecido (e youTubeId não está presente), o componente carrega automaticamente a API do Vimeo e permite controle completo
Todos os métodos são seguros e não lançam erros se o elemento não existir
O método play() retorna uma Promise que pode ser usada para tratamento de erros
O método getVideoElement() foi removido da API pública por questões de segurança e encapsulamento

Heranças

O componente Video herda todas as propriedades comuns da biblioteca através da interface CommonProps, que inclui:

Propriedades de estilo (margin, padding, etc)
Propriedades de layout (flex, grid, etc)
Propriedades de posicionamento
Propriedades de acessibilidade
Propriedades de identificação (id, data-e)

Observações

Para vídeos locais, é necessário fornecer a propriedade source
Para vídeos do YouTube, use a propriedade youTubeId (aceita ID ou URL completa)
O componente detecta automaticamente se youTubeId é uma URL do YouTube e extrai o ID necessário
Formatos de URL suportados: https://www.youtube.com/watch?v=VIDEO_ID, https://youtu.be/VIDEO_ID, https://www.youtube.com/embed/VIDEO_ID
Para vídeos do Vimeo, use a propriedade vimeoId
Prioridade: YouTube tem prioridade sobre Vimeo. Se ambos youTubeId e vimeoId forem fornecidos, apenas o YouTube será usado
O componente é responsivo por padrão com width="100%"
Recomenda-se sempre definir uma altura para evitar problemas de layout
Para autoplay funcionar, o vídeo deve estar mutado (muted={true})
Todos os métodos de controle funcionam tanto com vídeos locais quanto com vídeos do YouTube e Vimeo
Quando youTubeId é fornecido, o componente carrega automaticamente a API do YouTube em tempo de execução
Quando vimeoId é fornecido (e youTubeId não está presente), o componente carrega automaticamente a API do Vimeo em tempo de execução
A propriedade thumbnail funciona apenas com vídeos locais (não aplicável a vídeos do YouTube ou Vimeo)
A propriedade type funciona apenas com vídeos locais (não aplicável a vídeos do YouTube ou Vimeo)

Apresentação​

Quando usar​

Forma básica de uso​

Propriedades​

Eventos​

Eventos de Carregamento​

Eventos de Reprodução​

Eventos de Tempo​

Eventos de Progresso​

Eventos de Controle​

Eventos de Erro​

Exemplo de uso de eventos​

Controle através de Ref​

Criando uma ref​

Métodos disponíveis​

Reprodução​

Tempo​

Estado​

Áudio​

Utilitários​

Exemplos de uso com ref​

Controle básico (Play/Pause)​

Controle de tempo​

Controle de volume​

Monitoramento de estado​

Controle de vídeo do YouTube​

Controle de vídeo do Vimeo​

Observações sobre refs​

Heranças​

Observações​