Vue Reel Player

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

Ver demonstração ao vivo →

Recursos

Instalação

Importe a folha de estilo uma vez na entrada do seu app (ou em qualquer componente):

Uso básico

Desenhe uma grade de miniaturas e abra o overlay no índice clicado. Ligar v-model:is-open mantém o ref do componente pai em sintonia quando o leitor fecha o player pelo botão, por gesto ou com Escape.

Slots com escopo

Oito slots com escopo permitem trocar qualquer parte da interface do player. Cada um recebe um objeto de escopo fortemente tipado. Os slots que você não passar caem no padrão.

Linha do tempo própria

Troque a barra de reprodução padrão pela sua, com o slot #timeline. O slot só dispara 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.

Tipos de conteúdo próprios

ReelPlayerOverlay é genérico em relação ao formato dos seus itens de conteúdo. Estenda BaseContentItem para usar qualquer modelo de dados e importe o tipo de escopo de slot correspondente para manter as ligações fortemente tipadas:

O mesmo padrão vale para todos os outros slots. Importe o tipo de escopo correspondente (SlideSlotScope, ControlsSlotScope, NavigationSlotScope, NestedSlideSlotScope, LoadingSlotScope) e anote a desestruturação.

Estado na URL

Ver demonstração ao vivo →

Monte um controlador com useOverlayUrlState, de @reelkit/vue, e entregue-o ao ReelPlayerUrlOverlay como controller: quem manda no player é a barra de endereços, então ele abre quando o parâmetro nomeia um slide e fecha quando o parâmetro some. Abrir empilha uma entrada no histórico e cada troca de slide a substitui, então percorrer um feed não acrescenta entradas e um único passo para trás sempre sai. A profundidade da URL acompanha a chave do controlador: um urlIndexKey de eixo único endereça apenas o post (?reel=3); um urlIndexTwoAxisKey de dois eixos carrega também o índice da mídia interna de um post com várias mídias (?reel=3.2); escolha uma chave por app, porque os dois formatos não são decodificados um pelo outro. É um componente separado do ReelPlayerOverlay, então cada um carrega exatamente um comando do estado aberto — o modelo is-open ou o controller da URL, nunca os dois.

Um app com rotas deve passar um adaptador ligado ao roteador, 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. useVueRouterUrlAdapter, de @reelkit/vue/vue-router-url-adapter, é o adaptador pronto para o Vue Router.

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

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

Uma chave ou duas — escolha a profundidade da URL

O mesmo ReelPlayerOverlay 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.

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 ReelPlayerOverlay

ReelPlayerOverlayProps

Props do ReelPlayerUrlOverlay

ReelPlayerUrlOverlayProps

Aceita todas as props acima, menos is-open, substituída por controller. initial-index é ignorada — quem escolhe o slide é a posição do controlador, então um valor passado ao lado dela é sobrescrito a cada abertura.

Eventos

v-model:is-open

Use v-model:is-open para conduzir o overlay com uma única ligação. O padrão antigo de :is-open com @close continua funcionando, se você precisar do evento explícito.

Tipos

ContentItem

TimelineBarProps

TimelineSlotScope<T>

MediaItem

Subcomponentes

Use-os dentro dos seus templates de #controls, #slide ou #slideOverlay. Repasse as dimensões e os callbacks do escopo do slot para que a reprodução automática, a captura de pôster e a sincronia do som continuem funcionando.

CloseButton

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

SoundButton

Botão de mudo. Renderize-o dentro de um SoundProvider (o ReelPlayerOverlay fornece um). Fica escondido quando o slide ativo não tem vídeo.

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 pelo slot #timeline.

SlideOverlay

A camada em gradiente padrão, que mostra autor, descrição e curtidas. Aparece quando o conteúdo traz esses campos. Substitua-a ou esconda-a pelo slot #slideOverlay.

ImageSlide

Slide de imagem com carregamento tardio e object-fit: cover por padrão. Componha-o dentro do slot #slide para personalizar a exibição da imagem mantendo o comportamento embutido.

VideoSlide

Slide de vídeo apoiado em um elemento <video> compartilhado. Cuida da continuidade do som no iOS, dos quadros de pôster e da memória de posição. Renderize-o dentro de um SoundProvider (o ReelPlayerOverlay fornece um).

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; mídias quebradas mostram um ícone de erro. O player guarda em cache as URLs que falharam, então reabrir um slide quebrado pula a nova tentativa.

Callbacks de ciclo de vida

Ao usar o slot #slide, chame estes callbacks, vindos do escopo do slot, 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 pelos slots #loading e #error:

Linha do tempo

O overlay desenha uma barra de reprodução embutida sobre o vídeo ativo. Libere-a pela prop 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 o slot #timeline; o escopo dele expõe um timelineState apoiado no TimelineController por baixo.

Personalize pelas propriedades CSS --rk-reel-timeline-*.

Contexto de som

O ReelPlayerOverlay monta um SoundProvider na raiz, então qualquer componente renderizado lá dentro pode ler ou alternar o estado de mudo por useSoundState. O composable é reexportado por @reelkit/vue-reel-player, então você não precisa de um import separado de @reelkit/vue.

Classes CSS

As classes CSS são simples (sem escopo). Uma folha de estilo carregada depois de @reelkit/vue-reel-player/styles.css pode sobrescrever qualquer uma delas com um seletor de especificidade maior. Para mudar cor, tamanho e z-index, use as propriedades CSS da seção Temas, abaixo.

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 de @reelkit/react-reel-player, então as sobrescritas valem para os dois bindings.

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

Acessibilidade

A raiz do overlay é um diálogo modal (role="dialog", aria-modal="true"). Defina a prop aria-label 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