Image

Apresentação

O componente Image é responsável por exibir imagens na interface, oferecendo recursos avançados como zoom com gestos (pinch zoom), carregamento otimizado e fallback para casos de erro.

Quando usar

• Para exibir imagens em qualquer parte da interface
• Quando precisar de imagens responsivas
• Para implementar zoom em imagens com gestos
• Quando precisar de carregamento otimizado de imagens
• Para exibir imagens com fallback em caso de erro

Forma básica de uso

import { Image } from 'eitri-luminus';

// Imagem básica
<Image
  src="/caminho/da/imagem.jpg"
  alt="Descrição da imagem"
  width="100%"
  height="auto"
/>

// Imagem com zoom
<Image
  src="/caminho/da/imagem.jpg"
  alt="Descrição da imagem"
  pinchZoom
  zoomMaxScale={3}
/>

// Imagem com carregamento otimizado
<Image
  src="/caminho/da/imagem.jpg"
  alt="Descrição da imagem"
  loading="lazy"
  decoding="async"
/>

// Imagem com srcSet para diferentes resoluções
<Image
  src="/imagem-padrao.jpg"
  srcSet="/imagem-pequena.jpg 300w, /imagem-media.jpg 600w, /imagem-grande.jpg 900w"
  sizes="(max-width: 300px) 300px, (max-width: 600px) 600px, 900px"
  alt="Imagem responsiva"
/>

Propriedades

Propriedade	Tipo	Descrição
src	string	URL da imagem
alt	string	Texto alternativo para acessibilidade
loading	'eager' | 'lazy'	Estratégia de carregamento da imagem
decoding	'sync' | 'async'	Estratégia de decodificação da imagem
width	string | number	Largura da imagem
height	string | number	Altura da imagem
title	string	Título da imagem (tooltip)
srcSet	string	Conjunto de imagens para diferentes resoluções
sizes	string	Tamanhos das imagens para diferentes viewports
onLoad	() => void	Função chamada quando a imagem é carregada
pinchZoom	boolean	Habilita zoom com gestos (pinch)
zoomMaxScale	number	Escala máxima do zoom (padrão: 2)
zoomMaxTranslate	number	Distância máxima de translação do zoom (padrão: 100)

Heranças

O componente Image herda todas as propriedades comuns da biblioteca através da interface CommonProps, que inclui:

• Propriedades de estilo (margin, padding, etc)
• Propriedades de layout (flex, grid, etc)
• Propriedades de posicionamento
• Propriedades de acessibilidade
• Propriedades de identificação (id, data-e)

Eventos

O componente Image suporta eventos do elemento HTML <img> e eventos de zoom. Os eventos do elemento img recebem um objeto React.SyntheticEvent<HTMLImageElement, Event>.

Eventos do elemento img

• onLoadStart: Disparado quando o navegador começa a buscar a imagem
• onError: Disparado quando ocorre um erro no carregamento da imagem
• onAbort: Disparado quando o carregamento da imagem foi abortado
• onLoad: Disparado quando a imagem foi carregada com sucesso

Eventos de zoom

• onZoomStart: Disparado quando o usuário começa o gesto de zoom (pinch) - requer pinchZoom={true}
• onZoomEnd: Disparado quando o usuário termina o gesto de zoom (pinch) - requer pinchZoom={true}

Exemplo de uso de eventos

<Image
  src="/imagem.jpg"
  alt="Descrição"
  onLoad={(e) => console.log('Imagem carregada')}
  onError={(e) => console.error('Erro ao carregar imagem', e)}
  onLoadStart={(e) => console.log('Iniciando carregamento')}
/>

// Com eventos de zoom
<Image
  src="/imagem.jpg"
  alt="Descrição"
  pinchZoom
  onZoomStart={() => console.log('Zoom iniciado')}
  onZoomEnd={() => console.log('Zoom finalizado')}
/>

Controle através de Ref

O componente Image estende BaseComponent e expõe métodos públicos que podem ser acessados através de uma ref. Isso permite controle programático completo da imagem.

Criando uma ref

import React, { useRef } from 'react';
import { Image } from 'eitri-luminus';

function MyComponent() {
  const imageRef = useRef(null);

  return (
    <Image
      ref={imageRef}
      src="/imagem.jpg"
      alt="Descrição"
    />
  );
}

Métodos disponíveis

Informações da imagem

• getNaturalWidth(): number - Retorna a largura natural da imagem em pixels (dimensão original)
• getNaturalHeight(): number - Retorna a altura natural da imagem em pixels (dimensão original)
• getCurrentWidth(): number - Retorna a largura atual do elemento em pixels (considerando CSS aplicado)
• getCurrentHeight(): number - Retorna a altura atual do elemento em pixels (considerando CSS aplicado)
• getComplete(): boolean - Retorna se a imagem foi carregada completamente
• getImageError(): boolean - Retorna se houve erro no carregamento da imagem

Controle

• reload(): void - Recarrega a imagem

Exemplos de uso com ref

Obter informações da imagem

import React, { useRef } from 'react';
import { Image, Button, View, Text } from 'eitri-luminus';

function ImageInfo() {
  const imageRef = useRef(null);

  const showInfo = () => {
    if (imageRef.current) {
      const naturalWidth = imageRef.current.getNaturalWidth();
      const naturalHeight = imageRef.current.getNaturalHeight();
      const currentWidth = imageRef.current.getCurrentWidth();
      const currentHeight = imageRef.current.getCurrentHeight();
      const complete = imageRef.current.getComplete();
      const hasError = imageRef.current.getImageError();

      console.log({
        naturalWidth,
        naturalHeight,
        currentWidth,
        currentHeight,
        complete,
        hasError,
      });
    }
  };

  return (
    <View>
      <Image
        ref={imageRef}
        src="/imagem.jpg"
        alt="Descrição"
        className="w-full"
      />
      <Button onClick={showInfo}>Mostrar Informações</Button>
    </View>
  );
}

Recarregar imagem

import React, { useRef } from 'react';
import { Image, Button, View } from 'eitri-luminus';

function ImageReload() {
  const imageRef = useRef(null);

  const handleReload = () => {
    imageRef.current?.reload();
  };

  return (
    <View>
      <Image
        ref={imageRef}
        src="/imagem.jpg"
        alt="Descrição"
        className="w-full"
      />
      <Button onClick={handleReload}>Recarregar Imagem</Button>
    </View>
  );
}

Observações sobre refs

• Os métodos funcionam apenas quando a imagem está carregada
• getNaturalWidth() e getNaturalHeight() retornam 0 se a imagem não estiver carregada
• O método reload() reseta o estado de erro e recarrega a imagem

Observações

• O componente exibe um placeholder quando a imagem não carrega
• O zoom com gestos é suportado apenas em dispositivos touch
• O carregamento lazy é recomendado para imagens abaixo da dobra
• O componente é responsivo por padrão
• Recomenda-se sempre fornecer um texto alternativo para acessibilidade
• O zoom é limitado para evitar problemas de performance
• O componente suporta imagens em diferentes formatos (JPG, PNG, WebP, etc)
• Os métodos de ref funcionam apenas quando a imagem está carregada