Stories Player

Um player de stories em tela cheia no estilo Instagram para React, com @reelkit/react-stories-player.

Ver demonstração ao vivo →

Recursos

Instalação

Não esqueça de importar os estilos:

Início rápido

O componente StoriesOverlay renderiza um player de stories em tela cheia. Combine-o com StoriesRingList para ter pontos de entrada no estilo Instagram. Passe um array de objetos StoriesGroup e controle a visibilidade com isOpen.

Demonstração ao vivo

Clique em um anel para abrir o player. Toque nos lados esquerdo e direito para navegar, deslize para trocar de pessoa.

Estado na URL

Ver demonstração ao vivo →

StoriesUrlOverlay é um componente à parte cujo estado aberto vive na barra de endereços. Os dois eixos viajam em um único parâmetro — ?story=<grupo>.<story> — então o story em exibição ganha um link que dá para compartilhar, favoritar e fechar com o botão voltar. Monte um controlador com useOverlayUrlState e urlIndexTwoAxisKey e entregue-o como controller.

• Abrir empilha uma entrada no histórico. Passar de story e trocar de pessoa substituem essa entrada, então N navegações não acrescentam nenhuma e um único passo para trás sempre fecha o player. Voltar fecha; não retrocede stories.
• A navegação interna vai junto. O índice do story não fica congelado na granularidade do grupo — avançar dentro dos stories de uma pessoa atualiza ?story=2.n, então um link direto cai no story exato.
• 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 parâmetro que não nomeia grupo nem story — um favorito velho, um valor editado à mão, um story além do fim de um grupo — é retirado da URL, em vez de abrir um vizinho.

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. Por padrão o grupo é posicional, então um ?story=2.0 favoritado abre outra pessoa assim que o feed muda de ordem. Enderece o grupo por um id estável — outerCodec escreve o id na URL, outerLocator descobre onde ele está. A metade do story segue sendo um índice simples dentro do grupo resolvido.

Feeds infinitos. Paginar é assunto do outerLocator, independente do codec. locate é síncrono, então só responde pelos grupos já carregados — um link compartilhado para o grupo 400 de um feed que carregou 20 volta vazio. locateAsync é o plano B, chamado somente quando locate falha; o story é então limitado de novo pelo grupo em que a busca parar.

• 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 story que ninguém pediu.
• As opções completas de useOverlayUrlState estão na referência da API para React, e o passo a passo está no guia para React.

Lembrar o que já foi visto

Os anéis exibem o gradiente até o grupo ser assistido até o fim, e um grupo reabre no primeiro story que o leitor ainda não viu. As duas coisas vêm de um ViewedStateController, montado com a mesma chave da barra de endereços — então a entrada guardada fica idêntica ao parâmetro de um link compartilhado e sobrevive à reordenação do feed quando a chave é endereçada por id.

• O story de abertura conta. O story já na tela é registrado como visto na montagem, então abrir um grupo de um story só e fechar já o marca como assistido.
• Deslizar adiante também retoma. resumeStoryIndex é consultado para todo grupo alcançado pela primeira vez na sessão, inclusive aquele em que o player abriu, a menos que initialStoryIndex nomeie um story diretamente; um grupo já percorrido reabre onde parou.
• O link ainda vence. Com StoriesUrlOverlay, quem decide onde o player abre é o parâmetro, independentemente do que estiver guardado. Em todos os outros casos quem decide é o callback de retomada.
• A contagem é uma posição, não um total. A entrada nomeia o story mais distante alcançado, então acrescentar um story a um grupo já assistido acende o anel de novo, e remover um do meio encurta a contagem. A mesma cura espontânea que um link compartilhado recebe.
• O armazenamento é trocável. Passe createSessionStorageAdapter() para esquecer ao fechar a aba, ou o seu próprio StorageAdapter. Duas abas abertas ficam em sintonia pelo evento de armazenamento do navegador.

Referência da API

StoriesOverlayProps

StoriesOverlayProps<T>

StoriesUrlOverlayProps

StoriesUrlOverlayProps<T>

Aceita todas as props do StoriesOverlay, menos o trio do estado aberto — isOpen, initialGroupIndex, initialStoryIndex —, que vem do controlador.

Callbacks

Transições

A prop groupTransition controla o efeito 3D ao deslizar entre os grupos de pessoas. Importe as funções de transição de @reelkit/react:

Ciclo de vida do carregamento de conteúdo

Cada slide de story informa seu estado de carregamento pelos callbacks que chegam em SlideRenderProps:

Render Props

Todo elemento da interface pode ser substituído por uma render prop. Cada uma recebe props tipadas com o estado e os callbacks necessários.

renderHeader

Substitua o cabeçalho padrão (dados do autor, botões de pausa e som, botão de fechar):

renderFooter

Acrescente um rodapé abaixo do conteúdo do story:

renderSlide

Substitua por completo os slides padrão de imagem e vídeo. Use os subcomponentes ImageStorySlide e VideoStorySlide para aproveitar o tratamento de mídia que já vem pronto:

renderNavigation

Substitua os botões de seta padrão do desktop:

renderProgressBar

Substitua a barra de progresso padrão em canvas por uma implementação sua. O sinal progress emite valores de 0 a 1:

renderLoading

Indicador de carregamento próprio enquanto o conteúdo é buscado:

renderError

Camada de erro própria para quando o conteúdo não carrega:

StoriesApi

Use a prop apiRef para o controle imperativo:

Métodos

Toque duplo e curtidas

Uma animação de coração já embutida toca no toque duplo, dando um retorno visual imediato. O callback onDoubleTap dispara com os índices do grupo e do story, então você guarda a curtida no seu próprio estado (chamada de API, armazenamento local, o que for). O player não guarda esse estado internamente.

Personalizando a animação do coração

Ajuste a velocidade da animação pelo token --rk-stories-heart-duration (veja Temas). Para mudar cor, tamanho ou esconder o coração por completo, mire direto na classe .rk-stories-heart. O componente HeartAnimation também é exportado para uso isolado.

Subcomponentes

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

CanvasProgressBar

Barra de progresso segmentada em canvas, de alto desempenho. Desenha um segmento por story e anima o preenchimento do segmento ativo com requestAnimationFrame. Aceita uma janela deslizante para grupos com muitos stories.

StoryHeader

Cabeçalho padrão, com avatar e nome do autor, selo de verificado, horário relativo, botão de pausa, botão de som, girador de carregamento e botão de fechar. Usado automaticamente quando renderHeader não é informado.

ImageStorySlide

Slide de imagem de borda a borda, com object-fit: cover. Informa carregamento e erro pelos callbacks do ciclo de vida.

VideoStorySlide

Slide de vídeo que usa um elemento <video> compartilhado para a continuidade do som no iOS. Cuida da reprodução automática, dos quadros de pôster e da sincronia do som, e informa a duração e os eventos do ciclo de reprodução.

StoriesRing

Avatar circular com anel em gradiente no estilo Instagram. Dois estados: um grupo com stories por assistir ganha o gradiente giratório, um totalmente assistido ganha um anel discreto e parado.

StoriesRingList

Fileira horizontal e rolável de componentes StoriesRing, com o nome de cada autor. Um anel por grupo.

HeartAnimation

Camada animada de coração, disparada no toque duplo. Cresce e some ao longo de 800ms. Personalize pelo CSS (veja a seção Toque duplo e curtidas).

Tipos

StoryItem

AuthorInfo

StoriesGroup<T>

HeaderRenderProps<T>

FooterRenderProps<T>

SlideRenderProps<T>

NavigationRenderProps

ProgressBarRenderProps<T>

LoadingRenderProps<T>

ErrorRenderProps<T>

StoriesApi

Tipos de Story personalizados

Estenda StoryItem com campos seus e passe o parâmetro de tipo ao StoriesOverlay. Todas as render props vão receber o seu tipo estendido:

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-stories-player/styles.css. Para mudar cor, tamanho e z-index, prefira as propriedades CSS documentadas na 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.

Cole o trecho abaixo em uma folha de estilo carregada depois de @reelkit/react-stories-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 é "Stories player".

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