Comment créer un thème WordPress Block personnalisé avec theme.json : Guide étape par étape

Résumé

Construire un thème WordPress block personnalisé avec Full Site Editing (FSE) peut être intimidant, mais theme.json simplifie le processus. Ce guide vous accompagne dans la création d'un thème block minimal, la définition des styles globaux comme les couleurs et la typographie dans theme.json, et la création de modèles personnalisés à l'aide du balisage de blocs. Vous apprendrez à ajouter des motifs de blocs et des variations de style, permettant un site entièrement designable sans fichiers de modèles PHP. Nous aborderons les erreurs courantes, comme le mélange de fonctionnalités de thème classique et block, et montrerons comment tester votre thème. À la fin, vous aurez un thème block moderne et extensible prêt pour la production. Cette approche exploite les dernières capacités de WordPress pour un développement plus rapide et plus visuel.

Introduction

Full Site Editing (FSE) a révolutionné le développement de thèmes WordPress, vous permettant de concevoir visuellement chaque partie de votre site. Mais de nombreux développeurs utilisent encore des thèmes classiques ou peinent à créer des thèmes block à partir de zéro. La clé pour libérer la puissance de FSE est theme.json — un fichier de configuration qui contrôle les styles globaux, les paramètres et les modèles. Cet article fournit un guide pratique, étape par étape, pour construire un thème block personnalisé en utilisant theme.json. Vous apprendrez à configurer la structure des dossiers, définir des palettes de couleurs et des presets typographiques, créer des modèles personnalisés avec le balisage de blocs, et ajouter des variations de style. À la fin, vous aurez un thème block prêt pour la production, facile à maintenir et à étendre. Plongeons dans le vif du sujet et démystifions le développement FSE.

Pour un aperçu plus large de la manière dont FSE façonne l'avenir du design WordPress, consultez Gutenberg FSE : L'avenir du design WordPress en 2026.

1. Configuration d'un thème block minimal

Un thème block nécessite au minimum deux fichiers : style.css et index.html. Créons-les.

Structure des dossiers

Créez un dossier nommé my-block-theme dans votre répertoire wp-content/themes/. À l'intérieur, placez :

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

style.css

Même si les thèmes block dépendent moins du CSS, style.css est toujours nécessaire pour l'identification du thème :

/*
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 ligne Requires at least: 5.9 garantit que le thème fonctionne avec la fonctionnalité FSE.

index.html

C'est votre modèle de secours. Il doit commencer par un balisage de blocs. Créez une mise en page simple :

<!-- 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"} /-->

Ceci utilise la syntaxe de blocs pour inclure les parties de modèle d'en-tête et de pied de page, et affiche le titre et le contenu de l'article.

Attention : Les thèmes block ne doivent pas contenir de fichiers de modèle PHP comme header.php ou footer.php. Mélanger des modèles classiques et block cassera FSE.

Activation du thème

Téléchargez le dossier via FTP ou installez le zip, puis activez-le. Vous devriez voir un site vide avec votre structure minimale. Ensuite, nous le styliserons avec theme.json.

2. Maîtrise de theme.json : styles globaux et paramètres

theme.json centralise tous les contrôles de design. Il se trouve à la racine de votre dossier de thème. Créons-en un avec des paramètres de couleur et de typographie.

Structure de 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)"
        }
    }
}

Ceci définit une palette de couleurs, des familles de polices, des tailles de police et des styles globaux. Les fonctions var() référencent des propriétés personnalisées CSS générées automatiquement par WordPress. Les utilisateurs peuvent ensuite les modifier dans l'éditeur de site.

Conseil : Utilisez des propriétés personnalisées CSS pour la cohérence. Évitez de coder en dur des valeurs dans les fichiers CSS ; laissez theme.json être la source unique de vérité.

3. Création de modèles personnalisés

Les modèles de blocs sont des fichiers HTML avec un balisage de blocs. Ils suivent une hiérarchie similaire à celle des fichiers de modèles classiques. Par exemple, créez single.html pour les articles individuels :

<!-- 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"} /-->

De même, créez page.html, archive.html, etc. Vous pouvez également créer des modèles personnalisés en ajoutant un bloc wp:post-template dans une boucle de requête.

Pour une personnalisation avancée, envisagez de créer des blocs personnalisés. Apprenez comment dans Au-delà des blocs de base : Créer des blocs Gutenberg personnalisés pour des fonctionnalités WordPress améliorées.

Parties de modèle

Créez un dossier parts/ pour les parties réutilisables. Par exemple, 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 -->

Et footer.html :

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

4. Ajout de motifs de blocs et de variations de style

Les motifs de blocs sont des mises en page pré-conçues. Définissez-les dans un dossier patterns/. Créez 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">Bienvenue</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {"align":"center","textColor":"white"} -->
        <p class="has-text-align-center has-white-color">Ceci est une section hero personnalisée</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

Les variations de style permettent aux utilisateurs de changer l'apparence complète. Créez styles/default.json et styles/dark.json qui remplacent les paramètres du thème.

5. Mises en garde et bonnes pratiques

• Performance : theme.json est mis en cache. Videz le cache après les modifications. Utilisez le hook wp_register_theme_json si nécessaire.
• Rétrocompatibilité : Les thèmes block ne fonctionnent qu'à partir de WordPress 5.9. Si votre site doit prendre en charge des versions antérieures, envisagez une approche hybride mais évitez de mélanger les fichiers de modèles.
• Thèmes enfants : Les thèmes block peuvent être utilisés comme thèmes parents pour des thèmes enfants classiques, mais pas l'inverse. Utilisez template dans style.css pour déclarer un thème block parent.
• Internationalisation : Utilisez la fonction __() dans les parties de modèle PHP pour les chaînes traduisibles. Dans le balisage de blocs, spécifiez le domaine de texte via l'attribut textDomain.

Pour en savoir plus sur les bonnes pratiques de développement de plugins, consultez Construire des plugins WordPress robustes : Un guide pratique des bonnes pratiques.

Conclusion

Construire un thème block personnalisé avec theme.json vous permet de créer un site entièrement designable sans toucher au PHP. En suivant ce guide, vous avez configuré un thème minimal, défini des styles globaux, créé des modèles personnalisés et ajouté des motifs. N'oubliez pas de tester minutieusement, en particulier pour les cas particuliers comme les pages d'archives ou les types de publication personnalisés. À mesure que WordPress évolue, les thèmes block deviendront la norme. Commencez à exploiter FSE dès aujourd'hui pour rationaliser votre flux de travail et offrir à vos clients une flexibilité inégalée.

Si vous souhaitez accélérer encore la création de thèmes, envisagez d'utiliser un outil qui génère un site complet à partir d'une description. Par exemple, vous pouvez décrire la mise en page souhaitée et obtenir un thème block prêt à l'emploi en quelques minutes.

Prêt à mettre en ligne votre thème block ? Avec une description en texte clair, vous pouvez générer une page d'atterrissage ou un site entièrement fonctionnel — sans code requis.