MessageMedia
Foto e vídeo no balão
Foto sem legenda
Com o Baixar nas ações e no menu do botão direito
Documento no balão
Localização no balão
import { MessageMedia } from '@rivocode/ui/ai'Quando usar
A foto, o vídeo, o documento ou a localização dentro do balão de uma
conversa: a mídia na proporção dela, o vídeo como miniatura com o play no
centro e a duração no canto, o arquivo e o lugar como cartão, e o toque que
abre a mídia inteira. Vive em @rivocode/ui/ai, ao lado da Message, que
reconhece a peça como filho direto e põe a hora no lugar certo. Filho
direto quer dizer sem componente seu no meio: embrulhada num componente do
app, ela não é reconhecida e perde a hora por cima e a borda apertada. E
tem de ser a filha única: um {cond ? <X /> : null} ao lado já faz dos
filhos uma lista, e a hora some da foto. O que é condicional vai para fora
da Message ou para o caption.
import { Message, MessageMedia } from '@rivocode/ui/ai'
<Message variant="chat" role="assistant" author="Marina Costa" time="14:32">
<MessageMedia kind="video" src={video.url} poster={video.capa} duration={12} onOpen={abrirVideo} />
</Message>
<Message variant="chat" role="user" time="14:33" status="read">
<MessageMedia kind="image" src={foto.url} width={1600} height={1000} caption="Fachada nova da loja" onOpen={abrirFoto} />
</Message>
Documento
kind="document" é o cartão do arquivo: o ícone do tipo num quadro, o name
como título (cortado com reticências quando não cabe), e embaixo o tipo por
extenso e o tamanho ("PDF · 120 KB"). O tipo sai da extensão do name, e o
mimeType decide quando ela falta: "PDF", "Planilha", "Documento do Word",
"Documento" (o texto que não é do Word), "Imagem",
"Arquivo compactado", "Apresentação", e a extensão em maiúscula ("DWG") para o
que a peça não conhece. size é em bytes, escrito pelo mesmo formatador do
FileUpload.
À direita fica o Baixar, com o mesmo download da foto e do vídeo: true baixa
o src e salva com o name; uma função fica com o download e gira até a
promessa acabar. Dentro de uma Message, o botão é o do cartão e não se repete
nas ações; o item "Baixar" do contextMenu e a linha de falha continuam os da
Message. Fora dela, o cartão desenha o botão e a linha sozinho. Com onOpen,
o resto do cartão é o botão que abre o arquivo.
A legenda igual ao name não aparece. O WhatsApp manda o nome do arquivo
como legenda quando quem enviou não escreveu nenhuma, e o balão diria
"10.pdf" duas vezes. A legenda diferente do nome sai embaixo do cartão, como na
foto.
<Message variant="chat" role="assistant" author="Marina Costa" time="10:02" contextMenu>
<MessageMedia
kind="document"
src={{ uri: anexo.url, headers }}
name={anexo.nome}
mimeType={anexo.tipo}
size={anexo.bytes}
caption={anexo.legenda}
onOpen={abrirAnexo}
download
/>
</Message>
Localização
kind="location" é o cartão do lugar: o alfinete, o name ("Localização" sem
ele), o address embaixo ("Abrir no mapa" sem ele) e o ícone de sair no fim.
O cartão inteiro é o botão do onOpen, que abre o mapa que a tela escolher.
A peça não desenha mapa. A miniatura de um serviço de mapas mandaria as
coordenadas do contato para fora, e isso é decisão do app. Quem quiser o mapa
passa renderMap, que entra em cima da linha do lugar, dentro do mesmo botão.
<MessageMedia
kind="location"
name={lugar.nome}
address={lugar.endereco}
onOpen={() => window.open(linkDoMapa(lugar), '_blank', 'noopener')}
/>
A hora aparece uma vez só
Dentro de uma Message variant="chat", a hora e os tiques vão por cima da
mídia, no canto de baixo, numa pílula escura (o media-stage a 70%), quando
não há legenda: assim leem sobre foto branca e sobre foto escura, a 4,5:1 no
pior caso. Com caption, a legenda sai embaixo da mídia e a hora vai depois
dela, na cor de sempre. Nunca nos dois lugares. O balão aperta a borda em volta
da mídia, e a legenda e a hora ganham o respiro de volta.
No document e no location não há foto para pôr a hora por cima: ela vai
embaixo do cartão, na cor de sempre, ou depois da legenda quando ela existe.
Por cima da mídia, os tiques ficam na cor da pílula, e read e delivered
se distinguem pela palavra que o leitor de tela ouve, e não pela cor: o tom de
acento do tema claro não lê sobre o fundo escuro.
Vídeo sem player
kind="video" é a miniatura, e não o player: o poster na proporção do
vídeo, o play no centro e a duração ("0:12") no canto de baixo, sem barra de
controles. O toque chama onOpen, e quem decide o que abre é a tela: o
VideoPlayer numa folha ou em tela cheia. Sem poster, o web mostra o
primeiro quadro do arquivo, mudo e fora do foco; no celular, o palco escuro com
o play.
A proporção
aspectRatio vence, depois width e height. Passe um dos dois quando a API
souber, e o balão nasce do tamanho certo, sem pular quando a imagem chega. Sem
nenhum, o balão nasce em 4:3 e passa para a proporção da mídia quando ela
carrega. A proporção fica entre 9:16 e 2:1; a mídia mais alta ou mais larga
que isso é recortada pelo centro, para um vídeo vertical não ocupar a tela
inteira.
O endereço
src e poster aceitam o endereço ou { uri, headers }, o mesmo formato do
ImageViewer, para a foto que vem de uma API com x-api-key. Com headers, a
peça baixa por fetch e mostra o resultado; o vídeo em si não é baixado aqui.
Foto que falha mostra o aviso no lugar, e o balão continua do mesmo tamanho.
Baixar
download liga o Baixar da Message que tem a mídia como filha direta: o
botão nas ações e o item "Baixar" do contextMenu (no document, o botão é o
do cartão). É o mesmo download do
ImageViewer: true baixa o src com os mesmos headers e salva com o nome
do endereço ou do label; uma função fica com o download, e a promessa
rejeitada vira a linha de falha da Message. Fora de uma Message, a prop não
desenha nada na foto e no vídeo; no documento, o cartão desenha o botão.
<Message variant="chat" role="assistant" author="Marina Costa" time="14:32" contextMenu>
<MessageMedia kind="image" src={{ uri: foto.url, headers }} label="Fachada da loja" onOpen={abrir} download />
</Message>
Nomes
A foto se chama "Foto", o vídeo "Vídeo de 12 segundos", com a duração por
extenso, o documento "Documento 10.pdf, PDF, 120 KB", e a localização pelo
nome e pelo endereço ("Loja Centro, Rua XV de Novembro, 100"). label troca o
nome inteiro ("Comprovante do Pix"), e labels troca as palavras (image,
video, videoOf, file, location, openMap, e download,
downloading, downloadError e downloaded do Baixar do cartão fora de uma
Message). Sem onOpen, a mídia é imagem, e não botão.
<MessageMedia kind="image" src={comprovante.url} label="Comprovante do Pix" onOpen={abrir} />
Partes
classNames alcança media (a caixa da foto, da miniatura ou do cartão),
play e duration do vídeo, card (a linha do cartão), icon (o quadro do
ícone), title, detail (a linha de apoio), action (o Baixar) e map do
documento e da localização, e caption e meta (a caixa da hora, por cima ou
embaixo) em todos.
Quando não usar
- A galeria de fotos de um registro, fora da conversa, é
ImageViewer, que já traz a grade de miniaturas e o visualizador. AMessageMediaé uma mídia por balão, e oImageVieweré o que ela abre. - O vídeo que toca no lugar, com barra e velocidade, é
VideoPlayer. A miniatura do balão não toca: a conversa rola, e um vídeo tocando no meio dela é o que ninguém pediu. - O anexo fora da conversa (o PDF de um pedido, a lista de arquivos de um
registro) é
FileUploadItemou umItemcom o ícone do tipo. O cartão dodocumenté o arquivo que chegou numa mensagem, com a hora dela. - O endereço num formulário ou num detalhe de registro é texto num
DescriptionList, e não o cartão dolocation, que é o lugar que alguém mandou na conversa.
No React Native
Traduz, no caminho próprio @rivocode/ui-native/ai, com os mesmos kind, src, poster, width, height, aspectRatio, duration, onOpen, label, caption e os mesmos nomes ("Foto", "Vídeo de 12 segundos"). Dentro de uma Message de chat, a hora vai por cima da mídia sem legenda, na mesma pílula escura do web, e depois da legenda com ela.
Documento e localização, como no web. kind="document" é o mesmo cartão, com o mesmo ícone do lucide por tipo, o name numa linha só, o tipo e o tamanho embaixo, e mimeType e size com o mesmo sentido; a legenda igual ao name também não aparece. kind="location" é o mesmo cartão do lugar, com name, address, onOpen e renderMap, e sem mapa desenhado pela peça. A hora vai embaixo do cartão. Os nomes falados são os mesmos ("Documento 10.pdf, PDF, 120 KB").
O Baixar do documento é uma função. No web o download={true} baixa o src pelo navegador; aqui não há onde salvar sem o expo-file-system, então o download do cartão só aceita a função, e quem salva é o app (o saveToGallery serve para foto e vídeo; documento vai pelo expo-file-system ou pelo expo-sharing). O botão é o IconButton do cartão, gira enquanto a promessa corre, e o fim ou a falha saem numa linha embaixo do cartão, anunciada. Não há menu do toque longo, como na Message.
Sem peer. A miniatura do vídeo é o Image do core com o poster, e não um player: o expo-video mora em @rivocode/ui-native/video, e o caminho de IA não o cobra de quem só mostra foto. Sem poster, o vídeo é o palco escuro com o play, em 4:3 e sem duração; o web mostra o primeiro quadro, que aqui pede o módulo nativo.
O primeiro quadro vem do useVideoPreview, de @rivocode/ui-native/video. Ele abre o arquivo num player mudo do expo-video, com os headers do src, tira o quadro, a proporção e a duração, e solta o player. Proporção e duração entram pelas props de sempre. O quadro é um VideoThumbnail, imagem nativa que o Image do core não abre e o do expo-image abre: ele entra pelo renderPoster, que só existe no celular e vence o poster. Sem o expo-image no app, fique com a proporção e a duração, e o palco continua escuro.
import { Image } from 'expo-image'
import { useVideoPreview } from '@rivocode/ui-native/video'
const previa = useVideoPreview(video.src)
<MessageMedia
kind="video"
src={video.src}
aspectRatio={previa.aspectRatio}
duration={previa.duration}
renderPoster={
previa.thumbnail
? () => <Image source={previa.thumbnail} contentFit="cover" style={{ width: '100%', height: '100%' }} />
: undefined
}
/>
O hook guarda o resultado por endereço, os últimos 40, então rolar a conversa de volta não abre o arquivo de novo; abre no máximo dois por vez, e o resto espera na fila; e o balão que sai da tela antes de terminar solta o player dele. O arquivo que não abre dá status: "error" e não fica guardado: montar de novo tenta de novo.
{ uri, headers } baixa por fetch, como no ImageViewer nativo, e mostra um data: URI, porque o Image do Android ignora os headers da fonte. A proporção sai do onLoad da imagem quando nenhuma medida vem.
Sem download na foto e no vídeo. O Baixar do web vive no botão e no menu do botão direito da Message, e o celular não tem esse menu. Para salvar a mídia, ponha um IconButton nas actions da Message que chame o saveToGallery de @rivocode/ui-native/media-library.
As partes vestem pelo mesmo classNames do web: media, play, duration, caption, meta, card, icon, title, detail, action e map.
No iOS e no Android. 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 |
|---|---|
kindobrigatória`image` e a foto, inteira no balao; `video` e a miniatura com o play no centro e a duracao no canto; `document` e o cartao do arquivo, com o icone do tipo, o nome, o tipo e o tamanho, e o Baixar a direita; `location` e o cartao do lugar, que abre no mapa. | MessageMediaKind |
addressEm `location`, o endereco: a linha de baixo do cartao, e sem ele "Abrir no mapa". | string |
aspectRatioA proporcao, largura sobre altura. | number |
captionA legenda, embaixo da midia. | ReactNode |
classNamesClasse por parte: `media`, `play` e `duration` da foto e do video; `card` (a linha do cartao), `icon` (o quadro do icone), `title`, `detail` (a linha de apoio), `action` (o Baixar) e `map` no `document` e no `location`; e `caption` e `meta` em todos. | Partial<Record<"action" | "caption" | "card" | "detail" | "duration" | "icon" | "map" | "media" | "meta" | "play" | "title", string>> |
downloadLiga o Baixar da `Message` que tem esta midia como filha direta: o botao nas acoes e o item do `contextMenu`. | boolean | (() => void | Promise<unknown>) |
durationA duracao do video, em segundos: o "0:12" do canto e o "Video de 12 segundos" do leitor de tela. | number |
heightA altura da midia, em pixels, junto com `width`. | number |
labelO nome acessivel. | string |
labelsOs textos da peca: `image` ("Foto"), `video` ("Video"), `videoOf`, o video com a duracao falada, `file` (a palavra que abre o nome do cartao do arquivo), `location` ("Localização"), `openMap` ("Abrir no mapa"), e os do Baixar do `document` fora de uma `Message`: `download`, `downloading`, `downloadError` e `downloaded`. | Partial<MessageMediaLabels> |
metaA hora e os tiques. | ReactNode |
mimeTypeEm `document`, o tipo do arquivo ("application/pdf"), quando o `name` nao tem extensao. | string |
nameEm `document`, o nome do arquivo ("10.pdf"): o titulo do cartao, cortado com reticencias, e de onde sai o tipo pela extensao. | string |
onOpenChamado no clique ou no Enter: abra o `ImageViewer` com a foto, o `VideoPlayer` em tela cheia com o video, o documento numa aba ou o lugar no mapa. | (() => void) |
posterA miniatura do video, no mesmo formato do `src`. | ImageSource |
renderMapEm `location`, o mapa desenhado pelo app, em cima da linha do lugar. | (() => ReactNode) |
sizeEm `document`, o tamanho em bytes, escrito pela peca ("120 KB") ao lado do tipo. | number |
srcA foto, ou o arquivo do video: o endereco, ou `{ uri, headers }` para a imagem que pede cabecalho (uma API com `x-api-key`), como no `ImageViewer`. | ImageSource |
widthA largura da midia, em pixels, junto com `height`: so a proporcao conta, e ela vale desde o primeiro quadro, sem o balao pular quando a imagem chega. | number |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.