Pular para o conteúdo
Sobreposição

Tour

/componentes/tour.mdmarkdown cru, para quem lê com agent em vez de olho

Primeiro acesso

Alvo clicavel

Rascunhos salvos: 0

Importar
import { Tour } from '@rivocode/ui'

Quando usar

O passeio guiado pela tela: escurece a página, recorta um buraco em volta de um elemento de cada vez e explica, num balão preso a ele, o que aquele elemento faz. É o primeiro acesso a um painel novo, a funcionalidade que mudou de lugar, o fluxo que a pessoa só entende vendo as peças na ordem.

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>Fazer o tour</Button>
<Tour
  open={open}
  onOpenChange={setOpen}
  steps={[
    { target: '#novo-paciente', title: 'Cadastre o primeiro paciente', description: 'O cadastro pede só o nome e o celular.' },
    { target: '#busca', title: 'Ache pelo nome ou pelo celular' },
    { target: exportRef, title: 'Leve a lista para a planilha', placement: 'top' },
  ]}
  onFinish={() => markTourAsSeen()}
/>

Cada passo tem target, title, description opcional, placement opcional e action, um conteúdo extra que entra acima dos botões (um link para a doc, um atalho). O target é um seletor CSS ou um ref, e é lido na hora em que o passo abre: o alvo pode nascer depois do tour, desde que exista quando a vez dele chegar.

O destaque

A máscara pinta a tela com o overlay do tema, o mesmo papel do fundo do Dialog, e deixa um recorte de cantos arredondados em volta do alvo, com alguns pixels de folga. O recorte acompanha o alvo quando a página rola, quando a janela muda de tamanho e quando o próprio alvo cresce.

O alvo pode morar dentro de um Dialog, de uma Sheet ou de um Popover: a máscara sobe acima da camada onde ele está, e o balão acima da máscara. O resto do diálogo apaga e para de receber clique, como o resto da página.

Por padrão a máscara engole todo clique, inclusive o do alvo: o tour explica, e a tela espera. Com interactive, o recorte vira passagem e o alvo responde ao clique enquanto o resto continua bloqueado. Serve ao passo que ensina fazendo ("clique em Salvar"), e nesse caso quem avança o tour é você, pelo onStepChange ou pelo step controlado, no handler do próprio alvo. Pelo teclado o caminho continua sendo o balão: o foco fica preso nele, então o clique no alvo é atalho do ponteiro e do toque, e o "Próximo" nunca pode faltar.

Clicar na máscara não fecha nada. Um tour que some no primeiro clique distraído fora do balão é um tour que ninguém termina.

O balão

O balão ancora no alvo pelo mesmo posicionamento do Popover: prefere o lado de placement (bottom por padrão) e vira sozinho quando não cabe. Se o alvo está fora da vista, a página rola até ele e o põe no centro; com prefers-reduced-motion, a rolagem é um salto, sem animação.

Em cima vem o contador ("Passo 2 de 5"), depois o título e o texto. Embaixo, "Pular tour" à esquerda e, à direita, "Voltar" (a partir do segundo passo) e "Próximo", que no último passo vira "Concluir". As setas do teclado andam entre os passos com o foco no balão, menos quando o foco está num campo posto em action: ali a seta anda dentro do texto, e não troca de passo.

onFinish só é chamado no "Concluir". "Pular tour" e Esc chamam onSkip, com o índice do passo em que a pessoa desistiu, que é o dado que diz qual passo está longo demais. Os três fecham, e os três avisam onOpenChange(false).

Os textos saem em português e se trocam por labels: back, next, finish, skip e counter, que é uma função da posição e do total.

Acessibilidade

O balão é um diálogo com nome e descrição: o título entra por aria-labelledby e o texto por aria-describedby. O foco começa no "Próximo", fica preso no balão enquanto o tour está aberto, e volta para quem abriu o tour quando ele termina, por qualquer uma das três saídas. A troca de passo é anunciada ("Passo 3 de 5. Leve a lista para a planilha"), porque o foco continua no mesmo botão e, sem o anúncio, o leitor de tela não teria nada a dizer.

Alvo que não existe

O passo cujo alvo não está na página é pulado, na direção em que a pessoa andava, e em desenvolvimento o console avisa qual passo e qual seletor. Avançar sobre o último passo sem alvo conclui o tour; se nenhum alvo existe, o tour fecha sozinho sem chamar onFinish nem onSkip. É o que acontece quando uma permissão esconde um botão, e pular é melhor que um balão apontando para o nada.

Vale também para o alvo que some com o passo aberto, quando a tela troca de aba ou uma lista recarrega: o tour percebe que o elemento saiu do documento e pula o passo do mesmo jeito, em vez de deixar o recorte num canto vazio.

No celular ele vira folha de baixo

Abaixo de 640px o balão deixa de ser ancorado e sobe do pé da tela na largura toda, com os botões na altura de toque, a mesma decisão que o Popconfirm e o CalendarPanel tomam. A máscara e o recorte continuam: o alvo segue destacado, e a rolagem o leva para a metade de cima da tela, onde a folha não cobre.

As partes

className veste o balão, seja ele o flutuante ou a folha. classNames veste mask, spotlight (o recorte), counter, title, description e footer. A máscara é irmã do balão dentro do portal, e sem esses nomes ela não se alcança de lugar nenhum.

Quando não usar

Para uma dica sobre um elemento só, que a pessoa pede passando o ponteiro, use Tooltip. Para uma explicação de um parágrafo presa a um botão, que a pessoa abre quando quer e fecha clicando fora, use Popover. O tour é a sequência que a tela impõe, e custa atenção inteira; o Popover e o Tooltip são consulta, e não custam nada a quem não precisa deles.

Para anunciar uma novidade sem parar a pessoa ("a exportação agora sai em Excel"), use Banner: ele fica no alto da página, a pessoa lê quando quiser e fecha, e ninguém é obrigado a atravessar cinco passos para chegar ao trabalho.

E não use o tour para compensar uma tela que não se explica sozinha. Se o rótulo do botão precisa de um balão para ser entendido, é o rótulo que está errado.

No React Native

Traduz sobre o Modal do core, sem peer novo: o alvo vem por ref e é medido por measureInWindow quando o passo abre, e quatro faixas com o overlay do tema cercam o recorte. O recorte desconta onde a raiz do Modal começa na janela, e por isso não cai pela altura da barra de status no Android. O balão é sempre uma folha, que é o que o web já faz abaixo de 640px, com o mesmo contador, os mesmos botões e os mesmos textos, que moram num arquivo só, compartilhado pelos dois pacotes. A folha fica embaixo, e sobe para o topo quando o alvo está na metade de baixo da tela, para não cobrir a barra de abas; lá ela mede a área segura de cima do aparelho, guardada pelo RivoProvider da raiz antes de a navegação zerar a faixa do cabeçalho, e o topInset só troca essa medida. Ref vazio, ou que não é uma View com measureInWindow, pula o passo, com o mesmo aviso em desenvolvimento.

Três diferenças, e as três são do toque. O passo é controlado (step e onStepChange obrigatórios), como todo o pacote nativo. Não há interactive: o Modal é outra janela, e o toque não atravessa para a tela de trás. E não há rolagem sozinha, porque o React Native não tem scrollIntoView: quem rola é a tela, no onStepChange, com scrollTo({ animated: false }) na ScrollView, e a peça mede de novo no quadro seguinte. O voltar do Android pula o tour, como o Esc no web.

As partes vestem pelo mesmo classNames do web: mask (as quatro faixas em volta do recorte), counter, title, description e footer. spotlight não existe aqui: o recorte é o vão entre as faixas, e não um nó que se vista.

No iOS e no Android. A peça cobre a tela inteira, por cima da barra de status e da de navegação, e mede a área segura do aparelho com o react-native-safe-area-context, o mesmo número nos dois, e não a da tela, que a navegação zera embaixo do cabeçalho. No Android, o voltar do sistema pula o tour. O iOS não tem voltar: sai-se pelo “Pular tour” ou pelo gesto de escape do VoiceOver, que também pula.

API

PropTipoPadrão
stepsobrigatória

Os passos, na ordem.

TourStep[]sem padrão
classNames

Classe por parte: `mask`, `spotlight`, `counter`, `title`, `description`, `footer`.

Partial<Record<"counter" | "description" | "footer" | "mask" | "spotlight" | "title", string>>sem padrão
defaultOpen

Aberto ao montar, quando ninguem controla.

booleanfalse
defaultStep

O passo de partida, quando ninguem controla.

number0
interactive

Deixa o alvo clicavel atraves do recorte da mascara.

booleanfalse
labels

Os textos dos botoes e do contador, para trocar o idioma ou o termo.

Partial<TourLabels>sem padrão
onFinish

Chamado no Concluir do ultimo passo.

(() => void)sem padrão
onOpenChange

Avisa toda abertura e todo fechamento: concluir, pular e `Esc`.

((open: boolean) => void)sem padrão
onSkip

Chamado no "Pular tour" e no `Esc`, com o passo em que a pessoa desistiu.

((step: number) => void)sem padrão
onStepChange

Chamado a cada troca de passo: Voltar, Proximo, setas e passo pulado por falta de alvo.

((step: number) => void)sem padrão
open

Aberto, controlado.

booleansem padrão
step

O passo atual, controlado.

numbersem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.