Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Temi e personalizzazione

Lezione 18 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Un unico oggetto di opzioni
  2. Il tema
  3. La schermata iniziale
  4. Il compositore
  5. Intestazione, cronologia e risposte
  6. Lingua
  7. Mettere tutto insieme
  8. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente si basava su componenti e opzioni inesistenti in ChatKit: ChatProvider, MessageInput, rendering personalizzato dei messaggi e fogli di stile iniettati. Ora segue la guida Theming and customization di OpenAI e i tipi di @openai/chatkit 1.9.0; l’esempio completo è stato verificato tramite compilazione TypeScript. Due nomi differiscono tra la guida e il pacchetto pubblicato: questa lezione segue il pacchetto, usando label (non name) per i suggerimenti della schermata iniziale, e leftAction e rightAction (non customButtonLeft e customButtonRight) per i pulsanti dell’intestazione. Fonti: Theming and customization in ChatKit · Riferimento ChatKitOptions · ChatKit Studio.

Un unico oggetto di opzioni

Tutta la personalizzazione di ChatKit avviene tramite un singolo oggetto di opzioni. In React, lo passi a useChatKit({...}); con il componente web, a chatkit.setOptions({...}). La struttura è identica in entrambi i casi, quindi ciò che impari qui si applica a ogni integrazione.

Una conseguenza deriva dall’architettura trattata nella lezione precedente: ChatKit esegue il rendering all’interno di un iframe, quindi il tuo foglio di stile non può raggiungerlo. Le tue regole CSS si applicano solo al contenitore: le dimensioni e la posizione che assegni a <ChatKit className="…" />. Tutto il resto si configura tramite le opzioni. Questa è una buona notizia per la manutenzione: un aggiornamento di ChatKit non può rompere selettori CSS che non esistono.

Per provare le opzioni senza scrivere codice, il playground di ChatKit Studio mostra il rendering in tempo reale.

Il tema

Il tema controlla l’aspetto generale: schema colori, colore di accento, raggio degli angoli, densità 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 },
  },
});

Ogni impostazione ha un insieme chiuso di valori, che TypeScript valida per te:

OpzioneValoriEffetto
colorScheme'light', 'dark'Tema chiaro (predefinito) o scuro
color.accentprimary (hex, rgb(), hsl()…), level da 0 a 3Colore di accento dell’interfaccia e intensità della tavolozza
color.grayscalehue in gradi, tint da 0 a 9, shade da −4 a 4Tonalità e sfumatura della tavolozza dei grigi
color.surfacebackground, foregroundColori di superficie: sfondo e primo piano (testo, icone)
radius'pill', 'round', 'soft', 'sharp'Raggio degli angoli per bolle, pulsanti e campi
density'compact', 'normal', 'spacious'Spaziatura generale
typographyfontFamily, fontFamilyMono, baseSize (da 14 a 18), fontSourcesFont e dimensione base; fontSources carica un font web (family, src, weight…)

Per seguire la preferenza dell’utente, scegli lo schema durante la costruzione delle opzioni, ad esempio con window.matchMedia('(prefers-color-scheme: dark)').matches. È accettato anche un theme ridotto a una stringa, theme: 'dark', quando devi solo impostare lo schema colori.

La schermata iniziale

Una conversazione vuota può risultare intimidatoria. La schermata iniziale la sostituisce con un saluto e suggerimenti che mostrano all’utente cosa può fare l’assistente:

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 è il testo del pulsante, prompt è il messaggio inviato quando l’utente fa clic e icon è un nome dalla lista delle icone di ChatKit (search, write, calendar, lightbulb…), oppure un’icona Lucide nella forma 'lucide:name'.

Il compositore

L’oggetto composer configura il testo segnaposto, gli strumenti offerti all’utente e gli allegati:

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'] },
  },
},

Lo strumento selezionato dal menu viene inviato al server come preferenza di strumento per il turno successivo; devi tenerne conto nel tuo agente.

Gli allegati sono disabilitati di default e abilitarli richiede lavoro lato server. Con il tuo server, devi anche specificare in api come vengono caricati i file: uploadStrategy: { type: 'direct', uploadUrl: '…' } (l’interfaccia invia il file al tuo endpoint) oppure { type: 'two_phase' } (richiede un URL firmato, poi carica il file nel tuo storage). Sul lato Python, fornisci quindi un AttachmentStore. Non impostare enabled: true finché questa pipeline non esiste.

Intestazione, cronologia e risposte

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 visualizza un titolo fisso (altrimenti il titolo della conversazione corrente) e fino a due pulsanti personalizzati, leftAction e rightAction, ognuno con un’icona nell’intestazione (settings-cog, home…) e una funzione. header: { enabled: false } nasconde l’intera intestazione quando la tua applicazione fornisce già la propria barra.
  • history abilita il pannello delle conversazioni passate, con o senza possibilità di rinominare ed eliminare. Disabilitalo quando il concetto di conversazione non ha senso per il tuo caso d’uso, ad esempio per un assistente di supporto senza account utente.
  • threadItemActions.feedback visualizza i pulsanti pollice in su e in giù sotto le risposte. Ogni clic arriva al tuo server nel metodo add_feedback del tuo ChatKitServer (thread_id, item_ids, feedback impostato su 'positive' o 'negative'). Questa è la materia prima per le tue valutazioni. retry aggiunge il pulsante che rigenera una risposta.
  • disclaimer visualizza un breve testo Markdown sotto il compositore.

Lingua

Di default, ChatKit usa la lingua del browser. Se la tua applicazione ha una propria impostazione linguistica, imponila con locale: 'en', o una variante regionale come 'en-US' o 'en-GB'. Ogni richiesta inviata al tuo server porta questa lingua nell’intestazione Accept-Language: usala per far rispondere l’agente e per tradurre i messaggi dei tuoi strumenti nella stessa lingua dell’interfaccia.

Mettere tutto insieme

Ecco una configurazione completa, compilata così com’è con @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" />;
}

Punti chiave

  • Tutta la personalizzazione avviene tramite un unico oggetto di opzioni, identico in React (useChatKit) e con il componente web (setOptions)
  • ChatKit esegue il rendering in un iframe: il tuo CSS stila solo il contenitore; tutto il resto passa attraverso theme
  • theme: colorScheme, color.accent, radius, density, typography, con valori chiusi validati da TypeScript
  • startScreen (saluto e suggerimenti), composer (segnaposto, strumenti, allegati), header, history, threadItemActions, disclaimer e locale completano l’interfaccia
  • Allegati e feedback utente richiedono supporto lato server: uploadStrategy e AttachmentStore, oltre al metodo add_feedback