Pular para o conteúdo
Sobreposição

ImageViewer

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

Em volta, da última volta à primeira

Controlado, aberto por outro botão

No chat, com quem mandou e a barra de ações

Foto e vídeo da conversa no mesmo visualizador

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

Quando usar

Uma grade de miniaturas que abre a foto em tela cheia: fotos de um imóvel, comprovantes anexados a uma despesa, a vistoria de um veículo. Na tela cheia a pessoa navega entre as imagens, aproxima para ler o detalhe e fecha voltando exatamente para onde estava.

<ImageViewer
  images={[
    { src: '/fotos/fachada.jpg', alt: 'Fachada do prédio comercial' },
    { src: '/fotos/recepcao.jpg', alt: 'Recepção com balcão de madeira' },
  ]}
/>

É montada sobre o Dialog da casa: o foco fica preso dentro, Esc fecha, o fundo fica inerte para o leitor de tela e o tema acompanha o portal.

O palco é sempre escuro

A tela cheia abre num palco escuro nos dois temas, como a galeria do celular e os visualizadores de foto de mercado: fundo claro em volta da foto briga com ela e estoura o brilho. O fundo, a legenda, o contador e os controles (fechar, setas e zoom) leem os papéis fixos media-* (bg-media-stage, bg-media-control, text-media-fg, text-media-fg-muted, border-media-border e media-disabled para o controle desabilitado), e não os papéis do tema.

Eles moram em scales.css, fora dos temas, pelo mesmo motivo do par do QRCode: o palco continua escuro no tema claro e em todo tema de cliente, sem o cliente declarar nada. O check:contrast mede os pares: o palco escuro, legenda e contador a 4,5:1, ícone, contorno e anel de foco a 3:1, e o controle desabilitado visível e mais fraco que o vivo. A grade de miniaturas continua na página, e com as cores do tema.

O tema não declara --rc-media-*. Para mudar o palco num produto, vista as partes pelo classNames (viewer, counter, caption), com token.

As imagens

images é a lista, na ordem da navegação. Cada imagem tem src, alt obrigatório, caption opcional e thumbnail, a versão pequena que a grade usa (sem ela, a grade carrega o src).

Imagem que pede cabeçalho. src e thumbnail aceitam também { uri, headers }, para a foto que vem de uma API com chave (x-api-key) e que o <img> não sabe pedir. Com headers, a peça baixa por fetch, mostra pelo URL.createObjectURL e revoga o endereço ao desmontar; enquanto baixa, o palco gira, e se a resposta não for 2xx, diz que não carregou. Cada endereço baixa uma vez só enquanto a peça vive. Sem headers, nada muda: o endereço vai direto para o <img>.

const fotos = mensagens.map((m) => ({
  src: { uri: m.fotoUrl, headers: { 'x-api-key': chave } },
  alt: m.descricao,
}))

O alt é obrigatório no tipo, e não por capricho: ele é o nome do botão da miniatura, e é o que o leitor de tela ouve a cada troca de imagem, junto com a posição ("3 de 8: Recepção com balcão de madeira"). Uma galeria sem alt é, para quem não enxerga, uma fileira de botões sem nome.

A caption aparece embaixo da imagem aberta, e vale para o que o alt não diz: quando foi tirada, quem enviou, o que a pessoa deve reparar.

Num chat: quem mandou, quando, e as ações

Na conversa, cada imagem pode levar author e date, já escritos pelo app ("Marina Costa", "hoje, 14:33"). Com eles, o alto do visualizador mostra quem mandou e quando à esquerda, e o contador passa para perto do xis. A imagem sem os dois continua com o contador à esquerda.

actions desenha a barra de baixo, que o app escolhe: Responder, Encaminhar, Salvar. A função recebe a imagem aberta e o índice dela, e é chamada de novo a cada troca. O que vai nela já sai no contraste do palco: a barra redefine os papéis do tema (fg, fg-muted, surface, border-strong, ring e o resto) para os media-*, então um Button variant="ghost" ou um IconButton da casa fica claro sobre o palco escuro sem classe nenhuma.

const fotos = mensagens.map((m) => ({
  src: m.fotoUrl,
  alt: m.descricao,
  author: m.autor,
  date: m.horaEscrita,
}))

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  actions={(foto, posicao) => (
    <>
      <Button variant="ghost" onClick={() => responder(mensagens[posicao])}>Responder</Button>
      <Button variant="ghost" onClick={() => encaminhar(mensagens[posicao])}>Encaminhar</Button>
      <Button variant="ghost" render={<a href={foto.src} download />}>Salvar</Button>
    </>
  )}
/>

Baixar

download liga o botão Baixar na barra de cima, ao lado do zoom e do xis. Desligado por padrão: a foto de um imóvel não é, por si, coisa que se baixa.

  • download (ou download={true}) baixa pela própria peça o item aberto, foto ou vídeo, com os mesmos headers do src, e salva com o nome do endereço (fachada.jpg). Sem extensão no endereço, o nome vem do alt e a extensão do tipo que o servidor mandou. O arquivo passa por um Blob e um <a download>, e o endereço temporário é revogado logo depois.
  • O servidor que recusa a leitura (CORS) não deixa o navegador ler o arquivo. Sem headers, a peça abre o arquivo em outra aba, onde a pessoa salva pelo navegador; com headers, não abre, porque a aba iria sem o cabeçalho. Nos dois casos a falha aparece embaixo do palco e é anunciada.
  • Uma função fica com o download: recebe o item e o índice, como o actions. Se devolver uma promessa, o botão gira e diz "Baixando…" até ela acabar; a resolvida mostra labels.downloaded ("Arquivo salvo.") e a rejeitada, labels.downloadError.
<ImageViewer images={fotos} index={index} onIndexChange={setIndex} thumbnails={false} download />

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  download={(foto, posicao) => baixarPeloServidor(mensagens[posicao].id)}
/>

O botão não trava enquanto busca: ele continua com o foco, troca o nome para "Baixando…" e ignora o segundo clique. O fim sai na mesma linha embaixo do palco, e é anunciado: "Arquivo salvo." quando a promessa resolve, a falha quando rejeita. Trocar de item limpa a linha. Os textos são labels.download, labels.downloading, labels.downloaded e labels.downloadError. O downloadError aceita também uma função do erro, para dizer o motivo, e downloaded: "" cala o sucesso. A função que não devolve promessa não ganha linha de sucesso: a peça não sabe quando ela acabou.

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  download={(foto) => baixarPeloServidor(foto.src)}
  labels={{
    downloaded: "Foto salva.",
    downloadError: (erro) =>
      erro instanceof Error && erro.message === "HTTP 413"
        ? "O arquivo é grande demais para baixar."
        : "Não foi possível baixar o arquivo.",
  }}
/>

Foto e vídeo no mesmo visualizador

Como na galeria do WhatsApp, a mídia da conversa passa toda pelo mesmo visualizador, na ordem em que foi mandada: foto, vídeo, foto. O item com kind: "video" toca o src num VideoPlayer no palco, com o mesmo cabeçalho, o mesmo contador, o mesmo xis e a mesma barra de ações das fotos. Sem kind, o item é foto, como sempre foi.

const midia = mensagens.map((m) =>
  m.tipo === 'video'
    ? { kind: 'video', src: m.arquivo, poster: m.capa, duration: m.segundos, alt: '', author: m.autor, date: m.hora }
    : { src: m.arquivo, alt: m.descricao, author: m.autor, date: m.hora },
)

<ImageViewer images={midia} index={index} onIndexChange={setIndex} thumbnails={false} />
  • poster é a capa: aparece na miniatura e no palco até o primeiro toque, e com ela o arquivo só baixa quando a pessoa toca no play. Sem ela, o palco pede só os metadados e mostra o primeiro quadro que o navegador conseguir.
  • duration, em segundos, aparece no player antes de o arquivo carregar e dá o nome falado: com alt vazio, o leitor de tela ouve "2 de 3: Vídeo de 12 segundos", a mesma frase do MessageMedia no balão. Um alt escrito vence.
  • O player só existe no item aberto. Ao passar para a foto seguinte ele sai de cena, e o vídeo para junto: não fica som tocando atrás de uma foto.
  • Sem zoom no vídeo. Os botões de mais e menos desabilitam, e o duplo clique, a roda com Ctrl, a pinça e o +, - e 0 não fazem nada.
  • As setas dentro do player buscam no vídeo, de 5 em 5 segundos, como em todo VideoPlayer; com o foco fora dele, trocam de item. PageUp e PageDown trocam de item sempre. O deslizar de lado troca de item quando começa no quadro, e não na faixa de controles.
  • O src com { uri, headers } vale para a foto e para o poster. O arquivo do vídeo vai direto para o <video>, que não manda cabeçalho: sirva o vídeo por endereço assinado.

As setas na lateral, as setas do teclado, PageUp e PageDown e o deslizar de lado passam de imagem. O contador "3 de 8" fica no alto, à esquerda. Na primeira e na última, a seta daquele lado desabilita; com loop, a navegação dá a volta.

Se a seta desabilita com o foco nela, o foco desce para a área da imagem, e não se perde na página: as teclas do visualizador continuam valendo. O mesmo vale para o mais e o menos do zoom, no máximo e no tamanho que cabe.

A vizinha de cada lado é carregada antes de a pessoa pedir, então a troca de imagem não espera a rede. Enquanto a imagem aberta carrega, um giro ocupa o lugar dela; se ela não carrega, a tela diz isso em vez de girar para sempre.

Zoom

Os botões de mais e menos aproximam de uma vez e meia em uma vez e meia, até maxZoom (4 por padrão). O duplo clique na imagem dobra o zoom no ponto clicado, e o segundo volta ao tamanho que cabe. O duplo clique nos botões de anterior e próxima só troca de imagem duas vezes, sem aproximar. A roda do mouse aproxima com Ctrl apertado, que é o mesmo evento que o gesto de pinça do trackpad manda; no toque, a pinça de dois dedos aproxima direto.

Aproximada, a imagem se arrasta para ver o resto, e o deslizar deixa de trocar de imagem: o dedo que arrasta a foto aproximada não pode, de repente, mudar de foto. No teclado, + e - aproximam e afastam, e 0 volta ao tamanho que cabe.

Com zoom, as quatro setas percorrem a foto, de 40 em 40 pixels, sem passar da borda, e são o arrastar de quem não usa ponteiro. A troca de imagem fica com PageUp, PageDown e os botões da lateral. Trocar de imagem sempre volta o zoom ao começo.

Fechar e voltar

Esc, o xis no alto ou o onIndexChange(null) fecham. O foco volta para a miniatura da imagem que estava aberta, e não necessariamente para a que abriu: quem abriu a segunda foto, andou até a quinta e fechou, continua a partir da quinta na grade, com a página rolada até ela.

Controlado

index e onIndexChange: o índice da imagem aberta, contando de zero, ou null com o visualizador fechado. Com thumbnails={false} a grade some, e quem abre é o index, a partir de qualquer botão da tela:

const [index, setIndex] = useState<number | null>(null)

<Button onClick={() => setIndex(0)}>Ver as fotos</Button>
<ImageViewer images={fotos} thumbnails={false} index={index} onIndexChange={setIndex} />

Partes

classNames alcança cada nó pelo nome: thumbnails (a grade), thumbnail (cada botão da grade), viewer (a tela cheia), toolbar (a barra do alto), author (quem mandou e quando), counter, stage (a área da imagem), image, video (o player do item de vídeo), caption e actions (a barra de ações).

labels troca os textos: title (o nome do diálogo, só para o leitor de tela), counter (função da posição e do total), previous, next, close, zoomIn, zoomOut, loading, error, video ("Vídeo") e videoOf, o vídeo com a duração falada.

Quando não usar

  • Um vídeo sozinho, fora de uma galeria, é VideoPlayer, que já abre em tela cheia pelo próprio botão. O visualizador é para quando o vídeo vive no meio das fotos de uma conversa e a pessoa passa de um para o outro.
  • Conteúdo que não é imagem é Dialog. O visualizador existe para a foto ocupar a tela inteira; um formulário ou um texto dentro dele perde o que o Dialog dá (o título visível, o rodapé de ações, o tamanho que cabe no conteúdo).
  • Imagem que só precisa de moldura na página é AspectRatio. Se a pessoa não precisa ampliar nem navegar, a foto fica no próprio card, com a proporção reservada antes de carregar, e nada abre por cima.
  • Fileira de imagens que se percorre sem ampliar é Carousel. Os dois combinam: o carrossel mostra, e o visualizador amplia quando a pessoa pede.

No React Native

Traduz sobre o Modal do core, com as imagens numa FlatList horizontal com pagingEnabled: deslizar troca de imagem, e o voltar do Android fecha. A grade de miniaturas é a mesma, montada no Grid nativo, e cada miniatura é um imagebutton com o alt como nome. O index é controlado, como em todo o pacote nativo: onIndexChange recebe o índice ao abrir e ao navegar, e null ao fechar.

A pinça sai do PanResponder do core, e não do react-native-gesture-handler. O pacote já exige o reanimated, mas não o gesture-handler, e um visualizador de imagem não justifica um peer obrigatório a mais para todo app. Dois dedos aproximam até maxZoom, um dedo arrasta a foto aproximada, e o toque duplo dobra e desfaz o zoom. Com zoom, a fileira para de rolar: o dedo que arrasta a foto não troca de foto. Os botões de mais, menos, anterior e próximo continuam lá, porque o leitor de tela não faz pinça.

Arrastar para baixo fecha, como na galeria do celular: a foto segue o dedo e o fundo esmaece; passou de 120pt, ou soltou rápido, fecha, e senão volta para o lugar. Só com o zoom normal: com zoom, o mesmo arrasto anda pela foto. Com reduzir movimento, a foto não acompanha o dedo, e o arrasto longo fecha do mesmo jeito. O xis continua no alto, para quem não descobre o gesto e para o leitor de tela.

No chat, author e date em cada imagem põem quem mandou e quando no alto, com o contador perto do xis, e actions desenha a barra de ações embaixo, como no web. O palco é escuro nos dois esquemas e o celular não tem variável de cor viva para a barra redefinir: pinte o que vai nela com tokens.media, como os controles da peça.

import { tokens } from '@rivocode/ui-native/tokens'

const INK = { color: tokens.media['media-fg'] }

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  actions={(foto, posicao) => (
    <>
      <Button variant="ghost" onPress={() => responder(posicao)}>
        <Text style={INK}>Responder</Text>
      </Button>
      <Button variant="ghost" onPress={() => encaminhar(posicao)}>
        <Text style={INK}>Encaminhar</Text>
      </Button>
    </>
  )}
/>

Foto e vídeo no mesmo visualizador. O item com kind: "video" entra no meio das fotos, como no web, mas quem toca é o renderVideo: o expo-video é peer opcional e mora em @rivocode/ui-native/video, e a raiz não o importa. De lá sai pronto o renderViewerVideo, que monta o VideoPlayer com o quadro do tamanho do palco e leva os headers do src ao expo-video. O player só existe no item aberto: o vizinho mostra a capa (poster) com o play, e sair do item tira o player de cena, com o vídeo junto. No vídeo não há zoom nem pinça, e arrastar para baixo continua fechando. Sem renderVideo, o item fica na capa, e o modo de desenvolvimento avisa.

import { renderViewerVideo } from '@rivocode/ui-native/video'

<ImageViewer
  images={midia}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  renderVideo={renderViewerVideo}
/>

Baixar salva na galeria pelo saveToGallery. O download liga o botão ao lado do zoom, como no web, mas aqui ele é só a função: salvar na galeria pede o expo-media-library e o expo-file-system, peers opcionais que moram em @rivocode/ui-native/media-library, e a raiz não os importa. O saveToGallery de lá pede a permissão de escrita, baixa o arquivo para o cache com os headers do src, salva na galeria e apaga o cache; cada falha sai como GalleryError, com reason unavailable, permission, download ou save. O unavailable é o Expo Go no Android, que não dá acesso à galeria: ali o saveToGallery só roda num build de desenvolvimento; no iOS o Expo Go tem o módulo. Enquanto a promessa corre, o botão gira e diz "Baixando…"; a resolvida mostra e anuncia labels.downloaded ("Arquivo salvo."), e a rejeitada, labels.downloadError. O padrão dele lê o reason do GalleryError e diz o motivo: no unavailable, "Baixar não funciona no Expo Go do Android: use um build de desenvolvimento."; no permission, que falta a permissão da galeria; no download, que a conexão falhou; no save, que a galeria recusou. Ele aceita também a função do erro, (erro) => string, para o app dizer o motivo dele. downloaded: "" cala o sucesso, para o app que prefere um toast: o useToast aparece por cima do visualizador aberto.

import { saveToGallery } from '@rivocode/ui-native/media-library'

<ImageViewer
  images={midia}
  index={index}
  onIndexChange={setIndex}
  download={async (item) => {
    await saveToGallery(item.src, { name: item.alt, kind: item.kind })
    toast.add({ title: 'Salvo na galeria', type: 'success' })
  }}
/>

caption é string, a vizinha de cada lado é pedida antes por Image.prefetch, e o contador "3 de 8" fica numa região viva que diz também o alt da imagem nova.

SVG entra pelo renderImage. O Image do core não decodifica SVG no iOS ("Error decoding image data"), e a peça não decide como desenhar o arquivo: quem tem SVG desenha com o que já usa, na miniatura e no palco, e devolve undefined para a foto comum continuar no Image. O zoom, o arrasto e o alt ficam na moldura de fora; no palco, chame onLoad e onError, ou o giro não sai.

Imagem que pede cabeçalho baixa pela peça. O src (e o thumbnail) aceita { uri, headers }, como o VideoPlayer e o AudioPlayer. O Image do core ignora os headers da fonte no Android (a API responde 401 em toda foto), então com headers a peça baixa ela mesma por fetch e desenha um data: URI, com o giro enquanto baixa e o aviso de erro se a resposta não for 2xx. Cada endereço baixa uma vez só enquanto a peça vive, e o renderImage recebe o uri final, já baixado. Sem headers, nada muda.

const fotos = mensagens.map((m) => ({
  src: { uri: m.fotoUrl, headers: { 'x-api-key': chave } },
  alt: m.descricao,
}))
import { SvgUri } from 'react-native-svg'

<ImageViewer
  images={plantas}
  index={index}
  onIndexChange={setIndex}
  renderImage={({ uri, width, height, onLoad, onError }) =>
    uri.endsWith('.svg') ? (
      <SvgUri uri={uri} width={width ?? '100%'} height={height ?? '100%'} onLoad={onLoad} onError={onError} />
    ) : undefined
  }
/>

O palco é escuro nos dois esquemas, como no web: as cores saem de tokens.media, e não do tema, então o Modal não clareia no tema claro nem no tema de cliente. O controle desabilitado segue a regra do pacote, a camada inteira a 50%.

As partes vestem pelo mesmo classNames do web, as onze: thumbnails, thumbnail, viewer, toolbar, author, counter, stage, image, video, caption e actions. O className veste a grade de miniaturas, o mesmo nó de thumbnails, porque a peça não tem raiz: a grade e o Modal são irmãos.

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 fecha a peça. O iOS não tem voltar: fecha-se pelo botão da peça ou pelo gesto de escape do VoiceOver, o Z com dois dedos, que chama o mesmo fechar. Ao chegar no fim da rolagem, o iOS estica com mola e o Android estica a borda (Android 12 ou mais novo) ou mostra o brilho (até o 11). É o gesto do sistema, e a peça não o troca. O pedido de permissão do saveToGallery é o do sistema. No iOS pede só para adicionar fotos; no Android 13 ou mais novo pede foto e/ou vídeo conforme o kind; no Android 9 ou mais velho pede acesso ao armazenamento. Recusado, o erro é o mesmo nos dois: GalleryError com reason: 'permission'.

API

PropTipoPadrão
imagesobrigatória

As imagens, na ordem da navegacao.

ImageViewerImage[]sem padrão
actions

A barra de acoes embaixo da imagem aberta, que o app escolhe: Responder, Encaminhar, Salvar.

((image: ImageViewerImage, index: number) => ReactNode)sem padrão
classNames

Classe por parte: `thumbnails`, `thumbnail`, `viewer`, `toolbar`, `author` (quem mandou e quando), `counter`, `stage`, `image`, `video` (o player do item de video), `caption` e `actions`.

Partial<Record<"actions" | "author" | "caption" | "counter" | "image" | "stage" | "thumbnail" | "thumbnails" | "toolbar" | "video" | "viewer", string>>sem padrão
defaultIndex

A imagem aberta ao montar, quando ninguem controla.

number | nullnull
download

Liga o botao Baixar na barra de cima, ao lado do zoom.

boolean | ((image: ImageViewerImage, index: number) => void | Promise<unknown>)sem padrão
index

A imagem aberta, controlada: o indice, contando de zero, ou `null` com o visualizador fechado.

number | nullsem padrão
labels

Os textos da peca, para trocar o idioma ou o termo.

Partial<ImageViewerLabels>sem padrão
loop

Da ultima, a proxima volta a primeira, e vice-versa.

booleanfalse
maxZoom

O zoom maximo, em vezes o tamanho que cabe na tela.

number4
onIndexChange

Chamado ao abrir, ao navegar e com `null` ao fechar.

((index: number | null) => void)sem padrão
thumbnails

Desenha a grade de miniaturas que abre o visualizador.

booleantrue

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.