Reel Player

Um player de vídeo em tela cheia no estilo Instagram Reels/TikTok, com @reelkit/react-reel-player.

Ver demonstração ao vivo →

Recursos

Instalação

Não esqueça de importar os estilos:

Início rápido

O componente ReelPlayerOverlay renderiza um player em tela cheia. Passe um array de objetos ContentItem e controle a visibilidade com isOpen.

Demonstração ao vivo

Clique em uma miniatura para abrir o player em tela cheia. Pressione Escape ou o botão de fechar para voltar.

Personalização

Tipo de conteúdo genérico

Use tipos de dados próprios estendendo BaseContentItem:

Camada própria sobre o slide

Troque a camada padrão por um conteúdo seu em cada slide:

Slides que não são mídia

Use renderSlide para inserir conteúdo próprio (cartões de chamada, por exemplo). Devolva null para cair no padrão:

Controles próprios

Componha os subcomponentes reutilizáveis com os seus acréscimos:

Linha do tempo própria

Troque a barra de reprodução padrão pela sua, com renderTimeline. O callback só é chamado quando as regras do overlay renderizariam a barra padrão (a mesma lógica de modo timeline e de timelineMinDurationSeconds), então você não precisa reimplementá-las. Reaproveite a classe .rk-reel-timeline na sua raiz para herdar o posicionamento rente à base, o respiro da área segura e o espaço reservado para a camada do slide em dispositivos de toque.

Navegação própria

Navegação aninhada própria

Troque as setas de esquerda e direita dentro dos slides com várias mídias (carrossel horizontal) por uma navegação sua:

Slides aninhados próprios

Personalize cada slide dentro dos carrosséis de várias mídias com renderNestedSlide. Use props.defaultContent para envolver o ImageSlide/VideoSlide padrão, ou substitua-o por completo:

Estado na URL

Ver demonstração ao vivo →

ReelPlayerUrlOverlay é um componente à parte cujo estado aberto vive na barra de endereços. Monte um controlador com useOverlayUrlState, de @reelkit/react, e entregue-o como controller: o player se abre quando o parâmetro nomeia um slide e se fecha quando ele some. Os links dão para compartilhar, e o botão voltar fecha o player em vez de sair da página.

As opções completas de useOverlayUrlState — param, adapter, codec, locator — estão na referência da API para React. O passo a passo está no guia para React.

• Abrir empilha uma entrada no histórico. Percorrer o feed substitui essa entrada, então N deslizes não acrescentam nenhuma e um único passo para trás sempre sai do player. Voltar fecha; não troca de slide.
• Voltar só fecha quando o player foi aberto de dentro do app — foi o link que empilhou a entrada. Um link compartilhado aberto direto em uma aba nova não tem histórico atrás de si, então o voltar do navegador sai do site; o botão ✕ ou o Escape removem o parâmetro ali mesmo e você continua na página.
• Um link direto ?reel=3 abre o player naquele slide já no carregamento.
• Um parâmetro que não nomeia slide nenhum — um favorito velho, um valor editado à mão — é retirado da URL, em vez de deixar a barra de endereços afirmando um slide que não abre.
• Por padrão o parâmetro endereça apenas o post vertical (?reel=3). Adote uma chave de dois eixos para carregar também o índice da mídia interna de um carrossel — veja abaixo.

Uma chave ou duas — escolha a profundidade da URL

O mesmo ReelPlayerUrlOverlay conduz os dois formatos; ele distingue em tempo de execução pela posição do controlador, então não existe prop de modo. Escolha a chave ao montar o controlador:

Os dois fios são deliberadamente distintos — uma chave de dois eixos é estritamente pontuada (3.0, nunca um 3 solto), então um link de um eixo não é decodificado pelo outro. Trocar a chave de um app, portanto, invalida qualquer link já compartilhado. Escolha um formato e fique com ele.

App com rotas — passe um adaptador. Escrever history.pushState por trás de um roteador deixa a localização dele desatualizada, e a navegação seguinte derruba o parâmetro:

Links estáveis. O índice é posicional, então um ?reel=3 favoritado abre outro post assim que o feed muda de ordem — e num feed isso é o normal, não a exceção. urlStableIdKey usa o id estável de cada post, varrendo o feed atual — uma chamada resolve o caso comum.

Passe hashCodec: base64UrlCodec para escrever o id em base64url na URL — é um disfarce reversível, não um hash criptográfico.

Quer endereçar por outro campo (um slug), ou paginar um feed infinito com locateAsync? Monte o codec e o locator você mesmo. São dois papéis distintos: o codec escreve a identidade na URL, o locator descobre onde ela está.

Feeds infinitos. locate é síncrono, então só responde pelos posts já carregados — um link compartilhado para o post 400 de um feed que carregou 20 volta vazio. locateAsync é o plano B, chamado somente quando locate falha.

• Enquanto locateAsync está pendente, o player fica fechado e o parâmetro é deixado em paz, então o link direto sobrevive à busca. Um null ou uma rejeição derrubam o parâmetro.
• Uma resposta que chega depois de a URL ter mudado, depois de um fechamento ou depois da desmontagem é descartada — uma busca lenta não pode abrir um slide que ninguém pediu.
• Nada é renderizado enquanto a busca corre; esse estado de carregamento já pertence à página, então desenhe o seu próprio esqueleto.
• Não existe tempo limite — o player não tem como saber o tamanho do feed. Termine com null quando a paginação se esgotar, ou o overlay fica fechado para sempre.

Referência da API

Props do ReelPlayerOverlayProps

ReelPlayerOverlayProps<T>

Props do ReelPlayerUrlOverlay

ReelPlayerUrlOverlayProps<T>

Aceita todas as props visuais e de comportamento acima, menos isOpen, substituída por controller. initialIndex é ignorada — quem escolhe o slide é a posição do controlador, então um valor passado ao lado dela é sobrescrito a cada abertura.

Callbacks

Props do Reel (repassadas)

Estas props são repassadas ao componente Reel por baixo.

Tipos

BaseContentItem

O tipo que serve de restrição genérica. Estenda-o para usar tipos de dados próprios com o ReelPlayerOverlay.

ContentItem

MediaItem

MediaType

ControlsRenderProps<T>

NavigationRenderProps

SlideRenderProps<T>

NestedSlideRenderProps

SlideOverlayProps

ImageSlideProps

VideoSlideProps

CloseButtonProps

SoundButtonProps

TimelineBarProps

TimelineRenderProps<T>

Subcomponentes

Blocos reutilizáveis exportados para você compor dentro das suas render props:

CloseButton

Botão de fechar isolado, já com o estilo do reel player. Use dentro de renderControls.

SoundButton

Botão de som isolado. Precisa estar dentro de um SoundProvider (que o ReelPlayerOverlay fornece sozinho).

TimelineBar

Barra de reprodução padrão. Lê o TimelineProvider mais próximo (montado automaticamente dentro do ReelPlayerOverlay) e desenha a trilha, os trechos em buffer, o preenchimento do progresso e a pílula de arrasto. Personalize pelas propriedades --rk-reel-timeline-*, ou substitua por renderTimeline.

SlideOverlay

A camada em gradiente padrão, que mostra autor, descrição e curtidas. Aparece sozinha quando o conteúdo tem os campos necessários. Use renderSlideOverlay para substituí-la ou escondê-la.

ImageSlide

Slide de imagem com carregamento tardio e object-fit: cover por padrão. Use dentro de renderSlide para compor slides de imagem com os seus estilos.

VideoSlide

Slide de vídeo com elemento <video> compartilhado para a continuidade do som no iOS, quadros de pôster, memória de posição e indicador de carregamento. Precisa estar dentro de um SoundProvider (que o ReelPlayerOverlay fornece sozinho).

Carregamento de conteúdo e tratamento de erros

O player acompanha o carregamento e os erros de cada slide. Uma animação de onda aparece enquanto o conteúdo carrega; um ícone de erro aparece para mídias quebradas. As URLs com erro ficam em cache, então voltar a elas mostra o erro na hora, sem nova tentativa.

Callbacks de ciclo de vida

Ao usar renderSlide, chame estes callbacks para comandar o indicador de carregamento:

Interface própria de carregamento e erro

Troque a animação de onda e o ícone de erro padrão por componentes seus:

Linha do tempo

O overlay desenha uma barra de reprodução embutida sobre o vídeo ativo. A prop timeline libera ou não essa exibição:

• 'auto' (padrão): aparece quando a mídia ativa é um vídeo mais longo que timelineMinDurationSeconds (30 por padrão). Vale para slides de vídeo único e para carrosséis de várias mídias; a barra segue o item aninhado ativo e some nas imagens.
• 'always': aparece sempre que o slide ativo tiver vídeo.
• 'never': nunca aparece. Monte uma barra sua com renderTimeline.

Personalize pelas propriedades CSS --rk-reel-timeline-* (altura, cores, tamanho do cursor). Para uma barra, um cronômetro ou um indicador de progresso totalmente próprios, use renderTimeline; o callback recebe um timelineState apoiado no TimelineController por baixo.

Contexto de som

Em implementações próprias, você pode alcançar o estado do som:

Classes CSS

Todas as classes CSS são simples (não são CSS modules), então dá para alcançá-las com seletores de especificidade maior em uma folha de estilo carregada depois de @reelkit/react-reel-player/styles.css. Para mudar cor, tamanho e z-index, prefira as propriedades CSS documentadas na seção Temas, abaixo — elas existem exatamente para isso.

Temas

Cada cor, tamanho, z-index e transição vive em uma propriedade CSS. Sobrescreva uma ou várias em :root (ou em qualquer ancestral do overlay) para trocar o tema sem mexer no código dos componentes.

Cole o trecho abaixo em uma folha de estilo carregada depois de @reelkit/react-reel-player/styles.css.

Acessibilidade

A raiz do overlay é um diálogo modal (role="dialog", aria-modal="true"). Defina ariaLabel para mudar o que o leitor de tela anuncia; o padrão é "Video player". Cada slide carrega role="group", aria-roledescription="slide" e um aria-label="Slide N of M", então deslizar anuncia a posição na sequência.

O overlay captura o foco ao abrir e o devolve ao gatilho ao fechar. Tab e Shift+Tab percorrem os elementos focáveis lá dentro; um foco que escapa (clique fora, foco por código) é trazido de volta. Implementado com captureFocusForReturn e createFocusTrap, de @reelkit/core.

Atalhos de teclado