Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Personalização e temas

Aula 18 de 25 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Um único objeto de opções
  2. O tema
  3. O ecrã inicial
  4. O compositor
  5. Cabeçalho, histórico e respostas
  6. Idioma
  7. Juntar tudo
  8. Pontos-chave

Lição reescrita em 3 de novembro de 2026. A versão anterior baseava-se em componentes e opções que não existem no ChatKit: ChatProvider, MessageInput, renderização personalizada de mensagens e folhas de estilo injetadas. Esta versão segue o guia Theming and customization da OpenAI e os tipos de @openai/chatkit 1.9.0; o exemplo completo foi verificado via compilação TypeScript. Dois nomes diferem entre o guia e o pacote publicado, e esta lição segue o pacote: label (e não name) para sugestões no ecrã inicial, e leftAction e rightAction (e não customButtonLeft e customButtonRight) para botões no cabeçalho. Fontes: Theming and customization in ChatKit · ChatKitOptions reference · ChatKit Studio.

Um único objeto de opções

Toda a personalização do ChatKit ocorre através de um único objeto de opções. Em React, passa-o para useChatKit({...}); com o componente web, para chatkit.setOptions({...}). A estrutura é idêntica em ambos os casos, pelo que o que aprender aqui se aplica a qualquer integração.

Uma consequência decorre da arquitetura abordada na lição anterior: o ChatKit renderiza dentro de um iframe, pelo que a sua folha de estilos não o consegue alcançar. As suas regras CSS aplicam-se apenas ao contentor — o tamanho e a posição que atribui a <ChatKit className="…" />. Todo o resto é configurado via opções. Isto é uma boa notícia para a manutenção: uma atualização do ChatKit não pode quebrar seletores CSS que não existem.

Para experimentar opções sem escrever código, o ChatKit Studio playground mostra a renderização em tempo real.

O tema

O tema controla a aparência geral: esquema de cores, cor de destaque, raio dos cantos, densidade e tipografia.

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  theme: {
    colorScheme: 'dark',
    color: {
      accent: { primary: '#2D8CFF', level: 2 },
    },
    radius: 'round',
    density: 'compact',
    typography: { fontFamily: "'Inter', sans-serif", baseSize: 16 },
  },
});

Cada definição possui um conjunto fechado de valores, que o TypeScript valida por si:

OpçãoValoresEfeito
colorScheme'light', 'dark'Tema claro (padrão) ou escuro
color.accentprimary (hex, rgb(), hsl()…), level de 0 a 3Cor de destaque da interface e intensidade da paleta
color.grayscalehue em graus, tint de 0 a 9, shade de −4 a 4Matiz e tom da paleta de cinzentos
color.surfacebackground, foregroundCores de superfície: fundo e primeiro plano (texto, ícones)
radius'pill', 'round', 'soft', 'sharp'Raio dos cantos para balões, botões e campos
density'compact', 'normal', 'spacious'Espaçamento geral
typographyfontFamily, fontFamilyMono, baseSize (14 a 18), fontSourcesTipos de letra e tamanho base; fontSources carrega um tipo de letra web (family, src, weight…)

Para seguir a preferência do utilizador, escolha o esquema ao construir as opções, por exemplo com window.matchMedia('(prefers-color-scheme: dark)').matches. Um theme reduzido a uma string, theme: 'dark', também é aceite quando apenas precisa de definir o esquema de cores.

O ecrã inicial

Um tópico vazio pode parecer intimidante. O ecrã inicial substitui-o por uma saudação e sugestões que mostram ao utilizador o que o assistente pode fazer:

startScreen: {
  greeting: 'Hello! How can I help you?',
  prompts: [
    { label: 'Track an order', prompt: 'Where is my latest order?', icon: 'search' },
    { label: 'Open a ticket', prompt: 'I would like to report an issue.', icon: 'write' },
  ],
},

label é o texto do botão, prompt é a mensagem enviada quando o utilizador clica, e icon é um nome da lista de ícones do ChatKit (search, write, calendar, lightbulb…), ou um ícone Lucide no formato 'lucide:name'.

O compositor

O objeto composer configura o texto de marcador de posição, as ferramentas oferecidas ao utilizador e os anexos:

composer: {
  placeholder: 'Ask a question about your order…',
  tools: [
    { id: 'order-search', label: 'Search order', icon: 'search', pinned: true },
  ],
  attachments: {
    enabled: true,
    maxCount: 3,
    maxSize: 20 * 1024 * 1024, // 20 MB per file
    accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
  },
},

A ferramenta selecionada no menu é enviada para o servidor como uma preferência de ferramenta para a próxima interação; deve ter isso em conta no seu agente.

Os anexos estão desativados por padrão e ativá-los requer trabalho no lado do servidor. Com o seu próprio servidor, deve também especificar em api como os ficheiros são carregados: uploadStrategy: { type: 'direct', uploadUrl: '…' } (a interface publica o ficheiro no seu endpoint) ou { type: 'two_phase' } (solicita um URL assinado e, em seguida, carrega o ficheiro para o seu armazenamento). Do lado do Python, fornece então um AttachmentStore. Não marque enabled: true até que este pipeline exista.

Cabeçalho, histórico e respostas

header: {
  title: { text: 'Order Assistant' },
  leftAction: { icon: 'settings-cog', onClick: () => openSettings() },
},
history: { enabled: true, showRename: true, showDelete: false },
threadItemActions: { feedback: true, retry: true },
disclaimer: { text: "Responses may contain errors. [Our terms](/terms)" },
  • header exibe um título fixo (caso contrário, o título do tópico atual) e até dois botões personalizados, leftAction e rightAction, cada um com um ícone de cabeçalho (settings-cog, home…) e uma função. header: { enabled: false } oculta todo o cabeçalho quando a sua aplicação já fornece a sua própria barra.
  • history ativa o painel de conversas passadas, com ou sem opção de renomear e eliminar. Desative-o quando o conceito de tópico não fizer sentido para o seu caso de uso, por exemplo, para um assistente de suporte sem contas de utilizador.
  • threadItemActions.feedback exibe botões de polegar para cima e para baixo sob as respostas. Cada clique chega ao seu servidor no método add_feedback do seu ChatKitServer (thread_id, item_ids, feedback definido como 'positive' ou 'negative'). Esta é a matéria-prima para as suas avaliações. retry adiciona o botão que regenera uma resposta.
  • disclaimer exibe um curto texto em Markdown abaixo do compositor.

Idioma

Por padrão, o ChatKit utiliza o idioma do navegador. Se a sua aplicação tiver a sua própria definição de idioma, imponha-a com locale: 'en', ou uma variante regional como 'en-US' ou 'en-GB'. Cada pedido enviado ao seu servidor transporta este idioma no cabeçalho Accept-Language: utilize-o para fazer o agente responder e para traduzir as mensagens das suas ferramentas no mesmo idioma da interface.

Juntar tudo

Aqui está uma configuração completa, compilada tal como está com @openai/chatkit-react 1.6.1:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function OrderAssistant({ openSettings }: { openSettings: () => void }) {
  const dark = window.matchMedia('(prefers-color-scheme: dark)').matches;

  const { control } = useChatKit({
    api: { url: '/chatkit', domainKey: 'local-dev' },
    locale: 'en',
    theme: {
      colorScheme: dark ? 'dark' : 'light',
      color: { accent: { primary: '#2D8CFF', level: 2 } },
      radius: 'round',
      density: 'normal',
    },
    startScreen: {
      greeting: 'Hello! How can I help you?',
      prompts: [
        { label: 'Track an order', prompt: 'Where is my latest order?', icon: 'search' },
        { label: 'Open a ticket', prompt: 'I would like to report an issue.', icon: 'write' },
      ],
    },
    composer: { placeholder: 'Ask a question about your order…' },
    header: {
      title: { text: 'Order Assistant' },
      leftAction: { icon: 'settings-cog', onClick: openSettings },
    },
    history: { enabled: true, showRename: true, showDelete: false },
    threadItemActions: { feedback: true, retry: true },
  });

  return <ChatKit control={control} className="h-[640px] w-full max-w-md" />;
}

Pontos-chave

  • Toda a personalização ocorre através de um único objeto de opções, idêntico em React (useChatKit) e com o componente web (setOptions)
  • O ChatKit renderiza num iframe: o seu CSS apenas estiliza o contentor; todo o resto passa por theme
  • theme: colorScheme, color.accent, radius, density, typography, com valores fechados validados pelo TypeScript
  • startScreen (saudação e sugestões), composer (marcador de posição, ferramentas, anexos), header, history, threadItemActions, disclaimer e locale completam a interface
  • Anexos e feedback do utilizador requerem suporte no lado do servidor: uploadStrategy e AttachmentStore, além do método add_feedback