Visão geral do bate-papo React

O componente Ignite UI for React Chat fornece uma solução completa para a criação de interfaces de conversação em seus aplicativos. Esteja você criando uma ferramenta de suporte ao cliente, um espaço de trabalho colaborativo ou um assistente de chatbot, o componente Chat oferece os blocos de construção de que você precisa: enviar e receber mensagens de texto, fazer upload de anexos de arquivos, exibir sugestões de resposta rápida, mostrar indicadores de digitação quando o outro participante está escrevendo uma resposta.

Ao contrário de uma lista de mensagens estática, oIgrChatComponent componente é interativo e projetado para comunicação em tempo real. Ele gerencia entrada, renderização e interação do usuário, além de dar controle total sobre como mensagens e anexos são exibidos. Também expõe uma API de renderização extensa que permite sobrescrever qualquer parte do layout ou dos visuais.

Instalação

Para começar, instale o Ignite UI for React executando o seguinte comando:

npm install igniteui-react

Depois de instalado, você pode importar o componente em seu projeto e registrá-lo para que ele fique disponível como um elemento personalizado:

import { IgrChat } from "igniteui-react";
import 'igniteui-webcomponents/themes/light/bootstrap.css';

O arquivo CSS inclui um dos nossos temas padrão. Você pode substituí-lo por um tema diferente ou criar um personalizado se quiser que combineIgrChatComponent com a marca do seu aplicativo.

Uso

A maneira mais simples de usar oIgrChatComponent é declará-lo da seguinte forma:

import { IgrChat, IgrChatOptions } from 'igniteui-react';

const options: IgrChatOptions = {
  currentUserId: 'me',
  headerText: 'Support Chat',
};

return (
  <IgrChat options={options} />
);

Aqui, acurrentUserId propriedade informa ao componente quais mensagens são "enviadas" (enviadas pelo usuário atual) e quais mensagens estão "recebidas" (enviadas por outros). EleheaderText fornece um título para a janela de chat.

Depois de renderizado, você pode adicionar mensagens programaticamente:

import { useRef } from 'react';
import { IgrChat } from 'igniteui-react';

const ChatExample = () => {
  const chatRef = useRef<IgrChat>(null);

  const sendMessage = () => {
    const newMessage = {
      id: '1',
      sender: 'me',
      text: 'Hello! How can I help you?',
      timestamp: Date.now().toString()
    };
    chatRef.current!.messages = [...chatRef.current!.messages, newMessage];
  };

  return (
    <>
      <IgrChat ref={chatRef} options={{ currentUserId: 'me', headerText: 'Support Chat' }} />
      <button onClick={sendMessage}>Send Message</button>
    </>
  );
};

Essa abordagem facilita a conexão do Chat à sua própria fonte de dados, como um endpoint de servidor, um mecanismo de chatbot ou um back-end de aplicativo colaborativo.

Propriedades

OIgrChatComponent componente expõe várias propriedades importantes que permitem controlar seu estado e configuração:

Nome	Descrição
messages	Matriz de mensagens (ChatMessage[]) exibidas no chat. Você pode vincular a isso para controlar quais mensagens são mostradas.
draftMessage	A mensagem não enviada atual, representada como um objeto contendotext e opcionalattachments. Isso é útil para salvar ou restaurar rascunhos de mensagens.
options	Configuração de bate-papo (IgrChatOptions), como ID de usuário atual, espaços reservados de entrada, tipos de arquivo aceitos, sugestões de resposta rápida, atraso de digitação e renderizadores personalizados.
resourceStrings	Cadeias de caracteres de recursos localizadas para rótulos, cabeçalhos e texto do sistema. Use essa propriedade para adaptar o componente para diferentes idiomas.

Essas propriedades facilitam a sincronização da interface do usuário do Chat com o estado e o back-end do aplicativo.

Attachments

Conversas modernas raramente se limitam apenas ao texto. O componente Chat inclui suporte embutido para anexos de arquivos, permitindo que os usuários compartilhem imagens, documentos e outros arquivos. Por padrão, a área de entrada inclui um botão de anexo. Você pode controlar quais tipos de arquivo são permitidos definindo a propriedadeacceptedFiles:

const options: IgrChatOptions = {
  acceptedFiles="image/*,.pdf",
};

Neste exemplo, os usuários só poderão fazer upload de imagens e arquivos PDF. Se o seu caso de uso não exigir anexos, você poderá desativá-los facilmente:

const options: IgrChatOptions = {
  disableInputAttachments: true,
};

Sugestões

Sugestões de resposta rápida oferecem aos usuários respostas pré-definidas que podem tocar para responder instantaneamente. Esse recurso é particularmente útil em chatbots, fluxos de atendimento ao cliente ou ao guiar usuários por um processo estruturado. Você pode fornecer sugestões vinculando um array de strings à propriedade de sugestões. Osuggestions-position atributo permite que você controle onde elas são exibidas: seja abaixo da área de entrada ou abaixo da lista de mensagens.

const options: IgrChatOptions = {
  currentUserId: "me",
  suggestions: ['Yes', 'No', 'Maybe later'],
  suggestionsPosition: "below-input"
};

return (
  <IgrChat ref={chatRef} options={{ options }} />
);

Essa abordagem ajuda a simplificar as interações do usuário, reduzindo a necessidade de digitar respostas repetitivas e melhora a experiência geral em conversas guiadas.

Typing Indicator

As conversas parecem mais naturais quando os participantes veem que a outra pessoa está digitando. O componente Chat fornece esse comportamento por meio daisTyping propriedade do objeto options. Quando configurado como verdadeiro, o chat mostra um indicador sutil de digitação abaixo das mensagens:

const options: IgrChatOptions = {
  isTyping: true
};

Esse recurso normalmente é alternado programaticamente, por exemplo, ao receber um evento de digitação do serviço de back-end.

Custom Renderers

Embora o componente Chat funcione de fábrica com sua interface padrão, muitos aplicativos precisam personalizar a aparência e a sensação. Por exemplo, você pode querer adicionar recibos de leitura, exibir avatares ou substituir a área de entrada por um botão de gravação de voz. OIgrChatComponent componente atende a essa necessidade com um sistema de renderização. Um renderizador é simplesmente uma função que retorna um template para uma determinada parte da interface. Você pode sobrescrever quantos ou poucos renderizadores quiser.

ChatTemplateRenderer

Cada renderizador segue a mesma assinatura de função:

export type ChatTemplateRenderer<T> = (ctx: T) => unknown;

O parâmetro ctx fornece dados contextuais diferentes, dependendo do que está sendo renderizado.

Renderer Contexts

Context Type	Provided Data
ChatRenderContext	instance(a instância do componente de bate-papo).
ChatInputRenderContext	HerdaChatRenderContext e adicionaattachments (matriz deIgrChatMessageAttachment) evalue (texto de entrada atual).
ChatMessageRenderContext	HerdaChatRenderContext e adicionaIgrChatMessage (oIgrChatMessage que está sendo renderizado).
ChatAttachmentRenderContext	HerdaChatMessageRenderContext e adicionaattachment (oIgrChatMessageAttachment que está sendo renderizado).

Renderizadores disponíveis

As seguintes partes do bate-papo podem ser personalizadas:

• Message-level: message, messageHeader, messageContent, messageAttachments, messageActions
• Attachment-level: attachment, attachmentHeader, attachmentContent
• Input-level: input, inputActions, inputActionsStart, inputActionsEnd, inputAttachments, fileUploadButton, sendButton
• Suggestions: suggestionPrefix
• Miscellaneous: typingIndicator

Esse nível de granularidade significa que você pode ajustar apenas uma parte (por exemplo, a aparência dos anexos) sem reescrever todo o layout do chat.

Exemplo: Conteúdo de mensagem personalizada

Este exemplo mostra como substituir o balão de mensagem por seu próprio modelo:

const options = {
  renderers: {
    messageContent: (ctx) => {
      const { message } = ctx;
      return (
        <div className="bubble custom">${message.content}</div>
      );
    }
  }
};

Example: Custom Input Area

Por padrão, a entrada de chat é uma área de texto. Você pode substituí-lo para fornecer uma experiência mais personalizada, como adicionar um botão de entrada de voz:

const options = {
  renderers: {
    input: (ctx) => {
      return (
        <>
          <textarea placeholder={ctx.instance?.options?.inputPlaceholder || 'Type here...'}>{ctx.value}</textarea>
          <button onClick={() => alert('Voice input!')}>🎤</button>
        </>
      );
    }
  }
};

Exemplo: Estendendo ações de entrada

OIgrChatComponent componente fornece dois renderizadores que são úteis quando você quer manter as ações padrão (upload e envio), mas estendê-las com controles adicionais:

• inputActionsStart– permite que você injete conteúdo personalizado após o botão de upload embutido.
• inputActionsEnd– permite injetar conteúdo personalizado após o botão de enviar embutido.

Por exemplo, você pode querer adicionar um botão de gravação de voz após o botão de upload ou um menu de opções extras após o botão enviar. No exemplo a seguir, o botão de upload padrão é preservado, mas adicionamos um botão de microfone ao lado dele. Por outro lado, removemos o botão de envio padrão e o substituímos por um botão Ask personalizado e um menu "mais":

const _actionsStartTemplate = () => (
  <IgrIconButton variant="flat">🎤</IgrIconButton>
);

const _actionsEndTemplate = (ctx) => (
  <div>
    <IgrButton onClick={() => handleCustomSendClick(ctx.instance)}>Ask</IgrButton>
    <IgrIconButton variant="flat" name="more_horiz"></IgrIconButton>
  </div>
);

const options = {
  renderers: {
    inputActionsStart: _actionsStartTemplate,
    inputActionsEnd: _actionsEndTemplate,
    sendButton: () => null,
  },
};

Nesta configuração:

• O botão de upload permanece no lugar.
• Um botão de microfone é adicionado depois dele (inputActionsStart).
• O botão de envio padrão é removido e substituído por um botão Perguntar personalizado e um ícone "mais" (inputActionsEnd).

Essa abordagem oferece flexibilidade total na barra de entrada do chat, permitindo adicionar, remover ou reordenar ações sem reconstruir a área de entrada do zero.

Markdown Rendering

O componente Chat inclui suporte embutido para conteúdo Markdown através docreateMarkdownRenderer helper, que é exportado a partir do igniteui-react/extras ponto de entrada do pacote principal. Isso permite exibir mensagens com texto formatado, links, listas e até blocos de código destacados com sintaxe, garantindo que todo o HTML renderizado seja limpo para segurança.

[! Nota] Para usar o renderizador Markdown, você precisa instalar as seguintes dependências entre pares no seu projeto:

npm install marked marked-shiki shiki dompurify

Por padrão, as mensagens são renderizadas como texto sem formatação. Se você quiser habilitar o suporte a Markdown, poderá substituir o renderizador messageContent e usar o renderizador Markdown, conforme mostrado abaixo:

import { createMarkdownRenderer } from 'igniteui-react/extras';

// Create a reusable Markdown renderer instance
const markdownRenderer = await createMarkdownRenderer();

const options = {
  renderers: {
    messageContent: async ({ message }) => markdownRenderer(message),
  }
};

Neste exemplo:

• A propriedade text de cada mensagem será analisada como Markdown usando a biblioteca marcada.
• O renderizador limpa a saída usando DOMPurify
• Os links são abertos automaticamente em uma nova guia com atributos rel seguros.

Realce de sintaxe

O renderizador Markdown também dá suporte ao realce de sintaxe para blocos de código usando Shiki. Por padrão, ele inclui realce para JavaScript, TypeScript, HTML e CSS com o tema github-light. Você pode personalizar esse comportamento por meio de MarkdownRendererOptions:

const markdownRenderer = await createMarkdownRenderer({
  theme: { light: 'min-light' },
  languages: ['javascript', 'python']
});

Isso habilitará blocos de código destacados para JavaScript, Python e Go, estilizados com o tema escuro do GitHub.

Configuration Options

Opção	Descrição
noHighlighter	Iftrue, desabilita totalmente o realce de sintaxe.
languages	Lista de linguagens de programação a serem suportadas em blocos de código destacados.
theme	Um objeto que especifica temas Shiki para aplicar. Suporta valores separados paralight edark modo (por exemplo,{ light: 'github-light', dark: 'github-dark' }).
sanitizer	Uma função personalizada para limpar o HTML final. O padrão éDOMPurify.sanitize.

Eventos

Para se integrar à lógica do aplicativo, o componente Chat emite um conjunto de eventos:

• onMessageCreated – quando uma nova mensagem é criada.
• onMessageReact – quando uma mensagem é reagida.
• onAttachmentClick – quando um anexo é clicado.
• onAttachmentAdded – quando um anexo é adicionado.
• onAttachmentRemoved – quando um anexo é removido.
• onAttachmentDrag – enquanto arrasta um anexo.
• onAttachmentDrop – quando um anexo é descartado.
• onTypingChange – when typing status changes.
• onInputFocus / onInputBlur – input focus events.
• onInputChange – quando o valor de entrada é alterado.

Você pode ouvir esses eventos e sincronizá-los com seu back-end:

const chatRef = useRef<IgrChat>(null);
chatRef.current.addEventListener('onMessageCreated', (e) => {
  console.log('Message:', e.detail);
});

Estilização

OIgrChatComponent componente expõe tanto peças CSS quanto slots para personalização detalhada de sua aparência e estrutura.

Partes CSS

Nome da peça	Descrição
"contêiner-chat"	Estiliza o contêiner de bate-papo principal.
"cabeçalho"	Estiliza o contêiner de cabeçalho de chat.
"prefixo"	Estiliza o elemento antes do título do bate-papo (por exemplo, avatar).
"título"	Estiliza o título do cabeçalho do chat.
"contêiner-área-mensagem"	Estiliza o contêiner que contém as mensagens e sugestões (opcionais).
"lista de mensagens"	Estiliza o contêiner da lista de mensagens.
"item-mensagem"	Estiliza cada wrapper de mensagem.
"indicador de digitação"	Estiliza o contêiner do indicador de digitação.
"ponto de digitação"	Estilos de pontos indicadores de digitação individuais.
"Recipiente de Sugestões"	Estiliza o contêiner que contém todas as sugestões.
"cabeçalho-sugestões"	Estiliza o cabeçalho de sugestões.
"Sugestão"	Estiliza cada item de sugestão.
"sugestão-prefixo"	Estiliza o ícone ou prefixo em uma sugestão.
"sugestão-título"	Estiliza o texto/título de uma sugestão.
"estado vazio"	Estiliza o contêiner de estado vazio quando não há mensagens.
"contêiner-área-entrada"	Estiliza o wrapper ao redor da área de entrada do chat.
"contêiner-entrada"	Estiliza o contêiner de entrada principal.
"contêiner-adjuntos-entrada"	Estiliza o contêiner para anexos na entrada.
"Contêiner-Entrada-Anexo"	Estiliza um único anexo na área de entrada.
"nome-anexo-entrada"	Estiliza o nome do arquivo de um anexo.
"ícone de acessório de entrada"	Estiliza o ícone de um anexo.
"entrada de texto"	Estiliza o campo de entrada de texto para digitar mensagens.
"contêiner-ações-de entrada"	Estiliza o contêiner para ações de entrada.
"input-actions-start"	Estiliza o grupo de ações no início da entrada após o upload do arquivo padrão.
"fim-ações-entrada"	Estiliza o grupo de ações no final da entrada.
"contêiner-de upload de arquivo"	Estiliza o contêiner para a entrada de upload de arquivo.
"upload de arquivo"	Estiliza a própria entrada de upload de arquivo.
"Recipiente de botão de enviar"	Estiliza o contêiner ao redor do botão enviar.
"botão de enviar"	Estiliza o botão enviar.
"contêiner-mensagem"	Estiliza o contêiner de uma única mensagem.
"Lista de mensagens (encaminhada)"	Estiliza a lista interna de mensagens.
"cabeçalho de mensagem"	Estiliza o cabeçalho de uma mensagem (por exemplo, remetente, carimbo de data/hora).
"conteúdo da mensagem"	Estiliza o conteúdo de texto de uma mensagem.
"contêiner-anexos-de mensagens"	Estiliza o contêiner para anexos de mensagens.
"anexo de mensagem"	Estiliza um único anexo de mensagem.
"contêiner-de de ações-mensagem"	Estiliza o contêiner que contém as ações da mensagem.
"mensagem enviada"	Define as mensagens marcadas como enviadas pelo usuário atual.
"cabeçalho de anexo"	Estiliza o cabeçalho de um bloco de anexo.
"conteúdo de apego"	Estiliza o conteúdo de um bloco de anexo.
"ícone de anexo"	Estiliza o ícone de um anexo.
"nome do arquivo"	Estiliza o nome do arquivo mostrado em um anexo.

Slots

Nome do slot	Descrição
"prefixo"	Slot para injetar conteúdo (por exemplo, avatar ou ícone) antes do título do bate-papo.
"título"	Slot para substituir o conteúdo do título do bate-papo.
"Ações"	Slot para injetar ações de cabeçalho (por exemplo, botões, menus).
"cabeçalho-sugestões"	Slot para renderizar um cabeçalho personalizado para a lista de sugestões.
"Sugestões"	Slot para renderizar uma lista personalizada de sugestões de resposta rápida.
"sugestões-ações"	Slot para renderizar ações adicionais.
"Sugestão"	Slot para renderizar um único item de sugestão.
"estado vazio"	Slot mostrado quando não há mensagens.

Adoção de estilo raiz (adoptRootStyles)

As opções do componente Chat incluem um sinalizador especial para cenários de estilo avançados:

Opção	Tipo	Padrão	Descrição
adoptRootStyles	boolean	falso	Quandotrue, o componente permite que o conteúdo renderizado dentro de seu Shadow DOM (por exemplo, de renderizadores personalizados) herde estilos da raiz do documento. Isso fornece uma solução rápida para o estilo, mas não é recomendado para uso em produção.

Essa propriedade pode ser útil se você preferir não lidar com o encapsulamento Shadow DOM ao aplicar CSS global a modelos renderizados personalizados. No entanto, ele vem com compensações:

• ✅ Conveniência: permite que os estilos globais (do documento) afetem os renderizadores de mensagens personalizados.
• ⚠️ Arriscado: quebra o encapsulamento e pode levar ao vazamento de estilo, onde o CSS global altera involuntariamente os visuais internos.
• 🔒 Configuração única: Esta opção só pode ser definida na inicialização. Alterá-lo em tempo de execução não tem efeito.

É altamente recomendável usar as abordagens de estilo padrão do Web Component antes de recorrer a esta propriedade:

• Variáveis CSS e API ::p art – Prefira personalizar por meio de partes e variáveis expostas.
• "" elements – For larger stylesheets, inject them inside the Shadow DOM.
• Inline "