Chat de Imagem

Posicionamento Baseado em Porcentagem

O Image Chat usa coordenadas baseadas em porcentagem em vez de coordenadas em pixels para posicionar marcadores de chat nas imagens. Quando um usuário clica em uma imagem, o widget converte as coordenadas em pixels do clique em porcentagens da largura e altura da imagem. Essa abordagem garante que os marcadores permaneçam no local correto, independentemente de como a imagem é exibida.

Por exemplo, se um usuário clica a 250 pixels da borda esquerda de uma imagem de 1000px de largura, o widget armazena isso como 25% a partir da esquerda. Quando outro usuário visualiza a mesma imagem com 500px de largura em um dispositivo móvel, o marcador aparece a 125 pixels da esquerda, o que ainda corresponde a 25% da largura.

Benefícios para Layouts Responsivos

Esse sistema de porcentagem faz com que o Image Chat funcione perfeitamente em todos os tamanhos e orientações de dispositivos. Suas imagens podem ser exibidas em tamanhos diferentes dependendo da largura da tela, das regras CSS ou das restrições do contêiner, mas os marcadores sempre se alinham corretamente aos locais pretendidos.

Usuários em computadores desktop com monitores grandes veem os marcadores nas mesmas posições relativas que usuários em smartphones com telas pequenas. Os marcadores escalam proporcionalmente com a própria imagem.

Escala da Imagem e Proporção

Desde que sua imagem mantenha sua proporção ao ser escalada (que é o comportamento padrão do navegador), os marcadores baseados em porcentagem permanecerão perfeitamente alinhados. O widget assume que as imagens escalam proporcionalmente e calcula as posições com base nessa premissa.

Se você aplicar CSS que distorça a proporção da imagem (como usar object-fit: cover com dimensões específicas), as posições dos marcadores podem não se alinhar corretamente. Para obter os melhores resultados, permita que as imagens escalem naturalmente ou use object-fit: contain para manter a proporção.

Dimensionamento do Quadrado de Chat

O tamanho visual dos marcadores de chat também é baseado em porcentagem. A opção de configuração chatSquarePercentage tem o padrão de 5%, o que significa que cada quadrado tem 5% da largura da imagem. Isso garante um peso visual consistente em diferentes tamanhos de imagem.

Em uma imagem de 1000px de largura com a configuração padrão de 5%, os marcadores têm 50px de lado. Em uma imagem de 500px de largura, os mesmos marcadores têm 25px de lado. Eles permanecem proporcionais ao tamanho da imagem.

Comportamento em Dispositivos Móveis

Em telas com menos de 768px de largura, o Image Chat muda para um layout otimizado para dispositivos móveis. As janelas de chat abrem em tela cheia em vez de flutuar ao lado do marcador. Isso proporciona melhor usabilidade em telas pequenas, onde janelas flutuantes obscureceriam parte demais da imagem.

Os marcadores em si permanecem visíveis e clicáveis em suas posições baseadas em porcentagem. Os usuários ainda podem ver onde todas as discussões estão localizadas e tocar nos marcadores para abrir a interface de chat em tela cheia.

Carregamento Dinâmico de Imagens

O sistema baseado em porcentagem funciona corretamente mesmo quando as imagens são carregadas de forma assíncrona ou mudam de tamanho após o carregamento da página. O widget monitora o elemento da imagem e recalcula as posições dos marcadores sempre que as dimensões da imagem mudam.

Se você estiver usando carregamento tardio (lazy-loading) de imagens ou implementando imagens responsivas com tamanhos diferentes em diferentes breakpoints, os marcadores se ajustam automaticamente quando o tamanho da imagem muda.

Consistência entre Dispositivos

Como as coordenadas são armazenadas como porcentagens no banco de dados, uma discussão criada em um computador desktop aparece exatamente no mesmo local relativo quando visualizada em um tablet ou telefone. Os usuários podem colaborar entre dispositivos sem nenhuma inconsistência de posicionamento.

Isso funciona bidirecionalmente. Uma discussão criada ao tocar em um ponto específico em um dispositivo móvel aparece na mesma posição relativa quando visualizada em um monitor desktop grande.

Considerações sobre o Viewport

O widget calcula as porcentagens em relação ao próprio elemento da imagem, não ao viewport. Isso significa que rolar a página ou alterar o tamanho da janela do navegador não afeta as posições dos marcadores. Os marcadores permanecem ancorados aos seus locais na imagem, independentemente das mudanças no viewport.

Preparando o Conteúdo para o Futuro

A abordagem baseada em porcentagem torna suas discussões em imagens resilientes a mudanças de layout, design ou ecossistema de dispositivos. À medida que novos tamanhos de tela e dispositivos surgem, as discussões existentes continuarão a ser exibidas corretamente sem exigir atualizações ou migrações.

Suporte a Modo Escuro

O Image Chat inclui suporte integrado ao modo escuro. Quando você define hasDarkBackground: true na sua configuração, as janelas de chat e os elementos da UI ajustam-se automaticamente para funcionar bem em fundos escuros.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    hasDarkBackground: true
});

O estilo do modo escuro é aplicado às janelas de chat, aos marcadores quadrados e a todos os elementos interativos. Se o seu site possui um alternador de modo escuro, você pode reinicializar o widget quando o modo mudar, ou usar a abordagem de classe no body descrita abaixo.

Modo Escuro Dinâmico

Se o modo escuro do seu site é controlado adicionando a classe .dark ao elemento body, a UI do Image Chat irá respeitar isso automaticamente sem requerer reinicialização. Os estilos do widget são projetados para responder à presença dessa classe.

/* Seu CSS de modo escuro */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

Estilização Personalizada com CSS

Você pode personalizar a aparência dos marcadores, das janelas de chat e de outros elementos usando CSS. O widget adiciona classes específicas que você pode direcionar em sua folha de estilos.

Os quadrados e janelas de chat usam o sistema de estilos de balões de comentário do FastComments, então quaisquer personalizações que você aplicou ao widget de comentários padrão também afetarão o Image Chat.

Tamanho do Quadrado de Chat

A opção chatSquarePercentage controla o tamanho dos marcadores clicáveis. O padrão é 5% da largura da imagem:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    chatSquarePercentage: 7  // Quadrados maiores e mais visíveis
});

Valores menores criam marcadores mais sutis que se misturam à imagem. Valores maiores tornam os marcadores mais proeminentes e fáceis de clicar, especialmente em dispositivos móveis ou por motivos de acessibilidade.

Comportamento em Dispositivos Móveis

Em telas com largura inferior a 768px, o Image Chat muda automaticamente para um layout otimizado para dispositivos móveis. As janelas de chat aparecem em fullscreen em vez de flutuarem ao lado dos marcadores, proporcionando melhor usabilidade em telas pequenas.

Os marcadores permanecem visíveis em suas posições responsivas na imagem. Os usuários podem tocar em qualquer marcador para abrir a interface de chat em tela cheia. Esse comportamento é integrado e não requer nenhuma configuração.

Aparência da Janela de Chat

As janelas de chat têm 300px de largura no desktop com uma flecha de 16px apontando para o marcador. As janelas se posicionam automaticamente com base no espaço disponível da viewport, usando classes de posicionamento como to-right, to-left, to-top, e to-bottom.

Você pode adicionar CSS personalizado para ajustar cores, fontes, espaçamento ou outras propriedades visuais dessas janelas. As janelas de chat usam a mesma estrutura de componentes do widget padrão do FastComments, portanto herdam quaisquer personalizações globais que você aplicou.

Inicialização Preguiçosa

As janelas de chat são inicializadas ao passar o mouse para usuários de desktop ou imediatamente quando criadas. Isso reduz a sobrecarga de carregamento inicial, renderizando a interface de chat somente quando os usuários realmente interagem com um marcador.

A inicialização preguiçosa ocorre de forma transparente. Os usuários não percebem qualquer atraso, mas o navegador não precisa renderizar dezenas de janelas de chat ocultas se você tiver muitos marcadores em uma imagem.

Localização

O Image Chat suporta todas as mesmas opções de localização que o widget padrão do FastComments. Defina a opção locale para exibir o texto da UI em diferentes idiomas:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    locale: 'fr'  // Francês
});

O FastComments suporta dezenas de idiomas. A configuração de locale afeta todo o texto da UI, incluindo prompts, botões e texto de placeholder.

Opções de Personalização Herdadas

Como o Image Chat estende o widget de comentários padrão, ele herda todas as opções de personalização do widget base. Isso inclui classes CSS personalizadas, traduções personalizadas, customização de avatar, formatação de data e muito mais.

Veja a documentação principal de personalização do FastComments para a lista completa de opções de personalização disponíveis.

Trabalhando com Fontes Personalizadas

Se o seu site usa fontes personalizadas, a UI do Image Chat herdará essas fontes do CSS da sua página. As janelas de chat são renderizadas dentro do DOM da sua página e respeitam as configurações de tipografia existentes.

Para melhores resultados, garanta que suas fontes personalizadas sejam carregadas antes de inicializar o Image Chat, ou aceite que pode haver um breve flash de texto sem estilo enquanto as fontes carregam.

Design Visual dos Marcadores

Os marcadores quadrados têm um design visual sutil que os torna perceptíveis sem sobrecarregar a imagem. Você pode personalizar sua aparência com CSS se quiser um tratamento visual diferente.

Os marcadores incluem estados de hover que fornecem feedback quando os usuários movem o mouse sobre eles. Em dispositivos com touch, a interação por toque fornece feedback imediato abrindo a janela de chat.

Atualizações em Tempo Real

Image Chat usa conexões WebSocket para sincronizar todas as conversas em tempo real entre todos os usuários conectados. Quando alguém cria um novo marcador, adiciona um comentário ou exclui uma discussão, todos os outros usuários visualizando a mesma imagem veem a atualização imediatamente sem precisar atualizar a página.

Como a sincronização via WebSocket funciona

Quando você inicializa o Image Chat, o widget estabelece uma conexão WebSocket com os servidores do FastComments. Essa conexão permanece aberta durante a sessão do usuário e fica escutando por atualizações relacionadas à imagem atual.

O sistema WebSocket usa três tipos de mensagens de broadcast para o Image Chat. O evento new-image-chat é disparado quando alguém cria um novo marcador na imagem. O evento image-chat-updated é disparado quando alguém atualiza uma conversa existente. O evento deleted-image-chat é disparado quando alguém exclui um marcador.

Sistema de ID de Broadcast

Para evitar efeitos de eco em que os usuários veem suas próprias ações sendo retransmitidas de volta para eles, cada atualização inclui um broadcastId único. Quando um usuário cria ou atualiza um marcador, seu cliente gera um UUID para essa operação. Quando o WebSocket retransmite a atualização para todos os clientes, o cliente de origem ignora a atualização porque ela corresponde ao seu próprio broadcastId.

Isso garante uma interação fluida, onde os usuários veem suas alterações imediatamente na interface sem esperar a viagem de ida e volta pelo servidor, enquanto ainda garante que todos os outros usuários recebam a atualização.

Resiliência da Conexão

Se a conexão WebSocket cair devido a problemas de rede ou manutenção do servidor, o widget tenta reconectar automaticamente. Durante o período de reconexão, os usuários ainda podem interagir com marcadores existentes, mas não verão atualizações em tempo real de outros usuários até que a conexão seja restabelecida.

Uma vez reconectado, o widget ressincroniza para garantir que nenhuma atualização tenha sido perdida. Isso acontece de forma transparente, sem exigir intervenção do usuário.

Considerações sobre Largura de Banda

As mensagens WebSocket são leves e contêm apenas as informações essenciais necessárias para sincronizar o estado. Criar um novo marcador normalmente usa menos de 1KB de largura de banda. O sistema também inclui agrupamento inteligente para reduzir a frequência de mensagens durante períodos de alta atividade.

Suas métricas de uso no painel do FastComments rastreiam pubSubMessageCount e pubSubBandwidth para que você possa monitorar a atividade de sincronização em tempo real em seus sites.

Sincronização entre abas

Se um usuário tiver a mesma página aberta em várias abas do navegador, as atualizações em uma aba aparecem imediatamente nas outras abas. Isso funciona através do mesmo mecanismo de sincronização por WebSocket e não requer qualquer configuração adicional.

Os usuários podem ter seu site aberto em vários dispositivos simultaneamente, e todos eles permanecerão sincronizados. Um marcador criado em um computador desktop aparece instantaneamente no tablet do usuário se ambos os dispositivos estiverem visualizando a mesma imagem.

Segurança

As mensagens WebSocket são transmitidas por conexões seguras (WSS) e incluem validação do tenant para garantir que os usuários recebam apenas atualizações das conversas que estão autorizados a ver. O servidor valida todas as operações antes de transmiti-las para evitar acesso ou manipulação não autorizados.

Comportamento Offline

Quando os usuários estão completamente offline, eles ainda podem visualizar marcadores existentes, mas não podem criar novos nem ver atualizações de outros. O widget detecta o estado offline e exibe mensagens apropriadas.

Se um usuário tentar criar um marcador enquanto estiver offline e depois voltar a ficar online, a operação falhará em vez de ser enfileirada, garantindo consistência dos dados. Os usuários devem tentar novamente a operação assim que a conexão for restaurada.

Impacto no Desempenho

A conexão WebSocket tem impacto mínimo no desempenho. A conexão permanece ociosa quando não há atualizações ocorrendo e só processa mensagens quando há atividade. Em uma imagem típica com atividade moderada de marcadores, o WebSocket usa menos CPU do que renderizar a própria imagem.

Para páginas com centenas de usuários simultâneos e alta atividade de criação de marcadores, o sistema escala horizontalmente para manter o desempenho sem impactar as conexões dos clientes individuais.

Casos de Uso Colaborativos

A sincronização em tempo real torna o Image Chat particularmente poderoso para fluxos de trabalho colaborativos. Equipes de design podem revisar mockups juntas, com todos vendo a colocação dos marcadores em tempo real. Equipes de suporte ao cliente podem anotar screenshots colaborativamente para identificar problemas. Grupos educacionais podem discutir diagramas com todos os participantes vendo os marcadores uns dos outros conforme são criados.

O feedback imediato cria uma experiência colaborativa mais envolvente e produtiva em comparação com sistemas de comentários tradicionais, onde os usuários precisam atualizar a página para ver as atualizações.