Angular Reel Player

Player vertical de mídia em tela cheia no estilo Instagram/TikTok para Angular, construído sobre @reelkit/angular-reel-player.

Ver demonstração ao vivo →

Recursos

Instalação

Uso básico

Importe a folha de estilo e o componente standalone RkReelPlayerOverlayComponent no array imports do seu componente.

Slots de template

Seis diretivas de slot de template permitem personalizar cada parte da interface do player. Cada uma recebe um objeto de contexto fortemente tipado. Informe apenas os slots que quiser trocar — nos demais valem os padrões.

Linha do tempo própria

O slot de template rkPlayerTimeline só é chamado quando as regras do overlay renderizariam a barra padrão (o mesmo modo timeline e o mesmo 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 em dispositivos de toque. Chame state.bindInteractions(el) na sua trilha de arrasto para ligar o arrasto por ponteiro e por teclado.

Slider aninhado (itens com várias mídias)

Quando um ContentItem traz várias entradas em media, o player as exibe em um slider horizontal aninhado (no estilo carrossel do Instagram). Use o slot rkPlayerNestedSlide para personalizar o conteúdo dos slides internos.

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 o slot de template rkPlayerSlide, use os callbacks do contexto 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 templates seus:

Linha do tempo

O overlay desenha uma barra de reprodução embutida sobre o vídeo ativo. Libere-a pelo input timeline: 'auto' (padrão) aparece sempre que a mídia ativa for um vídeo mais longo que timelineMinDurationSeconds (30 por padrão), 'always' sempre que houver um vídeo ativo, 'never' para desligar. Para uma barra totalmente sua, use a diretiva de template rkPlayerTimeline; o contexto dela expõe um timelineState apoiado no TimelineController por baixo.

Personalize pelas propriedades CSS --rk-reel-timeline-*. Para controle direto em componentes seus, injete o TimelineStateService.

RkTimelineBarComponent

Componente da barra de reprodução padrão. Consome o TimelineStateService (fornecido pelo RkReelPlayerOverlayComponent) e desenha a trilha, os trechos em buffer, o preenchimento do progresso e a pílula de arrasto. Seletor: rk-timeline-bar. Inputs: class?: string, style?: Record<string, string>. Use dentro de um template rkPlayerTimeline para envolver ou complementar a barra padrão; use isolado apenas dentro de um componente que forneça o serviço.

SoundStateService

Fornecido no nível do RkReelPlayerOverlayComponent. Injetado pelo botão de som padrão e exposto no contexto do slot de controles. Pode ser injetado em controles próprios que sejam filhos do overlay, para acesso direto.

Estado na URL

Ver demonstração ao vivo →

RkReelPlayerUrlOverlayComponent é um componente à parte cujo estado aberto vive na barra de endereços. Monte um controlador com createOverlayUrlState em um contexto de injeção e passe-o como [controller]: o player abre quando o parâmetro nomeia um slide e fecha quando ele some. Os links dão para compartilhar, e o botão voltar fecha o player. O RkReelPlayerOverlayComponent continua comandado por [isOpen], então cada componente carrega exatamente um comando do estado aberto.

Um app com rotas passa um adaptador ligado ao Router, para que ele siga sendo a única fonte de verdade da navegação — escrever no histórico por trás dele deixa sua localização desatualizada e derruba o parâmetro na navegação seguinte. createRouterUrlAdapter, de @reelkit/angular/ng-router-url-adapter, é o adaptador pronto.

• 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.
• A profundidade da URL acompanha a chave do controlador: eixo único para o post apenas, ou dois eixos (urlIndexTwoAxisKey) para carregar também o índice da imagem interna de um post com várias mídias. Escolha uma chave por app; os formatos não são decodificados um pelo outro.

As opções completas de createOverlayUrlState estão na referência da API para Angular.

Uma chave ou duas — escolha a profundidade da URL

O mesmo RkReelPlayerUrlOverlayComponent conduz os dois formatos; ele distingue em tempo de execução pela posição do controlador, então não existe input 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.

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. 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: carregue as páginas necessárias e devolva o índice que a identidade acabou tendo.

• 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.

Tipos de dados próprios

Estenda BaseContentItem para usar o seu próprio modelo de domínio. O componente é genérico: RkReelPlayerOverlayComponent<T extends BaseContentItem>.

Inputs do RkReelPlayerOverlayComponent

Outputs do RkReelPlayerOverlayComponent

Inputs do RkReelPlayerUrlOverlayComponent

Aceita todos os inputs acima, menos isOpen e initialIndex, substituídos por um controller cuja posição escolhe o slide. Emite closed e slideChange.

Interface MediaItem

Tipos de contexto dos slots de template

Classes CSS

Todas as classes CSS são simples (sem escopo), então dá para alcançá-las com seletores de especificidade maior em uma folha de estilo carregada depois de @reelkit/angular-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. Os tokens são os mesmos dos pacotes de React e de Vue, então as sobrescritas valem para todos os bindings.

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

Acessibilidade

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

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