ImageViewer
Grade de miniaturas
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
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(oudownload={true}) baixa pela própria peça o item aberto, foto ou vídeo, com os mesmosheadersdosrc, e salva com o nome do endereço (fachada.jpg). Sem extensão no endereço, o nome vem doalte a extensão do tipo que o servidor mandou. O arquivo passa por umBlobe 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; comheaders, 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 mostralabels.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: comaltvazio, o leitor de tela ouve "2 de 3: Vídeo de 12 segundos", a mesma frase doMessageMediano balão. Umaltescrito 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+,-e0nã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.PageUpePageDowntrocam de item sempre. O deslizar de lado troca de item quando começa no quadro, e não na faixa de controles. - O
srccom{ uri, headers }vale para a foto e para oposter. O arquivo do vídeo vai direto para o<video>, que não manda cabeçalho: sirva o vídeo por endereço assinado.
Navegar
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 oDialogdá (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
| Prop | Tipo | Padrão |
|---|---|---|
imagesobrigatóriaAs imagens, na ordem da navegacao. | ImageViewerImage[] | sem padrão |
actionsA barra de acoes embaixo da imagem aberta, que o app escolhe: Responder, Encaminhar, Salvar. | ((image: ImageViewerImage, index: number) => ReactNode) | sem padrão |
classNamesClasse 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 |
defaultIndexA imagem aberta ao montar, quando ninguem controla. | number | null | null |
downloadLiga o botao Baixar na barra de cima, ao lado do zoom. | boolean | ((image: ImageViewerImage, index: number) => void | Promise<unknown>) | sem padrão |
indexA imagem aberta, controlada: o indice, contando de zero, ou `null` com o visualizador fechado. | number | null | sem padrão |
labelsOs textos da peca, para trocar o idioma ou o termo. | Partial<ImageViewerLabels> | sem padrão |
loopDa ultima, a proxima volta a primeira, e vice-versa. | boolean | false |
maxZoomO zoom maximo, em vezes o tamanho que cabe na tela. | number | 4 |
onIndexChangeChamado ao abrir, ao navegar e com `null` ao fechar. | ((index: number | null) => void) | sem padrão |
thumbnailsDesenha a grade de miniaturas que abre o visualizador. | boolean | true |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.