Pular para o conteúdo
IA

MessageMedia

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

Foto e vídeo no balão

14:32
Fachada nova da loja
14:33Lida

Foto sem legenda

09:14Entregue

Com o Baixar nas ações e no menu do botão direito

14:32

Documento no balão

10:02

Segue a planilha com o fechamento
10:05Lida

Localização no balão

11:20
11:21Entregue
Importar
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. A MessageMedia é uma mídia por balão, e o ImageViewer é 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) é FileUploadItem ou um Item com o ícone do tipo. O cartão do document é 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 do location, 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

PropTipo
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
address

Em `location`, o endereco: a linha de baixo do cartao, e sem ele "Abrir no mapa".

string
aspectRatio

A proporcao, largura sobre altura.

number
caption

A legenda, embaixo da midia.

ReactNode
classNames

Classe 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>>
download

Liga o Baixar da `Message` que tem esta midia como filha direta: o botao nas acoes e o item do `contextMenu`.

boolean | (() => void | Promise<unknown>)
duration

A duracao do video, em segundos: o "0:12" do canto e o "Video de 12 segundos" do leitor de tela.

number
height

A altura da midia, em pixels, junto com `width`.

number
label

O nome acessivel.

string
labels

Os 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>
meta

A hora e os tiques.

ReactNode
mimeType

Em `document`, o tipo do arquivo ("application/pdf"), quando o `name` nao tem extensao.

string
name

Em `document`, o nome do arquivo ("10.pdf"): o titulo do cartao, cortado com reticencias, e de onde sai o tipo pela extensao.

string
onOpen

Chamado 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)
poster

A miniatura do video, no mesmo formato do `src`.

ImageSource
renderMap

Em `location`, o mapa desenhado pelo app, em cima da linha do lugar.

(() => ReactNode)
size

Em `document`, o tamanho em bytes, escrito pela peca ("120 KB") ao lado do tipo.

number
src

A 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
width

A 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.

@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.