Codelab: como criar um componente de Histórias

Este codelab ensina como criar uma experiência como o Instagram Stories na Web. Vamos criar o componente aos poucos, começando com HTML, depois CSS e, por fim, JavaScript.

Confira minha postagem no blog Como criar um componente de Stories para saber mais sobre as melhorias progressivas feitas durante a criação desse componente.

Configuração

  1. Clique em Remix to Edit para tornar o projeto editável.
  2. Abra app/index.html.

HTML

Sempre procuro usar HTML semântico. Como cada amigo pode ter qualquer número de histórias, achei que seria interessante usar um elemento <section> para cada amigo e um elemento <article> para cada história. Mas vamos começar do início. Primeiro, precisamos de um contêiner para o componente de histórias.

Adicione um elemento <div> ao <body>:

<div class="stories">

</div>

Adicione alguns elementos <section> para representar amigos:

<div class="stories">
  <section class="user"></section>
  <section class="user"></section>
  <section class="user"></section>
  <section class="user"></section>
</div>

Adicione alguns elementos <article> para representar as histórias:

<div class="stories">
  <section class="user">
    <article class="story" style="--bg: url(https://picsum.photos/480/840);"></article>
    <article class="story" style="--bg: url(https://picsum.photos/480/841);"></article>
  </section>
  <section class="user">
    <article class="story" style="--bg: url(https://picsum.photos/481/840);"></article>
  </section>
  <section class="user">
    <article class="story" style="--bg: url(https://picsum.photos/481/841);"></article>
  </section>
  <section class="user">
    <article class="story" style="--bg: url(https://picsum.photos/482/840);"></article>
    <article class="story" style="--bg: url(https://picsum.photos/482/843);"></article>
    <article class="story" style="--bg: url(https://picsum.photos/482/844);"></article>
  </section>
</div>
  • Estamos usando um serviço de imagem (picsum.com) para ajudar a criar protótipos de histórias.
  • O atributo style em cada <article> faz parte de uma técnica de carregamento de marcador de posição, que será abordada na próxima seção.

CSS

Nosso conteúdo está pronto para ser estilizado. Vamos transformar esses ossos em algo com que as pessoas vão querer interagir. Hoje, vamos trabalhar com foco em dispositivos móveis.

.stories

Para o contêiner <div class="stories">, queremos um contêiner de rolagem horizontal. Para isso, podemos:

  • Como transformar o contêiner em uma grade
  • Configurar cada filho para preencher a faixa de linha
  • Definir a largura de cada filho como a largura de uma janela de visualização de dispositivo móvel

A grade vai continuar colocando novas colunas de largura 100vw à direita da anterior até que todos os elementos HTML sejam colocados na marcação.

Chrome e DevTools abertos com um visual de grade mostrando o layout de largura total
O Chrome DevTools mostrando o estouro da coluna da grade, criando um controle de rolagem horizontal.

Adicione o seguinte CSS à parte de baixo de app/css/index.css:

.stories {
  display: grid;
  grid: 1fr / auto-flow 100%;
  gap: 1ch;
}

Agora que temos conteúdo que se estende além da janela de visualização, é hora de dizer ao contêiner como lidar com isso. Adicione as linhas de código destacadas ao conjunto de regras .stories:

.stories {
  display: grid;
  grid: 1fr / auto-flow 100%;
  gap: 1ch;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
  overscroll-behavior: contain;
  touch-action: pan-x;
}

Queremos uma rolagem horizontal, então vamos definir overflow-x como auto. Quando o usuário rolar a tela, queremos que o componente pare suavemente na próxima história. Por isso, vamos usar scroll-snap-type: x mandatory. Leia mais sobre esse CSS nas seções Pontos de ajuste de rolagem do CSS e overscroll-behavior da minha postagem do blog.

É necessário que o contêiner pai e os filhos concordem com o ajuste de rolagem. Vamos cuidar disso agora. Adicione o código abaixo ao final de app/css/index.css:

.user {
  scroll-snap-align: start;
  scroll-snap-stop: always;
}

Seu app ainda não funciona, mas o vídeo abaixo mostra o que acontece quando scroll-snap-type é ativado e desativado. Quando ativada, cada ajuste de rolagem horizontal vai para a próxima história. Quando desativada, o navegador usa o comportamento de rolagem padrão.

Isso vai permitir que você role pelos seus amigos, mas ainda temos um problema com as histórias para resolver.

.user

Vamos criar um layout na seção .user que organiza esses elementos de histórias filhas. Vamos usar um truque de empilhamento para resolver isso. Estamos criando uma grade de 1x1 em que a linha e a coluna têm o mesmo alias de grade [story], e cada item da grade de histórias vai tentar reivindicar esse espaço, resultando em uma pilha.

Adicione o código destacado ao conjunto de regras .user:

.user {
  scroll-snap-align: start;
  scroll-snap-stop: always;
  display: grid;
  grid: [story] 1fr / [story] 1fr;
}

Adicione o seguinte conjunto de regras à parte de baixo de app/css/index.css:

.story {
  grid-area: story;
}

Agora, sem posicionamento absoluto, flutuações ou outras diretivas de layout que retiram um elemento do fluxo, ainda estamos no fluxo. Além disso, quase não tem código, olha só! Isso é detalhado no vídeo e no post do blog.

.story

Agora só precisamos estilizar o item da matéria.

Mencionamos anteriormente que o atributo style em cada elemento <article> faz parte de uma técnica de carregamento de marcador de posição:

<article class="story" style="--bg: url(https://picsum.photos/480/840);"></article>

Vamos usar a propriedade background-image do CSS, que permite especificar mais de uma imagem de plano de fundo. Podemos colocá-los em uma ordem para que a imagem do usuário fique por cima e apareça automaticamente quando o carregamento for concluído. Para ativar isso, vamos colocar o URL da imagem em uma propriedade personalizada (--bg) e usá-lo no CSS para criar uma camada com o marcador de carregamento.

Primeiro, vamos atualizar o conjunto de regras .story para substituir um gradiente por uma imagem de plano de fundo quando o carregamento for concluído. Adicione o código destacado ao conjunto de regras .story:

.story {
  grid-area: story;

  background-size: cover;
  background-image:
    var(--bg),
    linear-gradient(to top, lch(98 0 0), lch(90 0 0));
}

Definir background-size como cover garante que não haja espaço vazio na janela de visualização, porque a imagem vai preenchê-la. Definir duas imagens de plano de fundo permite que usemos um truque da Web em CSS chamado loading tombstone:

  • A imagem de plano de fundo 1 (var(--bg)) é o URL que transmitimos inline no HTML.
  • Imagem de plano de fundo 2 (linear-gradient(to top, lch(98 0 0), lch(90 0 0)) é um gradiente para mostrar enquanto o URL está carregando)

O CSS vai substituir automaticamente o gradiente pela imagem quando o download dela for concluído.

Em seguida, vamos adicionar um pouco de CSS para remover alguns comportamentos, liberando o navegador para se mover mais rápido. Adicione o código destacado ao conjunto de regras .story:

.story {
  grid-area: story;

  background-size: cover;
  background-image:
    var(--bg),
    linear-gradient(to top, lch(98 0 0), lch(90 0 0));

  user-select: none;
  touch-action: manipulation;
}
  • user-select: none impede que os usuários selecionem texto acidentalmente
  • touch-action: manipulation instrui o navegador a tratar essas interações como eventos de toque, o que evita que ele tente decidir se você está clicando em um URL ou não.

Por fim, vamos adicionar um pouco de CSS para animar a transição entre as histórias. Adicione o código destacado ao conjunto de regras .story:

.story {
  grid-area: story;

  background-size: cover;
  background-image:
    var(--bg),
    linear-gradient(to top, lch(98 0 0), lch(90 0 0));

  user-select: none;
  touch-action: manipulation;

  transition: opacity .3s cubic-bezier(0.4, 0.0, 1, 1);

  &.seen {
    opacity: 0;
    pointer-events: none;
  }
}

A classe .seen será adicionada a uma história que precisa de uma saída. A função de easing personalizada (cubic-bezier(0.4, 0.0, 1,1)) foi retirada do guia Easing do Material Design (role até a seção Accerlerated easing).

Se você tem um olhar atento, provavelmente percebeu a declaração pointer-events: none e está se perguntando o que ela significa. Eu diria que essa é a única desvantagem da solução até agora. Precisamos disso porque um elemento .seen.story vai ficar na parte de cima e receber toques, mesmo que seja invisível. Ao definir o pointer-events como none, transformamos a história de vidro em uma janela e não roubamos mais interações do usuário. Não é uma troca ruim, nem é muito difícil de gerenciar aqui no nosso CSS. Não estamos fazendo malabarismos com z-index. Ainda estou confiante.

JavaScript

As interações de um componente de Stories são bem simples para o usuário: toque à direita para avançar, toque à esquerda para voltar. O que é simples para os usuários costuma ser difícil para os desenvolvedores. Mas nós vamos cuidar de boa parte disso.

Configuração

Para começar, vamos calcular e armazenar o máximo de informações possível. Adicione o código a seguir a app/js/index.js:

const stories = document.querySelector('.stories')
const median = stories.offsetLeft + (stories.clientWidth / 2)

A primeira linha do JavaScript captura e armazena uma referência à raiz do elemento HTML principal. A próxima linha calcula onde fica o meio do elemento para que possamos decidir se um toque vai para frente ou para trás.

Estado

Em seguida, criamos um pequeno objeto com um estado relevante para nossa lógica. Nesse caso, só estamos interessados na história atual. Na marcação HTML, podemos acessá-lo pegando o primeiro amigo e a história mais recente dele. Adicione o código destacado ao app/js/index.js:

const stories = document.querySelector('.stories')
const median = stories.offsetLeft + (stories.clientWidth / 2)

const state = {
  current_story: stories.firstElementChild.lastElementChild
}

Listeners

Agora temos lógica suficiente para começar a detectar eventos do usuário e direcioná-los.

Camundongo

Vamos começar detectando o evento 'click' no contêiner de histórias. Adicione o código destacado a app/js/index.js:

const stories = document.querySelector('.stories')
const median = stories.offsetLeft + (stories.clientWidth / 2)

const state = {
  current_story: stories.firstElementChild.lastElementChild
}

stories.addEventListener('click', e => {
  if (e.target.nodeName !== 'ARTICLE')
    return

  navigateStories(
    e.clientX > median
      ? 'next'
      : 'prev')
})

Se um clique acontecer e não for em um elemento <article>, vamos sair e não fazer nada. Se for um artigo, pegamos a posição horizontal do mouse ou do dedo com clientX. Ainda não implementamos navigateStories, mas o argumento que ele usa especifica a direção que precisamos seguir. Se a posição do usuário for maior que a mediana, sabemos que precisamos navegar para next. Caso contrário, prev (anterior).

Teclado

Agora, vamos detectar as teclas pressionadas. Se a seta para baixo for pressionada, navegamos para next. Se for a seta para cima, vamos para prev.

Adicione o código destacado a app/js/index.js:

const stories = document.querySelector('.stories')
const median = stories.offsetLeft + (stories.clientWidth / 2)

const state = {
  current_story: stories.firstElementChild.lastElementChild
}

stories.addEventListener('click', e => {
  if (e.target.nodeName !== 'ARTICLE')
    return

  navigateStories(
    e.clientX > median
      ? 'next'
      : 'prev')
})

document.addEventListener('keydown', ({key}) => {
  if (key !== 'ArrowDown' || key !== 'ArrowUp')
    navigateStories(
      key === 'ArrowDown'
        ? 'next'
        : 'prev')
})

Navegação de histórias

É hora de abordar a lógica de negócios exclusiva das histórias e a UX que as tornou famosas. Parece complicado, mas se você analisar linha por linha, vai perceber que é bem simples.

Primeiro, armazenamos alguns seletores que nos ajudam a decidir se devemos rolar até um amigo ou mostrar/ocultar uma história. Como estamos trabalhando no HTML, vamos consultar a presença de amigos (usuários) ou histórias (história).

Essas variáveis vão nos ajudar a responder perguntas como: "Considerando a história x, 'próxima' significa passar para outra história do mesmo amigo ou de um amigo diferente?" Fiz isso usando a estrutura de árvore que criamos, alcançando os pais e os filhos.

Adicione o código abaixo ao final de app/js/index.js:

const navigateStories = direction => {
  const story = state.current_story
  const lastItemInUserStory = story.parentNode.firstElementChild
  const firstItemInUserStory = story.parentNode.lastElementChild
  const hasNextUserStory = story.parentElement.nextElementSibling
  const hasPrevUserStory = story.parentElement.previousElementSibling
}

Esta é nossa meta de lógica de negócios, o mais próximo possível da linguagem natural:

  • Decidir como lidar com o toque
    • Se houver uma história seguinte/anterior: mostre essa história
    • Se for a última/primeira história do amigo: mostre um novo amigo
    • Se não houver uma matéria para acessar nessa direção: não faça nada
  • Armazenar a nova história atual em state

Adicione o código destacado à função navigateStories:

const navigateStories = direction => {
  const story = state.current_story
  const lastItemInUserStory = story.parentNode.firstElementChild
  const firstItemInUserStory = story.parentNode.lastElementChild
  const hasNextUserStory = story.parentElement.nextElementSibling
  const hasPrevUserStory = story.parentElement.previousElementSibling

  if (direction === 'next') {
    if (lastItemInUserStory === story && !hasNextUserStory)
      return
    else if (lastItemInUserStory === story && hasNextUserStory) {
      state.current_story = story.parentElement.nextElementSibling.lastElementChild
      story.parentElement.nextElementSibling.scrollIntoView({
        behavior: 'smooth'
      })
    }
    else {
      story.classList.add('seen')
      state.current_story = story.previousElementSibling
    }
  }
  else if(direction === 'prev') {
    if (firstItemInUserStory === story && !hasPrevUserStory)
      return
    else if (firstItemInUserStory === story && hasPrevUserStory) {
      state.current_story = story.parentElement.previousElementSibling.firstElementChild
      story.parentElement.previousElementSibling.scrollIntoView({
        behavior: 'smooth'
      })
    }
    else {
      story.nextElementSibling.classList.remove('seen')
      state.current_story = story.nextElementSibling
    }
  }
}

Faça um teste

  • Para visualizar o site, pressione View App. Em seguida, pressione Fullscreen tela cheia.

Conclusão

Isso é tudo que eu precisava do componente. Fique à vontade para desenvolver, orientar com dados e, em geral, personalizar o conteúdo.