Cos'è il file theme.json in WordPress e come usarlo

Il file theme.json è una parte importante dei temi a blocchi di WordPress, che controlla molti aspetti dell'aspetto e della funzionalità del tuo sito. Se sei passato di recente da un tema classico a uno a blocchi, potresti chiederti di cosa si tratta questo file e se dovresti modificarlo.

Non sei solo. Anche noi e molti utenti di WPBeginner ci siamo posti esattamente la stessa domanda. Abbiamo quindi deciso di approfondire questo argomento per fornire una guida completa.

In questo articolo, spiegheremo cos'è un file theme.json, perché è importante e come puoi usarlo per personalizzare il tuo sito WordPress. 

Cos'è il file theme.json di WordPress?

Il file theme.json è un file tema speciale introdotto in WordPress 5.8. Svolge un ruolo chiave nell'esperienza di editing completo del sito (FSE), che ti consente di personalizzare visivamente ogni aspetto del tuo tema a blocchi di WordPress.

Essenzialmente, il file theme.json funge da progetto che controlla lo stile e la funzionalità del tuo tema a blocchi. Contiene codice che indica a WordPress come diversi elementi come colori, tipografia, layout e modelli dovrebbero apparire e comportarsi.

Perché i temi a blocchi di WordPress necessitano di un file theme.json?

Modificare un tema a blocchi in WordPress è diverso dal modificare un tema classico.

I temi classici utilizzano il file functions.php per abilitare funzionalità come menu personalizzati o immagini in evidenza con la funzione add_theme_support(). Successivamente, è possibile stilizzare tali funzionalità con regole CSS nel file del foglio di stile CSS (style.css).

Nei temi a blocchi, theme.json funge da hub centrale per tutto ciò che definisce l'aspetto del tuo tema a blocchi. Ti consente di definire elementi come font, colori e opzioni di layout in un unico posto, sostituendo la necessità di add_theme_support() in functions.php.

Ecco perché il file functions.php nei temi a blocchi è spesso più piccolo dell'equivalente nei temi classici.

Avere un file theme.json dedicato offre alcuni grandi vantaggi rispetto al precedente sistema di temi classici.

Innanzitutto, theme.json lavora in sinergia con l'editor completo del sito di WordPress. Questo ti consente di personalizzare facilmente gli stili e le impostazioni del tuo tema direttamente dall'editor senza dover toccare alcun codice.

Inoltre, theme.json mira a creare un'esperienza coerente sia per gli sviluppatori che per gli utenti. Alcuni utenti trovano davvero frustrante quando devono cambiare tema perché devono imparare layout e opzioni di stile completamente nuovi.

Con theme.json, il passaggio tra i temi diventa un processo più agevole perché tutto è organizzato in modo simile.

Infine, utilizzando theme.json, gli sviluppatori di temi e gli utenti possono rendere i loro lavori a prova di futuro man mano che WordPress continua ad espandere le sue capacità di editing completo del sito.

Ora che abbiamo visto cos'è un file theme.json, approfondiamo l'argomento. Puoi usare i collegamenti rapidi qui sotto per navigare in questa guida:

• Dove Trovare il File theme.json di WordPress
• Come Si Presenta il File theme.json
• Cosa Fare Prima di Modificare il File theme.json
• Come Modificare il File theme.json di WordPress
• Suggerimento Bonus: Usa WPCode per Aggiungere Codice Personalizzato al Tuo Tema

Dove Trovare il File theme.json di WordPress

Il file theme.json si trova all'interno della directory del tuo tema sul tuo server web. Il percorso tipico del file sarebbe public_html » wp-content » themes » nome-del-tuo-tema » theme.json.

Per accedervi, devi prima connetterti al tuo sito tramite FTP o il file manager del tuo account di hosting.

Se usi Bluehost, puoi accedere e passare alla scheda 'Siti web'. Quindi, fai clic sul pulsante 'Impostazioni' sotto il tuo sito web.

Ora, assicurati di rimanere nella scheda 'Panoramica'.

Quindi, scorri verso il basso per fare clic sul pulsante 'Gestione file'.

Quando apri il file manager in questo modo, sarai automaticamente all'interno della cartella principale del tuo sito web.

Qui, cerca la directory 'wp-content' e aprila. Lì, troverai la cartella 'themes' che contiene tutti i tuoi temi WordPress installati.

Apri la cartella per il tema a blocchi specifico che stai utilizzando. Il file theme.json si troverà direttamente all'interno di questa directory del tema, insieme ad altri file del tema.

Una volta trovato, puoi visualizzare il file theme.json utilizzando un editor di codice.

Come Si Presenta il File theme.json

Il file theme.json ha una struttura specifica che organizza tutte le impostazioni globali per il tuo tema a blocchi WordPress.

A seconda di quanto sia complesso o semplice il tuo tema, il file può essere molto corto o lungo. Tuttavia, puoi facilmente suddividere questo file in 7 sezioni di primo livello:

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}

Ecco una ripartizione semplificata:

Schema

Questa parte è in realtà opzionale nei temi a blocchi, quindi potresti vederla o meno nel tuo.

La proprietà schema collega l'URL allo schema JSON di WordPress, che definisce le impostazioni globali, gli stili e altre configurazioni per il tuo tema.

Versione

Questa sezione specifica quale versione dell'API del formato theme.json viene utilizzata dal file e garantisce che segua la struttura corretta.

Al momento della scrittura di questo articolo, l'API è alla versione 2.

Impostazioni

Questa proprietà definisce le opzioni e i controlli disponibili per gli utenti per personalizzare il loro tema. Questi includono preset per la palette di colori del tema, tipografia, spaziatura, sfumature, ombre, bordi e così via.

Ecco un esempio molto semplice di come appare la proprietà settings:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },
        {
          "slug": "contrast",
          "color": "#222222",
          "name": "Dark"
        },
        {
          "slug": "accent",
          "color": "#f08080",
          "name": "Pink"
        },
        {
          "slug": "accent-2",
          "color": "#90ee90",
          "name": "Light Green"
        },
        {
          "slug": "accent-3",
          "color": "#e0ffff",
          "name": "Light Blue"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "Open Sans, sans-serif",
          "slug": "open-sans",
          "name": "Open Sans"
        },
        {
          "fontFamily": "Arial, sans-serif",
          "slug": "arial",
          "name": "Arial"
        },
        {
          "fontFamily": "Times New Roman, serif",
          "slug": "times-new-roman",
          "name": "Times New Roman"
        }
      ],
      "fontSizes": [
        {
          "name": "Extra Small",
          "slug": "xx-small",
          "size": "0.75rem"
        },
        {
          "name": "Small",
          "slug": "small",
          "size": "0.875rem"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "1rem"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "1.125rem"
        },
        {
          "name": "Extra Large",
          "slug": "x-large",
          "size": "1.25rem"
        },
        {
          "name": "XX-Large",
          "slug": "xx-large",
          "size": "1.5rem"
        }
      ],
      "spacing": {
        "units": ["rem"],
        "values": {
          "small": "1rem",
          "medium": "1.5rem",
          "large": "2rem"
        }
      }
    }
  }
}

Se guardi il codice, il linguaggio utilizzato è abbastanza facile da capire. Puoi dire che le impostazioni definiscono i colori, i font, le dimensioni dei font e la spaziatura utilizzati nel tema.

Se ci sono riferimenti qui o nel tuo tema che non capisci, puoi consultare il Riferimento ufficiale alle impostazioni di WordPress.

Alcuni elementi, come colori e famiglie di font, hanno degli slug, come questo:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },

Questi torneranno utili per la sezione degli stili in seguito per creare preset, che spiegheremo nella parte successiva.

Stili

Mentre la sezione settings definisce le opzioni di personalizzazione predefinite del tema, la sezione styles le applica al tema.

Qui, puoi applicare le impostazioni di personalizzazione all'intero sito web o a livello di blocco utilizzando i preset.

Diamo un'occhiata all'esempio qui sotto:

{
  "settings": {
    // Existing settings from the previous example
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--accent-2)"
        }
      },
      "h1": {
        "fontSize": "var(--wp--preset--font-size--xx-large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      },
      "h2": {
        "fontSize": "var(--wp--preset--font-size--x-large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      },
      "h3": {
        "fontSize": "var(--wp--preset--font-size--large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      }
    }
  }
}

Come puoi vedere, c'è questa riga di codice che appare in tutto questo snippet: var(--wp--preset--xxx). Questi sono preset, che sono scorciatoie nella sezione degli stili che fanno riferimento ai valori definiti nella sezione delle impostazioni.

Ad esempio, considera {"slug": "base", "color": "#ffffff", "name": "White"} nella sezione settings. Qui, "base" è lo slug e il preset corrispondente per questo colore è var(--wp--preset--color--base).

Pertanto, il codice "color": {"background": "var(--wp--preset--color--base)" negli stili indica che il colore di sfondo di questo tema è bianco.

Modelli personalizzati

Nello sviluppo di temi a blocchi per WordPress, gli sviluppatori possono creare layout predefiniti per pagine personalizzate, post o tipi di post personalizzati che gli utenti possono utilizzare.

Ad esempio, il tema Twenty Twenty-Four ha diversi modelli personalizzati definiti nel file theme.json: Pagina senza titolo, Pagina con barra laterale, Pagina con immagine ampia e Singolo con barra laterale.

Puoi usare uno qualsiasi di questi per creare i tuoi contenuti.

],
"customTemplates": [
  {
    "name": "page-no-title",
    "postTypes": ["page"],
    "title": "Page No Title"
  },
  {
    "name": "page-with-sidebar",
    "postTypes": ["page"],
    "title": "Page With Sidebar"
  },
  {
    "name": "page-wide",
    "postTypes": ["page"],
    "title": "Page with wide Image"
  },
  {
    "name": "single-with-sidebar",
    "postTypes": ["post"],
    "title": "Single with Sidebar"
  }
]

Una cosa da notare è che il file theme.json fa riferimento ai modelli solo per nome e fornisce metadati su di essi, come il loro titolo e i tipi di post per cui sono destinati.

Tuttavia, l'aspetto e la funzionalità effettivi dei modelli personalizzati sono definiti in file di modello separati all'interno della cartella del tema.

Per vederli, puoi andare su public_html » wp-content » themes » nome-del-tuo-tema » templates.

Parti del modello

Le parti del modello sono aree riutilizzabili che puoi applicare ai tuoi modelli personalizzati. Questi sono elementi come intestazioni, piè di pagina, barre laterali e così via.

Ecco come appaiono quelle parti del modello registrate in theme.json:

"templateParts": [
  {
    "area": "header",
    "name": "header",
    "title": "Header"
  },
  {
    "area": "footer",
    "name": "footer",
    "title": "Footer"
  },
  {
    "area": "sidebar",  // Removed "uncategorized"
    "name": "sidebar",
    "title": "Sidebar"
  },
  {
    "area": "post-meta",  // Removed "uncategorized"
    "name": "post-meta",
    "title": "Post Meta"
  }
]

Come i modelli personalizzati, il file theme.json fa riferimento solo ai modelli.

Il loro aspetto effettivo è definito nei propri file di parte del modello nella cartella parts.

Pattern

I pattern sono raccolte predefinite di blocchi che ti consentono di creare layout di contenuto personalizzati nelle tue pagine, post o ovunque altro nel tuo tema.

Quando apri l'editor del sito completo, potresti notare il menu Pattern. È qui che puoi trovare tutti i pattern disponibili per il tuo tema a blocchi Gutenberg.

Con theme.json, gli sviluppatori di temi possono fare riferimento a pattern dalla directory pubblica dei Pattern di WordPress. È un ottimo modo per offrire più opzioni di personalizzazione senza dover progettare questi blocchi riutilizzabili da soli.

Ad esempio, il tema Twenty Twenty-Four fa riferimento a due pattern dalla directory ufficiale: tre colonne di servizi e la sezione clienti:

"patterns": [
  "three-columns-of-services",
  "clients-section"
]

Sappiamo questo perché questi pattern si trovano nel menu Pattern nell'editor del sito completo.

Tuttavia, non si trovano nella cartella patterns all'interno della directory del tema.

Cosa Fare Prima di Modificare il File theme.json

Poiché theme.json è un file di tema principale, modificarlo direttamente sul tuo sito web WordPress live comporta alcuni rischi. Errori accidentali potrebbero potenzialmente danneggiare il tuo tema o sito web.

Un approccio più sicuro è utilizzare un tema figlio.

Un tema figlio eredita tutte le variazioni di stile e le funzionalità del tuo tema padre (il tema a blocchi che stai utilizzando) ma ti consente di personalizzare le cose senza modificare il tema padre stesso. In questo modo, se il tema padre riceve aggiornamenti, le tue personalizzazioni non verranno sovrascritte.

Puoi leggere la nostra guida su come creare un tema figlio in WordPress per maggiori informazioni. Questo articolo mostra un metodo semplice con il plugin Create Block Theme, che genererà automaticamente un nuovo file theme.json solo per il tuo tema figlio.

Per garantire un'esperienza di modifica fluida ed evitare tempi di inattività del sito web, ti consigliamo inoltre di creare un nuovo backup del tuo sito WordPress. In questo modo, se qualcosa va storto, puoi ripristinare facilmente il tuo sito al suo stato precedente.

Ti consigliamo di utilizzare un plugin come Duplicator per una soluzione di backup rapida e affidabile.

Si consiglia inoltre di lavorare in un ambiente di sviluppo WordPress locale o in un sito di staging. Questo crea una replica del tuo sito web live dove puoi testare le modifiche in sicurezza senza influenzare i tuoi visitatori.

Ecco alcuni altri suggerimenti da tenere a mente:

• Inizia con piccole modifiche nel tuo file theme.json e testale a fondo prima di apportare modifiche più complesse.
• Se non sei sicuro di una proprietà o impostazione specifica all'interno del file theme.json, consulta la documentazione ufficiale di WordPress.
• Non esitare a chiedere aiuto al team di supporto dello sviluppatore del tema o ai forum di supporto di WordPress.org se riscontri problemi. Dai un'occhiata alla nostra guida su come chiedere supporto per WordPress per maggiori informazioni.

Come Modificare il File theme.json di WordPress

Sulla base delle nostre ricerche e dei nostri test, abbiamo scoperto due modi per modificare un file theme.json di WordPress: utilizzando l'editor completo del sito o utilizzando il codice. La prima opzione è molto più semplice e sicura e ti consente di vedere le tue modifiche dal front-end del tuo sito web.

Nel frattempo, la seconda opzione è consigliata se hai familiarità con lo sviluppo avanzato di WordPress.

Modifica theme.json senza codice (per principianti)

Per modificare il tuo file theme.json senza toccare direttamente il codice, puoi utilizzare il plugin Create Block Theme. Questo plugin è stato pubblicato dal team ufficiale di WordPress.org per consentire agli utenti di creare un tema a blocchi personalizzato, modificarlo e/o salvare le variazioni di stile del loro tema a blocchi.

Innanzitutto, procedi con l'installazione del plugin WordPress nella tua area amministrativa. Quindi, apri l'editor completo del sito andando su Aspetto » Editor.

Ora vedrai diversi menu per modificare il tuo tema.

Qui, seleziona 'Stili'.

Successivamente, fai clic sull'icona a forma di matita 'Modifica stili'.

Questo ti porterà all'editor a blocchi per modificare le impostazioni globali e gli stili del tuo sito web.

Ora puoi cambiare lo stile del tuo tema come al solito. Puoi leggere la sezione su come modificare gli stili globali del tuo tema nella nostra guida all'editing completo del sito di WordPress per maggiori informazioni.

Proviamo a creare una palette di colori personalizzata come esempio.

Lo schema di colori o palette è un insieme di colori predefiniti per elementi come testo, sfondi e pulsanti. Garantisce un aspetto coerente in tutto il tuo sito web.

Gli elementi che utilizzano la stessa preimpostazione di colore corrisponderanno sempre, in modo che il design del tuo sito web appaia curato e professionale.

Per modificare la palette, seleziona 'Colori' nella barra laterale delle impostazioni di Stile.

Nella schermata successiva, vedrai alcune impostazioni per personalizzare i colori del tuo tema.

Qui, fai clic sui colori nella sezione 'Palette'.

In questo esempio, il tema Twenty Twenty-Four ha già definito 5 colori nella palette, ma puoi cambiarne uno qualsiasi per crearne uno personalizzato da zero.

Per farlo, fai clic su uno dei colori sotto 'Tema'. Quindi, seleziona qualsiasi colore nello strumento di selezione del colore.

Ora, se visualizzi in anteprima il tuo sito web, vedrai che i blocchi o gli elementi specifici che utilizzavano il colore precedente sono stati sostituiti con il colore che hai appena selezionato nella tua palette.

Puoi ripetere gli stessi passaggi per ogni colore. Quindi, fai clic su 'Salva'.

Dopo aver salvato le modifiche, fai clic sul pulsante Crea tema a blocchi (l'icona della chiave inglese).

Quindi, seleziona 'Salva modifiche al tema'.

Nella schermata successiva, devi scorrere verso il basso.

Dopodiché, fai clic su 'Salva modifiche'. Questo richiederà a WordPress di memorizzare tutte le modifiche apportate al tuo tema nel file theme.json.

Una volta fatto ciò, l'editor a blocchi si aggiornerà automaticamente.

Ora, fai di nuovo clic sul pulsante Crea tema blocco e seleziona ‘Visualizza theme.json.’

Per vedere il codice della tua palette di colori personalizzata, cerca palette annidato all'interno di color e settings, in questo modo:

"settings": {
  // Some code...
  "color": {
    // Some code...
    "palette":  
  }
}

Sotto di esso, dovresti vedere i nuovi codici esadecimali della tua palette di colori personalizzata.

Modifica theme.json con il codice (utenti avanzati)

Questo metodo è consigliato se sei un aspirante sviluppatore di temi WordPress o hai una certa esperienza con il codice.

Innanzitutto, apri il file theme.json del tuo tema blocco nella tua directory WordPress. Puoi utilizzare l'editor di codice nel file manager del tuo provider di hosting web o scaricare il file, modificarlo sul tuo computer e ricaricarlo sul tuo server.

Utilizzeremo il tema Twenty Twenty-Four e il file manager di Bluehost a scopo dimostrativo. Se sei un utente Bluehost e stai utilizzando il file manager, puoi semplicemente fare clic con il pulsante destro del mouse sul tuo file theme.json e fare clic su ‘Modifica.’

Se utilizzi FTP, puoi leggere la nostra guida su come utilizzare FTP per caricare file su WordPress.

Proviamo un semplice esempio di modifica del tuo file theme.json: creazione di dimensioni di font personalizzate.

Ancora una volta, ricorda che la proprietà settings specifica gli stili predefiniti del tuo tema, mentre la proprietà styles li implementa. Per questo motivo, modificheremo la proprietà settings nel file theme.json.

Se utilizzi un tema figlio, puoi semplicemente copiare e incollare il seguente codice nel tuo file theme.json e modificare le dimensioni dei font in pixel come preferisci:

{
  "settings": {
    "typography": {
      "fluid": false,
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "16px"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "24px"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "40px"
        },
        {
          "name": "Extra Large",
          "slug": "x-lagrge",  // Typo fixed (large -> large)
          "size": "48px"
        }
      ]
    }
  }
}

Nota: Se stai modificando direttamente il file del tuo tema padre, devi trovare il codice che dice fontSizes.

Dovrebbe essere annidato all'interno di typography e settings, in questo modo:

{
  "settings": {
    // Some code...
    "typography": {
      // Some code...
      "fontSizes": [
        // Font size definitions here
      ]
    }
  }
}

Dopodiché, sostituisci quelle righe di codice con lo snippet di codice sopra. Assicurati solo che non ci siano errori di sintassi al suo interno.

Una volta terminato, salva il file e visualizza in anteprima il tuo sito web per vedere le modifiche. Per gli utenti Bluehost, puoi semplicemente fare clic su 'Salva modifiche' nell'editor di codice del file manager.

Se desideri modificare ulteriormente il tuo theme.json, ti incoraggiamo vivamente a familiarizzare con la struttura del file come spiegato nella sezione precedente.

Ti suggeriamo inoltre di leggere il Riferimento ufficiale alle impostazioni di WordPress, che include un elenco completo delle proprietà delle impostazioni disponibili e istruzioni per il loro utilizzo.

Suggerimento Bonus: Usa WPCode per Aggiungere Codice Personalizzato al Tuo Tema

In questa guida, hai appreso di theme.json e del suo potenziale per la personalizzazione del tema. Ma forse ti sembra ancora un po' opprimente modificarlo direttamente.

Fortunatamente, esiste un'altra opzione user-friendly per aggiungere codice personalizzato ed effettuare personalizzazioni avanzate: WPCode.

Con WPCode, puoi inserire snippet di codice personalizzato senza dover mai toccare i file del tuo tema. Questo riduce significativamente il rischio di rompere il tuo sito web durante la personalizzazione.

Se vuoi saperne di più su questo plugin per snippet di codice, dai un'occhiata alla nostra recensione completa di WPCode.

Inoltre, ecco alcuni tutorial utili per iniziare a usare WPCode:

• Utili snippet di codice WordPress per principianti (scelta degli esperti)
• Come evidenziare i nuovi post per i visitatori di ritorno in WordPress
• Come evidenziare il testo in WordPress
• Come aggiungere facilmente l'ombra a box in WordPress

Speriamo che questo articolo ti abbia aiutato a conoscere il file theme.json in WordPress. Potresti anche voler consultare la nostra guida per principianti su come modificare un sito web WordPress e la nostra selezione di esperti dei migliori page builder drag-and-drop per WordPress.

Se ti è piaciuto questo articolo, iscriviti al nostro canale YouTube per tutorial video su WordPress. Puoi anche trovarci su Twitter e Facebook.