Esempi di CSS e JavaScript

Questa pagina mostra un esempio realizzato su un sito dimostrativo 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 mobile. 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

Per impostazione predefinita, l’intestazione di Jam si integra nella pagina. In modalità chiara è trasparente e lascia intravedere il gradiente tenue sullo sfondo; in modalità scura ha lo stesso colore quasi nero del resto della pagina. I pulsanti hanno angoli leggermente arrotondati. La versione Harbor apporta quattro modifiche:

• È una barra blu navy in entrambe le modalità, chiara e scura, per risaltare sulla pagina.
• Una sottile linea arancione corre lungo il bordo inferiore.
• Il campo di ricerca, Ask AI e Book a demo diventano pulsanti a forma di capsula.
• Il logo bianco di Harbor sostituisce quello predefinito.

Le modifiche richiedono CSS e un file con il logo. L’intestazione di Jamdesk non viene modificata, quindi 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. Logo, colori, link dell’intestazione e pulsante Book a demo si configurano tutti 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. Poiché l’intestazione è blu navy sia in modalità chiara che scura, basta un solo file.

Jamdesk usa il colore primary per il pulsante Book a demo, la voce attiva della barra laterale e i link, quindi l’arancione appare in tutto il sito. In modalità scura viene usato il colore light. Assicurati che sia abbastanza scuro da rendere ben leggibile il testo bianco sul pulsante. Per tutte le opzioni della barra di navigazione, consulta Link di navigazione.

Personalizza l’intestazione

Il testo, i bordi, il campo di ricerca e gli angoli arrotondati dell’intestazione sono controllati da variabili CSS. Se imposti queste variabili all’interno dell’intestazione, le modifiche riguarderanno solo l’intestazione:

/* 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;
}

Il blu navy viene 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 al contenuto dell’intestazione e funziona in tutti i temi.

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

L’icona Ask AI nell’intestazione usa il colore di accento, che sul blu navy è poco visibile. L’ultima regola le assegna una tonalità arancione chiara.

In modalità scura, Jamdesk aggiunge la classe dark a <html>, quindi il blocco html.dark rende il 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, eseguendo la stessa azione del pulsante Ask AI nell’intestazione.

(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 poi 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;
  }
}

Sui telefoni, il pulsante si trova a 16px dai bordi. Quando si apre la chat, occupa gran parte dello schermo e il pulsante scompare fino alla chiusura:

Per usare il pulsante, la chat AI deve essere attiva. Se chat.enabled è impostato su false in docs.json, facendo clic non succede nulla: in tal caso, non aggiungere il pulsante.

Se usi anche un widget di supporto come Crisp o Intercom, probabilmente si trova nell’angolo in basso a destra. Per separarli, usa left: 24px al posto di right in #ask-ai-fab oppure aumenta il valore di 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. In seguito, facendo clic su un link della documentazione, il contenuto della pagina viene sostituito senza ricaricarla, quindi lo script non viene eseguito di nuovo. Il pulsante Ask AI non ne risente perché è collegato a <body>, che rimane invariato.

Se il codice legge o modifica il contenuto della pagina, deve rilevare i cambi di pagina. Questo frammento controlla la colonna principale e verifica 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 derivano da Tailwind e possono cambiare con qualsiasi versione. Cambiano anche le etichette dei pulsanti, perché nei siti multilingue vengono tradotte. Usa invece questi selettori:

Verifica le modifiche

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

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

E adesso?