Come creare un tema a blocchi personalizzato per WordPress con theme.json: Guida passo passo

Sommario

Creare un tema a blocchi personalizzato per WordPress con Full Site Editing (FSE) può essere scoraggiante, ma theme.json semplifica il processo. Questa guida ti accompagna nella creazione di un tema a blocchi minimale, nella definizione di stili globali come colori e tipografia in theme.json, e nella creazione di modelli personalizzati utilizzando il markup a blocchi. Imparerai ad aggiungere pattern e variazioni di stile, abilitando un sito completamente personalizzabile senza file PHP di template. Tratteremo errori comuni, come mescolare funzionalità di temi classici e a blocchi, e mostreremo come testare il tuo tema. Alla fine, avrai un tema a blocchi moderno ed estensibile pronto per la produzione. Questo approccio sfrutta le ultime funzionalità di WordPress per uno sviluppo più veloce e visivo.

Introduzione

Full Site Editing (FSE) ha rivoluzionato lo sviluppo dei temi WordPress, permettendoti di progettare visivamente ogni parte del sito. Ma molti sviluppatori si affidano ancora ai temi classici o faticano a creare temi a blocchi da zero. La chiave per sbloccare il potere di FSE è theme.json — un file di configurazione che controlla stili globali, impostazioni e modelli. Questo articolo fornisce una guida pratica e passo passo per creare un tema a blocchi personalizzato usando theme.json. Imparerai a impostare la struttura delle cartelle, definire palette di colori e preset tipografici, creare modelli personalizzati con markup a blocchi e aggiungere variazioni di stile. Alla fine, avrai un tema a blocchi pronto per la produzione, facile da mantenere ed estendere. Immergiamoci e demistifichiamo lo sviluppo FSE.

Per uno sguardo più ampio su come FSE sta plasmando il futuro del design di WordPress, dai un'occhiata a Gutenberg FSE: Il futuro del design WordPress nel 2026.

1. Impostazione di un tema a blocchi minimale

Un tema a blocchi richiede almeno due file: style.css e index.html. Creiamoli.

Struttura delle cartelle

Crea una cartella chiamata my-block-theme nella directory wp-content/themes/. All'interno, inserisci:

• style.css
• index.html
• (opzionale) theme.json

style.css

Anche se i temi a blocchi si basano meno su CSS, style.css è ancora necessario per l'identificazione del tema:

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built with theme.json.
Version: 1.0
Requires at least: 5.9
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
Text Domain: my-block-theme
*/

La riga Requires at least: 5.9 garantisce che il tema funzioni con la funzionalità FSE.

index.html

Questo è il template di fallback. Deve iniziare con il markup a blocchi. Crea un layout semplice:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Questo utilizza la sintassi a blocchi per includere parti di template header e footer, e mostra il titolo e il contenuto del post.

Attenzione: I temi a blocchi non devono contenere file PHP di template come header.php o footer.php. Mescolare template classici e a blocchi romperà FSE.

Attivazione del tema

Carica la cartella tramite FTP o installazione zip, e attivala. Dovresti vedere un sito vuoto con la tua struttura minima. Successivamente, lo styleremo con theme.json.

2. Padroneggiare theme.json: Stili e impostazioni globali

theme.json centralizza tutti i controlli di design. Si trova nella radice della cartella del tema. Creiamone uno con impostazioni di colore e tipografia.

Struttura di base

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "#007cba",
                    "name": "Primary"
                },
                {
                    "slug": "secondary",
                    "color": "#005a87",
                    "name": "Secondary"
                },
                {
                    "slug": "background",
                    "color": "#ffffff",
                    "name": "Background"
                }
            ],
            "gradients": []
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "slug": "system",
                    "name": "System"
                },
                {
                    "fontFamily": "'Georgia', serif",
                    "slug": "serif",
                    "name": "Serif"
                }
            ],
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "14px",
                    "name": "Small"
                },
                {
                    "slug": "medium",
                    "size": "18px",
                    "name": "Medium"
                },
                {
                    "slug": "large",
                    "size": "24px",
                    "name": "Large"
                }
            ]
        },
        "spacing": {
            "padding": true,
            "margin": true,
            "units": ["px", "em", "rem"]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--background)",
            "text": "var(--wp--preset--color--primary)"
        },
        "typography": {
            "fontFamily": "var(--wp--preset--font-family--system)",
            "fontSize": "var(--wp--preset--font-size--medium)"
        }
    }
}

Questo definisce una palette di colori, famiglie di font, dimensioni dei font e stili globali. Le funzioni var() fanno riferimento a proprietà CSS personalizzate generate automaticamente da WordPress. Gli utenti potranno poi modificarle nell'Editor del Sito.

Suggerimento: Usa proprietà CSS personalizzate per coerenza. Evita di hardcodare valori nei file CSS; lascia che theme.json sia l'unica fonte di verità.

3. Creazione di modelli personalizzati

I template a blocchi sono file HTML con markup a blocchi. Seguono una gerarchia simile ai file di template classici. Ad esempio, crea single.html per i singoli post:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
    <!-- wp:post-navigation-link {"type":"previous"} /-->
    <!-- wp:post-navigation-link {"type":"next"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Allo stesso modo, crea page.html, archive.html, ecc. Puoi anche creare modelli personalizzati aggiungendo un blocco wp:post-template all'interno di un loop di query.

Per personalizzazioni avanzate, considera la creazione di blocchi personalizzati. Scopri come in Oltre i blocchi di base: Creare blocchi Gutenberg personalizzati per funzionalità WordPress avanzate.

Parti di template

Crea una cartella parts/ per parti riutilizzabili. Ad esempio, header.html:

<!-- wp:group {"tagName":"header","layout":{"type":"flex","flexWrap":"nowrap"}} -->
<header class="wp-block-group">
    <!-- wp:site-logo /-->
    <!-- wp:navigation {"themeLocation":"primary"} /-->
</header>
<!-- /wp:group -->

E footer.html:

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">&copy; 2025 My Site</p>
<!-- /wp:paragraph -->

4. Aggiungere pattern e variazioni di stile

I pattern a blocchi sono layout predefiniti. Definisci in una cartella patterns/. Crea patterns/hero.php:

<?php
/**
 * Title: Hero
 * Slug: my-block-theme/hero
 * Categories: hero
 */
?>
<!-- wp:cover {"overlayColor":"primary","minHeight":50,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:50vh">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color"></span>
    <div class="wp-block-cover__inner-container">
        <!-- wp:heading {"textAlign":"center","level":1,"style":{"color":{"text":"#ffffff"}}} -->
        <h1 class="has-text-align-center has-text-color" style="color:#ffffff">Benvenuto</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {"align":"center","textColor":"white"} -->
        <p class="has-text-align-center has-white-color">Questa è una sezione hero personalizzata</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

Le variazioni di stile permettono agli utenti di cambiare completamente l'aspetto. Crea styles/default.json e styles/dark.json che sovrascrivono le impostazioni del tema.

5. Avvertenze e buone pratiche

• Performance: theme.json viene memorizzato nella cache. Cancella la cache dopo le modifiche. Usa l'hook wp_register_theme_json se necessario.
• Compatibilità all'indietro: I temi a blocchi funzionano solo da WordPress 5.9. Se il tuo sito deve supportare versioni precedenti, considera un approccio ibrido ma evita di mescolare file di template.
• Temi figli: I temi a blocchi possono essere usati come temi genitori per temi figli classici, ma non viceversa. Usa template in style.css per dichiarare un tema a blocchi genitore.
• Internazionalizzazione: Usa la funzione __() all'interno delle parti di template PHP per stringhe traducibili. Nel markup a blocchi, specifica il text domain tramite l'attributo textDomain.

Per ulteriori informazioni sulle buone pratiche di sviluppo di plugin, vedi Costruire plugin WordPress robusti: Una guida pratica alle migliori pratiche.

Conclusione

Creare un tema a blocchi personalizzato con theme.json ti permette di realizzare un sito completamente personalizzabile senza toccare PHP. Seguendo questa guida, hai impostato un tema minimale, definito stili globali, creato modelli personalizzati e aggiunto pattern. Ricorda di testare accuratamente, specialmente per casi limite come pagine archivio o tipi di post personalizzati. Con l'evoluzione di WordPress, i temi a blocchi diventeranno lo standard. Inizia a sfruttare FSE oggi per ottimizzare il tuo flusso di lavoro e offrire ai clienti una flessibilità senza pari.

Se vuoi accelerare ulteriormente la creazione del tema, considera l'utilizzo di uno strumento che genera un sito completo da una descrizione. Ad esempio, puoi descrivere il layout desiderato e avere un tema a blocchi pronto all'uso in pochi minuti.

Pronto a mettere online il tuo tema a blocchi? Con una descrizione in testo semplice, puoi generare una landing page o un sito web completamente funzionale — senza scrivere codice.