CSS e JavaScript personalizzati

Questa pagina mostra un esempio su un sito demo chiamato Harbor. L’intestazione usa il logo e i colori di Harbor e include due link aggiuntivi; nell’angolo in basso a destra compare un pulsante Ask AI fluttuante. Puoi copiare i file così come sono e sostituire il logo e i colori con i tuoi.

Gli screenshot mostrano l'interfaccia in inglese.

Cosa cambia in questa intestazione

Di default, l’intestazione di Jam si integra con la pagina. In modalità chiara è trasparente e lascia intravedere il gradiente tenue sullo sfondo. In modalità scura ha lo stesso colore quasi nero di tutto il resto. I pulsanti hanno angoli leggermente arrotondati. La versione Harbor introduce quattro cambiamenti:

• È una barra blu navy anche in modalità scura.
• Una sottile linea arancione corre lungo il bordo inferiore.
• La casella di ricerca e i pulsanti Ask AI e Book a demo sono a forma di pillola.
• Il logo bianco di Harbor sostituisce quello predefinito.

Le modifiche richiedono CSS e un file del logo. L’intestazione di Jamdesk non viene modificata. La ricerca, Ask AI, il selettore del tema e il menu per dispositivi mobili continuano a funzionare come prima.

L’esempio usa questi file nel progetto:

harbor-docs/
├── docs.json              ← logo, header links and brand colors
├── style.css              ← header and button styles
├── script.js              ← creates the Ask AI button
└── images/
    └── harbor-logo.svg    ← white logo for the navy header

Inizia con docs.json

Per la prima parte non serve scrivere codice. Il logo, i colori, i link dell’intestazione e il pulsante Book a demo si configurano in docs.json:

{
  "logo": {
    "light": "/images/harbor-logo.svg",
    "dark": "/images/harbor-logo.svg"
  },
  "colors": {
    "primary": "#C2410C",
    "light": "#D9480F",
    "dark": "#9A3412"
  },
  "navbar": {
    "links": [
      { "label": "Blog", "href": "https://example.com/blog" },
      { "label": "Status", "href": "https://example.com/status" }
    ],
    "primary": {
      "type": "button",
      "label": "Book a demo",
      "href": "https://example.com/demo"
    }
  }
}

Il logo è bianco. L’intestazione è sempre blu navy. Usa lo stesso file per light e dark.

Jamdesk usa il colore primary per il pulsante Book a demo, la voce attiva della barra laterale e i link. In modalità scura usa invece il colore light. Scegli una tonalità abbastanza scura da mantenere leggibile il testo bianco sul pulsante. Consulta Link di navigazione per tutte le opzioni della barra di navigazione.

Personalizza l’intestazione

Il testo, i bordi, la casella di ricerca e gli angoli arrotondati dell’intestazione dipendono da variabili CSS. Imposta queste variabili nell’intestazione per modificarla senza influire sul resto:

/* header[data-has-tabs] matches the site header only.
   A plain `header` selector would also match the title
   block at the top of every page. */
header[data-has-tabs] {
  --header-top: #0f1d3a;
  --header-bottom: #1b2f5b;
  --header-stripe: #f97316;
  --color-text-primary: #ffffff;
  --color-text-secondary: #cbd5e1;
  --color-text-tertiary: #cbd5e1;
  --color-text-muted: #94a3b8;
  --color-bg-primary: #0f1d3a;
  --color-bg-secondary: rgba(255, 255, 255, 0.08);
  --color-bg-hover: rgba(255, 255, 255, 0.16);
  --color-border: rgba(255, 255, 255, 0.16);
  /* Rounds the search box, Ask AI and buttons into pills */
  --radius-md: 999px;
  --radius-lg: 999px;
}

html.dark header[data-has-tabs] {
  --header-top: #0a1328;
  --header-bottom: #13234a;
  --color-bg-primary: #0a1328;
}

/* Some themes keep the header background transparent on
   purpose, so paint the color on a layer behind it. */
header[data-has-tabs]::before {
  content: "";
  position: absolute;
  inset: 0 -24px; /* reach past the 16-24px page gutter */
  z-index: -1;
  background: linear-gradient(
    90deg, var(--header-top), var(--header-bottom)
  );
  border-bottom: 3px solid var(--header-stripe);
}

/* The sparkle icon uses the accent color, which is hard to
   see on navy, so give it the stripe color instead */
header[data-has-tabs] .fa-sparkles {
  color: #fdba74;
}

Lo sfondo blu navy è applicato a un livello ::before perché il tema Jam imposta background dell’intestazione su none con !important. Una normale regola background sull’intestazione non avrebbe effetto. Il livello si trova dietro i contenuti dell’intestazione e funziona con tutti i temi.

Impostando --radius-md e --radius-lg su 999px, i pulsanti dell’intestazione diventano a forma di pillola. La modifica è limitata a header[data-has-tabs]. Le schede e i blocchi di codice della pagina mantengono i loro angoli consueti.

L’icona Ask AI nell’intestazione usa il colore di accento, difficile da distinguere sul blu navy. L’ultima regola la rende arancione chiaro.

In modalità scura Jamdesk aggiunge la classe dark a <html>. Il blocco html.dark rende lo sfondo blu navy leggermente più scuro:

Aggiungi un pulsante Ask AI mobile

Lo script aggiunge alla pagina un normale elemento <button>. Quando si fa clic, invia Ctrl+I, la scorciatoia da tastiera che apre e chiude il pannello della chat. Il pulsante Ask AI nell’intestazione esegue la stessa azione.

(function () {
  if (document.getElementById('ask-ai-fab')) return;

  var button = document.createElement('button');
  button.id = 'ask-ai-fab';
  button.type = 'button';

  // Jamdesk loads Font Awesome, so its icons are available here
  var icon = document.createElement('i');
  icon.className = 'fa-solid fa-sparkles';
  icon.setAttribute('aria-hidden', 'true');
  button.append(icon, ' Ask AI');

  button.addEventListener('click', function () {
    // Same as pressing Ctrl+I / Cmd+I: toggles the chat panel
    var shortcut = { key: 'i', ctrlKey: true, bubbles: true };
    document.dispatchEvent(new KeyboardEvent('keydown', shortcut));
  });

  document.body.appendChild(button);
})();

Aggiungi quindi gli stili del pulsante a style.css:

#ask-ai-fab {
  position: fixed;
  right: 24px;
  bottom: 24px;
  z-index: 40; /* below the header, search and mobile menu */
  display: inline-flex;
  align-items: center;
  gap: 8px;
  padding: 12px 18px;
  border: 0;
  border-radius: 999px;
  background: #c2410c;
  color: #fff;
  font: inherit;
  font-weight: 600;
  box-shadow: 0 6px 20px rgba(15, 29, 58, 0.25);
  cursor: pointer;
}

#ask-ai-fab:hover {
  background: #9a3412;
}

#ask-ai-fab:focus-visible {
  outline: 2px solid #f97316;
  outline-offset: 2px;
}

/* Hide the button while the chat panel is open. On mobile
   the closed panel stays in the page with data-open="false",
   so exclude that case. */
body:has([data-chat-panel]:not([data-open="false"])) #ask-ai-fab {
  display: none;
}

@media (max-width: 767px) {
  #ask-ai-fab {
    right: 16px;
    bottom: 16px;
  }
}

Su un telefono, il pulsante si trova a 16px dai bordi. La chat aperta copre gran parte dello schermo. Il pulsante resta nascosto finché la chat non viene chiusa:

Per usare il pulsante, la chat AI deve essere attiva. Se in docs.json imposti chat.enabled su false, fare clic sul pulsante non produce alcun effetto. In tal caso, non aggiungere il pulsante.

Anche un widget di supporto, come Crisp o Intercom, potrebbe trovarsi nell’angolo in basso a destra. Per separarli, usa left: 24px invece di right su #ask-ai-fab. In alternativa, aumenta bottom per posizionare il pulsante sopra il widget.

Esegui il codice dopo ogni cambio di pagina

Lo script viene eseguito una volta, quando un visitatore apre il sito per la prima volta. Facendo clic su un link nella documentazione, il contenuto della pagina cambia senza ricaricarla. Lo script non viene eseguito di nuovo, ma il pulsante Ask AI non ne risente: è collegato a <body>, che rimane invariato.

Il codice che legge o modifica il contenuto della pagina deve rilevare i cambi di pagina. Questo snippet osserva la colonna principale e controlla se l’URL è cambiato. Inseriscilo nello stesso script.js, sotto il codice del pulsante:

(function () {
  var lastPath = location.pathname;
  var main = document.getElementById('main-content') || document.body;

  function onPageChange() {
    // Your per-page code goes here
    console.log('Now on', location.pathname);
  }

  new MutationObserver(function () {
    if (location.pathname === lastPath) return;
    lastPath = location.pathname;
    onPageChange();
  }).observe(main, { childList: true, subtree: true });
})();

onPageChange viene eseguita una volta per ogni nuova pagina, sia che il visitatore faccia clic su un link della barra laterale, usi la ricerca o prema il pulsante Indietro.

Selettori consigliati

I nomi delle classi di Jamdesk dipendono da Tailwind e possono cambiare in qualsiasi versione. Anche le etichette dei pulsanti possono cambiare. I siti multilingue le traducono. Usa invece questi selettori:

Verifica le modifiche

jamdesk dev mostra il CSS, ma non esegue il JavaScript personalizzato. La chat AI funziona solo sul sito pubblicato. Per provare lo script localmente, incollalo nella console del browser sulla pagina di anteprima. Il pulsante apparirà, ma la chat non si aprirà finché non pubblichi il sito.

Controlla il risultato su uno schermo delle dimensioni di un telefono (largo 375px) e in modalità scura, non solo su desktop. È in queste condizioni che spesso si verificano problemi con i colori dell’intestazione e i pulsanti fissi.

E adesso?