Qu'est-ce que le fichier theme.json dans WordPress et comment l'utiliser

Le fichier theme.json est une partie importante des thèmes de blocs WordPress, contrôlant de nombreux aspects de l'apparence et des fonctionnalités de votre site. Si vous êtes récemment passé d'un thème classique à un thème de blocs, vous vous demandez peut-être à quoi sert ce fichier et si vous devriez le modifier.

Vous n'êtes pas seul. Nous et de nombreux utilisateurs de WPBeginner nous sommes posé exactement la même question. Nous avons donc décidé de plonger en profondeur dans ce sujet pour fournir un guide complet.

Dans cet article, nous expliquerons ce qu'est un fichier theme.json, pourquoi il est important et comment vous pouvez l'utiliser pour personnaliser votre site WordPress. 

Qu'est-ce que le fichier theme.json de WordPress ?

Le fichier theme.json est un fichier de thème spécial introduit dans WordPress 5.8. Il joue un rôle clé dans l'expérience de l'édition complète du site (FSE), qui vous permet de personnaliser visuellement chaque aspect de votre thème de blocs WordPress.

Essentiellement, le fichier theme.json agit comme un plan directeur qui contrôle le style et la fonctionnalité de votre thème de blocs. Il contient du code qui indique à WordPress comment différents éléments tels que les couleurs, la typographie, les mises en page et les modèles doivent apparaître et se comporter.

Pourquoi les thèmes de blocs WordPress ont-ils besoin d'un fichier theme.json ?

Modifier un thème de blocs dans WordPress est différent de modifier un thème classique.

Les thèmes classiques utilisent le fichier functions.php pour activer des fonctionnalités telles que les menus personnalisés ou les images mises en avant avec la fonction add_theme_support(). Ensuite, vous pouvez styliser ces fonctionnalités avec des règles CSS dans le fichier de feuille de style CSS (style.css).

Dans les thèmes de blocs, theme.json agit comme un hub central pour tout ce qui définit l'apparence de votre thème de blocs. Il vous permet de définir des éléments tels que les polices, les couleurs et les options de mise en page en un seul endroit, remplaçant ainsi le besoin de add_theme_support() dans functions.php.

C'est pourquoi le fichier functions.php dans les thèmes de blocs est souvent plus petit que l'équivalent dans les thèmes classiques.

Avoir un fichier theme.json dédié offre de grands avantages par rapport au système de thèmes classiques précédent.

Premièrement, theme.json fonctionne en tandem avec l'éditeur complet de site de WordPress. Cela vous permet de personnaliser facilement les styles et les paramètres de votre thème directement dans l'éditeur sans avoir à toucher au code.

De plus, theme.json vise à créer une expérience cohérente pour les développeurs et les utilisateurs. Certains utilisateurs trouvent frustrant lorsqu'ils doivent changer de thème car ils doivent apprendre des mises en page et des options de style complètement nouvelles.

Avec theme.json, le changement de thème devient un processus plus fluide car tout est organisé de manière similaire.

Enfin, en utilisant theme.json, les développeurs de thèmes et les utilisateurs peuvent pérenniser leur travail à mesure que WordPress continue d'étendre ses capacités d'édition complète de site.

Maintenant que nous avons vu ce qu'est un fichier theme.json, approfondissons le sujet. Vous pouvez utiliser les liens rapides ci-dessous pour naviguer dans ce guide :

• Où trouver le fichier theme.json de WordPress ?
• À quoi ressemble le fichier theme.json ?
• Ce que vous devriez faire avant de modifier le fichier theme.json
• Comment modifier le fichier theme.json de WordPress
• Astuce bonus : Utilisez WPCode pour ajouter du code personnalisé à votre thème

Où trouver le fichier theme.json de WordPress ?

Le fichier theme.json se trouve dans le répertoire de votre thème sur votre serveur web. Le chemin d'accès typique serait public_html » wp-content » themes » nom-de-votre-thème » theme.json.

Pour y accéder, vous devez d'abord vous connecter à votre site via FTP ou le gestionnaire de fichiers de votre compte d'hébergement.

Si vous utilisez Bluehost, vous pouvez vous connecter et passer à l'onglet « Websites ». Ensuite, cliquez sur le bouton « Settings » sous votre site web.

Maintenant, assurez-vous de rester sur l'onglet « Aperçu ».

Ensuite, faites défiler vers le bas pour cliquer sur le bouton « Gestionnaire de fichiers ».

Lorsque vous ouvrez le gestionnaire de fichiers de cette manière, vous serez automatiquement dans le dossier racine de votre site Web.

Ici, recherchez le répertoire « wp-content » et ouvrez-le. Là, vous trouverez le dossier « themes » qui contient tous vos thèmes WordPress installés.

Ouvrez le dossier du thème de bloc spécifique que vous utilisez. Le fichier theme.json sera situé directement à l'intérieur de ce répertoire de thème, aux côtés d'autres fichiers de thème.

Une fois que vous l'avez trouvé, vous pouvez afficher le fichier theme.json à l'aide d'un éditeur de code.

À quoi ressemble le fichier theme.json ?

Le fichier theme.json a une structure spécifique qui organise tous les paramètres globaux de votre thème de bloc WordPress.

Selon la complexité ou la simplicité de votre thème, le fichier peut être très court ou très long. Cependant, vous pouvez facilement diviser ce fichier en 7 sections de niveau supérieur :

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

Voici une explication simplifiée :

Schéma

Cette partie est en fait facultative dans les thèmes de bloc, vous pourriez donc la voir ou non dans le vôtre.

La propriété schema lie l'URL au schéma JSON WordPress, qui définit les paramètres globaux, les styles et d'autres configurations pour votre thème.

Version

Cette section spécifie quelle version de l'API du format theme.json est utilisée par le fichier et garantit qu'il suit la bonne structure.

Au moment de la rédaction de cet article, l'API est à la version 2.

Paramètres

Cette propriété définit les options et les contrôles disponibles pour que les utilisateurs personnalisent leur thème. Cela inclut des préréglages pour la palette de couleurs du thème, la typographie, l'espacement, les dégradés, les ombres, les bordures, etc.

Voici un exemple très simple de ce à quoi ressemble la propriété 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"
        }
      }
    }
  }
}

Si vous regardez le code, le langage utilisé est assez facile à comprendre. Vous pouvez dire que les paramètres définissent les couleurs, les familles de polices, les tailles de polices et l'espacement utilisés dans le thème.

S'il y a des références ici ou dans votre thème que vous ne comprenez pas, vous pouvez consulter la Référence officielle des paramètres WordPress.

Certains éléments, comme les couleurs et les familles de polices, ont des slugs, comme ceci :

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

Ceux-ci seront utiles pour la section des styles plus tard afin de créer des préréglages, que nous expliquerons dans la partie suivante.

Styles

Alors que la section des paramètres définit les options de personnalisation par défaut du thème, la section des styles les applique au thème.

Ici, vous pouvez appliquer les paramètres de personnalisation à l'ensemble du site Web ou au niveau d'un bloc en utilisant des préréglages.

Examinons l'exemple ci-dessous :

{
  "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"
      }
    }
  }
}

Comme vous pouvez le constater, il y a cette ligne de code qui apparaît dans cet extrait : var(--wp--preset--xxx). Ce sont des préréglages, qui sont des raccourcis dans la section des styles qui font référence aux valeurs définies dans la section des paramètres.

Par exemple, considérez {"slug": "base", "color": "#ffffff", "name": "White"} dans la section des paramètres. Ici, "base" est le slug, et le préréglage correspondant pour cette couleur est var(--wp--preset--color--base).

Par conséquent, le code "color": {"background": "var(--wp--preset--color--base)" dans les styles indique que la couleur d'arrière-plan de ce thème est blanche.

Modèles personnalisés

Dans le développement de thèmes WordPress par blocs, les développeurs peuvent créer des mises en page prédéfinies pour des pages personnalisées, des articles ou des types d'articles personnalisés que les utilisateurs peuvent utiliser.

Par exemple, le thème Twenty Twenty-Four a plusieurs modèles personnalisés définis dans le fichier theme.json : Page sans titre, Page avec barre latérale, Page avec grande image et Article avec barre latérale.

Vous pouvez utiliser l'un de ceux-ci pour créer votre contenu.

],
"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"
  }
]

Il est à noter que le fichier theme.json ne fait référence aux modèles que par leur nom et fournit des métadonnées à leur sujet, telles que leur titre et les types de publication pour lesquels ils sont destinés.

Cependant, l'apparence et la fonctionnalité réelles des modèles personnalisés sont définies dans des fichiers de modèle distincts à l'intérieur du dossier du thème.

Pour les voir, vous pouvez aller dans public_html » wp-content » themes » votre-nom-de-thème » templates.

Parties de modèle

Les parties de modèle sont des zones réutilisables que vous pouvez appliquer à vos modèles personnalisés. Ce sont des éléments tels que les en-têtes, les pieds de page, les barres latérales, etc.

Voici à quoi ressemblent ces parties de modèle enregistrées dans 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"
  }
]

Comme les modèles personnalisés, le fichier theme.json ne fait référence qu'aux modèles.

Leur apparence réelle est définie dans leurs propres fichiers de partie de modèle dans le dossier parts.

Motifs

Les motifs sont des collections de blocs préconçus qui vous permettent de créer des mises en page de contenu personnalisées sur vos pages, articles ou n'importe où ailleurs dans votre thème.

Lorsque vous ouvrez l'éditeur de site complet, vous remarquerez peut-être le menu Motifs. C'est là que vous pouvez trouver tous les motifs disponibles pour votre thème de blocs Gutenberg.

Avec theme.json, les développeurs de thèmes peuvent référencer des modèles du répertoire public de modèles. C'est un excellent moyen d'offrir plus d'options de personnalisation sans avoir à concevoir vous-même ces blocs réutilisables.

Par exemple, le thème Twenty Twenty-Four référence deux modèles du répertoire officiel : trois colonnes de services et une section clients :

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

Nous le savons car ces modèles se trouvent dans le menu Modèles de l'éditeur de site complet.

Cependant, ils ne se trouvent pas dans le dossier patterns à l'intérieur du répertoire du thème.

Ce que vous devriez faire avant de modifier le fichier theme.json

Étant donné que theme.json est un fichier de thème principal, le modifier directement sur votre site Web WordPress en direct comporte certains risques. Des erreurs accidentelles pourraient potentiellement casser votre thème ou votre site Web.

Une approche plus sûre consiste à utiliser un thème enfant.

Un thème enfant hérite de toutes les variations de style et des fonctionnalités de votre thème parent (le thème de blocs que vous utilisez) mais vous permet de personnaliser les choses sans modifier le thème parent lui-même. De cette façon, si le thème parent reçoit des mises à jour, vos personnalisations ne seront pas écrasées.

Vous pouvez consulter notre guide sur comment créer un thème enfant dans WordPress pour plus d'informations. Cet article présente une méthode simple avec le plugin Create Block Theme, qui générera automatiquement un nouveau fichier theme.json pour votre thème enfant uniquement.

Pour garantir une expérience d'édition fluide et éviter toute interruption de votre site web, nous vous recommandons également de créer une nouvelle sauvegarde de votre site WordPress. Ainsi, si quelque chose tourne mal, vous pourrez facilement restaurer votre site à son état précédent.

Nous vous recommandons d'utiliser un plugin tel que Duplicator pour une solution de sauvegarde rapide et fiable.

Il est également recommandé de travailler dans un environnement de développement WordPress local ou un site de staging. Cela crée une réplique de votre site Web en direct où vous pouvez tester les modifications en toute sécurité sans affecter vos visiteurs.

Voici quelques conseils supplémentaires à garder à l'esprit :

• Commencez par des modifications mineures dans votre fichier theme.json et testez-les minutieusement avant d'apporter des changements plus complexes.
• Si vous n'êtes pas sûr d'une propriété ou d'un paramètre spécifique dans le fichier theme.json, consultez la documentation officielle de WordPress.
• N'hésitez pas à demander de l'aide à l'équipe de support du développeur du thème ou aux forums de support de WordPress.org si vous rencontrez des problèmes. Consultez notre guide sur comment demander du support WordPress pour plus d'informations.

Comment modifier le fichier theme.json de WordPress

Sur la base de nos recherches et tests, nous avons découvert deux façons de modifier un fichier theme.json de WordPress : en utilisant l'éditeur complet du site ou en utilisant du code. La première option est beaucoup plus facile et plus sûre, et vous permet de voir vos modifications depuis le front-end de votre site Web.

Pendant ce temps, la deuxième option est recommandée si vous êtes à l'aise avec le développement WordPress avancé.

Modifier theme.json sans code (débutants)

Pour modifier votre fichier theme.json sans toucher directement au code, vous pouvez utiliser le plugin Create Block Theme. Ce plugin a été publié par l'équipe officielle de WordPress.org pour permettre aux utilisateurs de créer un thème de blocs personnalisé, de le modifier et/ou d'enregistrer les variations de style de leur thème de blocs.

Tout d'abord, installez le plugin WordPress dans votre zone d'administration. Ensuite, ouvrez l'éditeur complet du site en allant dans Apparence » Éditeur.

Vous verrez maintenant plusieurs menus pour modifier votre thème.

Ici, sélectionnez « Styles ».

Ensuite, cliquez sur l'icône en forme de crayon « Modifier les styles ».

Cela vous mènera à l'éditeur de blocs pour modifier les paramètres globaux et les styles de votre site web.

Vous pouvez maintenant modifier le style de votre thème comme d'habitude. Vous pouvez lire la section sur comment modifier les styles globaux de votre thème dans notre guide sur l'édition complète du site WordPress pour plus d'informations.

Essayons de créer une palette de couleurs personnalisée, par exemple.

La palette de couleurs est un ensemble de couleurs par défaut pour des éléments tels que le texte, les arrière-plans et les boutons. Elle garantit un aspect cohérent sur l'ensemble de votre site web.

Les éléments utilisant la même combinaison de couleurs correspondront toujours, de sorte que le design de votre site web paraisse soigné et professionnel.

Pour modifier la palette, sélectionnez « Couleurs » dans la barre latérale des paramètres de Styles.

Sur l'écran suivant, vous verrez des paramètres pour personnaliser les couleurs de votre thème.

Ici, cliquez sur les couleurs dans la section « Palette ».

Dans cet exemple, le thème Twenty Twenty-Four a déjà défini 5 couleurs dans la palette, mais vous pouvez les modifier pour en créer une personnalisée à partir de zéro.

Pour ce faire, cliquez sur l'une des couleurs sous « Thème ». Ensuite, sélectionnez n'importe quelle couleur dans l'outil de sélection de couleurs.

Maintenant, si vous prévisualisez votre site web, vous verrez que les blocs ou éléments spécifiques qui utilisaient la couleur précédente ont été remplacés par la couleur que vous venez de sélectionner dans votre palette.

Vous pouvez répéter les mêmes étapes pour chaque couleur. Ensuite, cliquez sur « Enregistrer ».

Après avoir enregistré vos modifications, cliquez sur le bouton Créer un thème de bloc (l'icône de clé à molette).

Ensuite, sélectionnez « Enregistrer les modifications du thème ».

Sur l'écran suivant, vous devez faire défiler vers le bas.

Après cela, cliquez sur « Enregistrer les modifications ». Cela demandera à WordPress de stocker toutes les modifications que vous avez apportées à votre thème dans le fichier theme.json.

Une fois que vous avez fait cela, l'éditeur de blocs se rafraîchira.

Maintenant, cliquez à nouveau sur le bouton Créer un thème de bloc et sélectionnez « Afficher theme.json ».

Pour voir le code de votre palette de couleurs personnalisée, recherchez palette imbriqué dans color et settings, comme ceci :

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

En dessous, vous devriez voir les nouveaux codes hexadécimaux de votre palette de couleurs personnalisée.

Modifier theme.json avec du code (utilisateurs avancés)

Cette méthode est recommandée si vous êtes un futur développeur de thèmes WordPress ou si vous avez une certaine expérience du code.

Tout d'abord, ouvrez le fichier theme.json de votre thème de bloc dans votre répertoire WordPress. Vous pouvez soit utiliser l'éditeur de code du gestionnaire de fichiers de votre hébergeur, soit télécharger le fichier, le modifier sur votre ordinateur, puis le téléverser sur votre serveur.

Nous utiliserons le thème Twenty Twenty-Four et le gestionnaire de fichiers de Bluehost à des fins de démonstration. Si vous êtes un utilisateur Bluehost et que vous utilisez le gestionnaire de fichiers, vous pouvez simplement faire un clic droit sur votre fichier theme.json et cliquer sur « Modifier ».

Si vous utilisez FTP, vous pouvez consulter notre guide sur comment utiliser FTP pour téléverser des fichiers sur WordPress.

Essayons un exemple simple de modification de votre fichier theme.json : la création de tailles de police personnalisées.

Encore une fois, rappelez-vous que la propriété settings spécifie les styles par défaut de votre thème, tandis que la propriété styles les implémente. Pour cette raison, nous modifierons la propriété settings dans le fichier theme.json.

Si vous utilisez un thème enfant, vous pouvez simplement copier et coller le code suivant dans votre fichier theme.json et modifier les tailles de police en pixels selon vos besoins :

{
  "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"
        }
      ]
    }
  }
}

Remarque : Si vous modifiez directement le fichier de votre thème parent, vous devez trouver le code qui dit fontSizes .

Il doit être imbriqué dans typography et settings , comme ceci :

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

Après cela, remplacez ces lignes de code par l'extrait de code ci-dessus. Assurez-vous simplement qu'il n'y a pas d'erreurs de syntaxe dedans.

Une fois terminé, enregistrez le fichier et prévisualisez votre site Web pour voir vos modifications. Pour les utilisateurs de Bluehost, vous pouvez simplement cliquer sur « Enregistrer les modifications » dans l'éditeur de code du gestionnaire de fichiers.

Si vous souhaitez modifier davantage votre theme.json, nous vous encourageons vivement à vous familiariser avec la structure du fichier, comme expliqué dans la section précédente.

Nous vous suggérons également de lire la Référence officielle des paramètres WordPress, qui comprend une liste complète des propriétés de paramètres disponibles et des instructions pour les utiliser.

Astuce bonus : Utilisez WPCode pour ajouter du code personnalisé à votre thème

Dans ce guide, vous avez découvert theme.json et son potentiel de personnalisation de thème. Mais il est peut-être encore un peu intimidant de le modifier directement.

Heureusement, il existe une autre option conviviale pour ajouter du code personnalisé et effectuer des personnalisations avancées : WPCode.

Avec WPCode, vous pouvez insérer des extraits de code personnalisés sans jamais avoir à toucher vous-même aux fichiers de votre thème. Cela réduit considérablement le risque de casser votre site web lors de la personnalisation.

Si vous souhaitez en savoir plus sur ce plugin d'extraits de code, consultez notre avis complet sur WPCode.

De plus, voici quelques tutoriels utiles pour vous aider à démarrer avec WPCode :

• Extraits de code WordPress utiles pour les débutants (choix d'expert)
• Comment mettre en évidence les nouveaux articles pour les visiteurs récurrents dans WordPress
• Comment mettre du texte en surbrillance dans WordPress
• Comment ajouter facilement une ombre portée dans WordPress

Nous espérons que cet article vous a aidé à en apprendre davantage sur le fichier theme.json dans WordPress. Vous voudrez peut-être aussi consulter notre guide pour débutants sur comment modifier un site WordPress et notre sélection d'experts des meilleurs constructeurs de pages glisser-déposer pour WordPress.

Si cet article vous a plu, abonnez-vous à notre chaîne YouTube pour des tutoriels vidéo WordPress. Vous pouvez également nous retrouver sur Twitter et Facebook.