Personalização e temas
Nesta página
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/chatkit1.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ãoname) para sugestões no ecrã inicial, eleftActionerightAction(e nãocustomButtonLeftecustomButtonRight) para botões no cabeçalho. Fontes: Theming and customization in ChatKit ·ChatKitOptionsreference · 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ção | Valores | Efeito |
|---|---|---|
colorScheme | 'light', 'dark' | Tema claro (padrão) ou escuro |
color.accent | primary (hex, rgb(), hsl()…), level de 0 a 3 | Cor de destaque da interface e intensidade da paleta |
color.grayscale | hue em graus, tint de 0 a 9, shade de −4 a 4 | Matiz e tom da paleta de cinzentos |
color.surface | background, foreground | Cores 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 |
typography | fontFamily, fontFamilyMono, baseSize (14 a 18), fontSources | Tipos 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)" },
headerexibe um título fixo (caso contrário, o título do tópico atual) e até dois botões personalizados,leftActionerightAction, 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.historyativa 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.feedbackexibe botões de polegar para cima e para baixo sob as respostas. Cada clique chega ao seu servidor no métodoadd_feedbackdo seuChatKitServer(thread_id,item_ids,feedbackdefinido como'positive'ou'negative'). Esta é a matéria-prima para as suas avaliações.retryadiciona o botão que regenera uma resposta.disclaimerexibe 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 TypeScriptstartScreen(saudação e sugestões),composer(marcador de posição, ferramentas, anexos),header,history,threadItemActions,disclaimerelocalecompletam a interface- Anexos e feedback do utilizador requerem suporte no lado do servidor:
uploadStrategyeAttachmentStore, além do métodoadd_feedback