En 2018, WordPress a introduit l’éditeur Gutenberg avec la version 5.0, apportant une nouvelle façon de construire des pages et des articles à l’aide de « blocs ». Au début, ces blocs étaient assez basiques, mais au fil des ans, ils ont évolué pour offrir plus de flexibilité et une meilleure expérience d’édition.
Pourtant, il arrive qu’un bloc ne fasse pas tout à fait ce dont vous avez besoin. Vous voulez peut-être supprimer certaines fonctions, en ajouter de nouvelles, appliquer un style spécifique par défaut ou rendre certains réglages plus faciles d’accès. Dans ce cas, la création d’un bloc personnalisé à partir de zéro peut sembler une option, mais – soyons honnêtes – c’est exagéré pour de petites modifications. Ne serait-il pas plus simple de modifier des blocs qui existent déjà ?
C’est là que l’API des blocs entre en jeu. Cet article explique comment étendre les blocs de base de WordPress à l’aide de l’API des blocs, en fournissant des exemples pratiques qui peuvent être utilisés dans des projets réels.
Comprendre l’API des blocs WordPress
L’API des blocs WordPress est la base de l’éditeur de blocs, permettant aux développeurs de créer, de modifier et d’étendre les blocs. L’API propose différentes façons d’interagir avec les blocs. Vous pouvez :
- Modifier les réglages des blocs – Changer les attributs, les valeurs par défaut et les comportements des blocs.
- Ajouter ou supprimer des supports de bloc – Activer ou désactiver des caractéristiques telles que la typographie, les couleurs et l’espacement.
- Injecter des contrôles personnalisés – Ajouter de nouvelles options à l’intérieur du panneau des réglages du bloc.
- Créer des variations de blocs – Créer des versions préconfigurées de blocs existants pour accélérer la création de contenu.
Chaque bloc dans WordPress, qu’il s’agisse d’un paragraphe, d’une image ou d’un bouton, est défini par un ensemble d’attributs et de réglages stockés dans un fichier block.json. Ce fichier contient des métadonnées sur le bloc, notamment son nom, sa catégorie, ses attributs par défaut et les fonctionnalités qu’il prend en charge.
WordPress vous permet de modifier ces valeurs à l’aide de PHP ou de JavaScript, mais cet article explique comment utiliser les crochets de filtrage de l’API des blocs. Cela permet de s’assurer que tes modifications sont enregistrées sur le serveur sans qu’il soit nécessaire de mettre en file d’attente des fichiers JavaScript supplémentaires.
Par exemple, si vous voulez activer ou désactiver certaines fonctions d’un bloc, la meilleure façon de le faire est d’utiliser le filtre register_block_type_args en PHP. Cette méthode vous permet d’ajuster les réglages du bloc de façon dynamique sans modifier directement le fichier block.json.
Modifier les supports des blocs
Les blocs WordPress sont livrés avec des supports prédéfinis, qui contrôlent les options de l’éditeur. Certains blocs, comme le bloc Image (core/image), ont des filtres duotone activés par défaut, ce qui permet aux utilisateurs d’appliquer des superpositions de couleurs.
Cependant, le bloc Média & Texte (core/media-text) ne prend pas en charge le duotone d’emblée, même s’il permet aux utilisateurs d’insérer une image. Cela signifie que si vous pouvez appliquer un filtre duotone à un bloc Image autonome, vous ne pouvez pas faire de même lorsqu’une image est placée à l’intérieur d’un bloc Média & Texte.
Étant donné que le bloc Média et texte peut contenir une image, il est logique d’activer les filtres duotone. Nous pouvons le faire en modifiant son tableau supports et en spécifiant le sélecteur CSS correct pour que le filtre s’applique correctement. Nous pouvons l’activer en utilisant le filtre register_block_type_args en PHP.
Ajoutez le code suivant au fichier functions.php de votre thème :
function enable_duotone_for_media_text_block($args, $block_type) {
// Only modify the Media & Text block
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter('register_block_type_args', 'enable_duotone_for_media_text_block', 10, 2);Le code ci-dessus active le filtre duotone à l’intérieur du tableau supports et définit le sélecteur CSS correct pour appliquer l’effet duotone aux images à l’intérieur du bloc Média & Texte. La fonction add_filter() utilise 10 comme priorité (lorsque le filtre s’exécute) et 2 pour spécifier le nombre d’arguments passés ($args, $block_type).
Lorsque vous enregistrez le fichier et que vous le rechargez, vous devriez voir les contrôles Duotone disponibles dans la section Filtres.
L’activation du duotone pour le bloc Média & Texte à l’aide de register_block_type_args est un moyen efficace de modifier le comportement du bloc de manière dynamique. Cependant, WordPress propose une autre méthode pour modifier les réglages des blocs : remplacer les métadonnées des blocs à l’aide de block_type_metadata.
Les deux approches vous permettent de personnaliser les blocs, mais elles fonctionnent à des étapes différentes du processus d’enregistrement des blocs.
Par exemple, disons que nous voulons ajuster le bloc Paragraphe (core/paragraph) pour qu’il ne prenne en charge que les ajustements de marge et qu’il désactive le remplissage. Une façon d’y parvenir est d’utiliser register_block_type_args:
function modify_paragraph_spacing_args($args, $block_type) {
if ($block_type === 'core/paragraph') {
$args['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $args;
}
add_filter('register_block_type_args', 'modify_paragraph_spacing_args', 10, 2);Cette méthode fonctionne bien dans la plupart des cas, mais comme elle modifie le bloc après qu’il a déjà été enregistré, elle peut parfois être remplacée par d’autres extensions ou thèmes qui modifient le même bloc plus tard dans le processus.
Une approche plus structurée dans ce cas pourrait consister à remplacer les métadonnées du bloc directement en utilisant block_type_metadata:
function mytheme_modify_paragraph_spacing($metadata) {
if ($metadata['name'] === 'core/paragraph') {
$metadata['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $metadata;
}
add_filter('block_type_metadata', 'mytheme_modify_paragraph_spacing');Aucune des deux approches n’est intrinsèquement meilleure que l’autre – cela dépend simplement du moment où vous voulez modifier le bloc et de la persistance du changement.
Enregistrement des styles de blocs
De nombreux blocs WordPress sont dotés de styles prédéfinis que les utilisateurs peuvent sélectionner dans l’éditeur. Un bon exemple est le bloc Image (core/image), qui inclut un style Arrondi par défaut. Cependant, les coins arrondis par défaut sont souvent trop extrêmes, ce qui fait que l’image ressemble plus à un ovale qu’à un élément bien stylisé.
Au lieu d’ajuster manuellement l’arrondi de la bordure pour chaque image, une meilleure approche consiste à personnaliser le style arrondi afin qu’il applique un arrondi plus raffiné – peut-être en ajoutant une ombre subtile pour un look moderne. De cette façon, les utilisateurs peuvent simplement cliquer sur un bouton pour appliquer un style bien conçu sans avoir besoin de modifier manuellement les réglages à chaque fois.
Prenons le style Arrondi du bloc Image et personnalisons-le pour que les coins soient légèrement arrondis au lieu d’être excessivement courbés, et qu’une ombre subtile soit ajoutée pour un aspect plus soigné.
Comme l’éditeur de blocs permet d’enregistrer et de désenregistrer les styles de blocs, nous pouvons supprimer le style Arrondi par défaut et le remplacer par une version personnalisée.
Voici comment procéder :
function modify_image_block_rounded_style() {
// Remove the default "Rounded" style
unregister_block_style( 'core/image', 'rounded' );
// Register a new "Rounded" style with custom CSS
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'inline_style' => '
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjust this value */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Optional shadow */
}
',
)
);
}
add_action( 'init', 'modify_image_block_rounded_style' );Le code remplace le style trop arrondi par défaut par une version raffinée qui applique border-radius: 20px; pour des coins plus doux et box-shadow pour une élévation subtile.
Utilisation d’un fichier CSS externe au lieu de styles en ligne
Si le style en ligne fonctionne bien pour les styles simples, il n’est pas idéal pour la maintenabilité. Une meilleure approche consiste à définir les styles dans un fichier CSS externe et à le mettre en file d’attente.
Pour cela, créez un nouveau fichier CSS, par exemple custom-block-styles.css, et ajoutez-y ceci :
/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjusted rounded corners */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Subtle shadow */
}Ensuite, vous mettez en file d’attente le fichier CSS dans functions.php:
function enqueue_custom_block_styles() {
wp_enqueue_style(
'custom-block-styles',
get_template_directory_uri() . '/css/custom-block-styles.css',
array(),
'1.0'
);
}
add_action('wp_enqueue_scripts', 'enqueue_custom_block_styles');
add_action('enqueue_block_editor_assets', 'enqueue_custom_block_styles');Maintenant, au lieu d’utiliser le style inline, vous pouvez enregistrer le style sans intégrer le CSS directement dans PHP :
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'style_handle' => 'custom-block-styles'
)
);De cette façon, vous pouvez modifier les styles sans toucher à PHP.
Enregistrer des variations de blocs
Les variations de bloc vous permettent de créer des versions prédéfinies d’un bloc avec des réglages personnalisés, ce qui permet aux utilisateurs d’appliquer plus facilement des conceptions cohérentes en un seul clic. Au lieu de modifier manuellement les réglages d’un bloc à chaque fois, une variation vous permet d’insérer un bloc auquel les bons attributs, styles ou configurations sont déjà appliqués.
Certains blocs de base de WordPress fonctionnent en fait de cette façon. Le bloc Embed n’est pas un bloc unique – c’est un ensemble de variations pour différentes plateformes comme YouTube, Twitter et Spotify. Le bloc Row et le bloc Stack sont également des variantes du bloc Group, chacune avec des réglages de mise en page différents.
Cette approche permet de conserver une certaine modularité, ce qui permet à WordPress de proposer des expériences personnalisées tout en utilisant une structure sous-jacente commune.
Création d’une variante Témoignage du bloc Citation
Bien que WordPress ne dispose pas d’un bloc dédié aux témoignages, le bloc Citation (core/quote) peut être adapté à cet effet. Au lieu de demander aux utilisateurs d’ajouter manuellement une image, d’aligner le texte et de tout mettre en forme, nous pouvons définir une variante Témoignage du bloc Citation.
Cette variante comprend automatiquement un bloc Image, un bloc Citation et deux blocs Paragraphe pour le nom et l’entreprise de la personne. Cela permet de s’assurer que chaque témoignage suit le même format structuré sans nécessiter d’ajustements supplémentaires.
Pour enregistrer une variation de bloc dans WordPress, nous utilisons registerBlockVariation() en JavaScript. Comme les variations de bloc sont gérées côté client, nous devons mettre en file d’attente un fichier JavaScript qui enregistre notre variation de témoignage personnalisée.
Pour mettre cela en œuvre, créez un fichier JavaScript (comme custom-block-variations.js) qui définit la variation Témoignage du bloc Citation. Vous pouvez créer ce fichier dans le répertoire assets/js/ de votre thème et ajouter le code suivant :
wp.domReady(() => {
wp.blocks.registerBlockVariation(
'core/quote',
{
name: 'testimonial',
title: 'Testimonial',
description: 'A variation of the Quote block for testimonials.',
category: 'text',
attributes: {
className: 'is-style-testimonial',
},
innerBlocks: [
['core/image', { align: 'center', width: 100, height: 100 }],
['core/quote'],
['core/paragraph', { placeholder: 'Name', align: 'center', fontSize: 'medium', className: 'testimonial-name' }],
['core/paragraph', { placeholder: 'Company / Role', align: 'center', fontSize: 'small', className: 'testimonial-company' }]
],
scope: ['inserter'],
}
);
// Inject inline styles for the editor preview
const style = document.createElement('style');
style.innerHTML = `
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial p {
margin-bottom: 12px;
font-size: 1.1em;
}
.wp-block-quote.is-style-testimonial cite {
font-weight: bold;
display: block;
margin-top: 10px;
color: #0073aa;
}
.wp-block-quote.is-style-testimonial .wp-block-image {
display: flex;
justify-content: center;
margin: 0 auto 12px;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
`;
document.head.appendChild(style);
});Dans le code ci-dessus, registerBlockVariation() définissez la variante Témoignage du bloc Citation, en préchargeant un bloc Image, un bloc Citation et deux blocs Paragraphe pour le nom et l’entreprise de la personne. Le bloc Image est centré à 100×100 pixels pour des images de profil uniformes, tandis que le bloc Citation reste inchangé en tant que texte de témoignage.
Une classe personnalisée (is-style-testimonial) est appliquée pour le style, donnant au bloc un arrière-plan clair, une ombre subtile et un texte centré. La bordure gauche par défaut est supprimée et l’image conserve son rapport hauteur/largeur avec des coins légèrement arrondis pour un aspect soigné.
Ensuite, comme le fichier JavaScript doit être chargé dans l’éditeur de blocs, nous devons le mettre en file d’attente à l’adresse functions.php.
function enqueue_custom_block_variations() {
wp_enqueue_script(
'custom-block-variations',
get_template_directory_uri() . '/assets/js/custom-block-variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( get_template_directory() . '/assets/js/custom-block-variations.js' ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_custom_block_variations' );Cela permet de s’assurer que la variation du bloc Témoignage apparaît dans l’éditeur de blocs.
Alors que le code JavaScript garantit que le bloc apparaît correctement dans l’éditeur, nous devons également appliquer les styles sur l’interface publique pour que les témoignages s’affichent correctement lorsqu’ils sont publiés. Ajoutez le code suivant à functions.php:
function register_testimonial_block_style() {
register_block_style(
'core/quote',
array(
'name' => 'testimonial',
'label' => __( 'Testimonial', 'your-text-domain' ),
'inline_style' => '
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
',
)
);
}
add_action( 'init', 'register_testimonial_block_style' );Désormais, chaque fois qu’un utilisateur insère un bloc de témoignage, il inclut déjà les champs image, citation, nom et entreprise, tous préformatés et stylisés correctement. Cela élimine le besoin d’ajustements manuels et garantit que chaque témoignage suit la même structure propre et professionnelle.
Au lieu de forcer les utilisateurs à construire des témoignages à partir de zéro, cette variation de bloc fournit un flux de travail rationalisé qui améliore la création de contenu tout en maintenant la cohérence de la conception du site.
Cas d’utilisation avancé : Combiner les API Supports et Styles pour créer des boutons de marque
Maintenant que vous savez ce que chaque API peut faire et comment elle fonctionne, pourquoi ne pas pousser les choses un peu plus loin ? Au lieu d’utiliser l’API Supports ou l’API Styles séparément, nous pouvons les utiliser ensemble pour résoudre un seul problème : maintenir la cohérence de la conception tout en donnant aux utilisateurs un moyen structuré d’appliquer les bons styles.
Considérons un scénario du monde réel. Une entreprise souhaite que tous les boutons de son site respectent des directives strictes en matière de marque. Elle ne veut pas que les utilisateurs choisissent des couleurs au hasard, modifient le remplissage ou appliquent une typographie bizarre. Cependant, elle veut de la flexibilité – les utilisateurs doivent donc pouvoir choisir entre deux styles de boutons pré-approuvés :
- Bouton principal – Le principal bouton d’appel à l’action, avec un arrière-plan solide et un style audacieux.
- Bouton secondaire – Un bouton plus subtil, avec un contour, généralement utilisé pour des actions secondaires.
Pour y parvenir, nous devons :
- Utiliser l’API Styles pour définir les deux styles de boutons.
- Utiliser l’API Supports pour supprimer les réglages inutiles, afin de s’assurer que les utilisateurs ne remplacent pas manuellement l’image de marque en modifiant les couleurs, l’espacement ou la typographie.
En combinant les deux API, nous permettons des choix structurés tout en empêchant les utilisateurs de casser le système de conception.
Étape 1 : Définir des styles de boutons personnalisés
Commencez par ajouter le code suivant au fichier functions.php:
function register_custom_button_styles() {
register_block_style(
'core/button',
array(
'name' => 'primary-button',
'label' => __( 'Primary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-primary-button .wp-block-button__link {
background-color: #4D4D4D;
color: #ffffff;
padding: 12px 24px;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: 2px 2px 6px rgba(0, 0, 0, 0.1);
}
',
)
);
register_block_style(
'core/button',
array(
'name' => 'secondary-button',
'label' => __( 'Secondary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-secondary-button .wp-block-button__link {
background-color: transparent;
color: #4D4D4D;
padding: 12px 24px;
border: 1px solid #4D4D4D;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: none;
}
',
)
);
}
add_action( 'init', 'register_custom_button_styles' );Désormais, lorsque les utilisateurs insèrent un bloc Bouton, ils voient Bouton principal et Bouton secondaire comme choix de style.
Le bouton principal a un arrière-plan gris foncé uni, tandis que le bouton secondaire a un arrière-plan transparent avec une bordure. Les deux boutons ont un rembourrage, un rayon de bordure et un style de police cohérents, ce qui garantit une apparence professionnelle sur l’ensemble du site.
Étape 2 : Restreindre la personnalisation des boutons
Bien que les styles des boutons soient maintenant prédéfinis, les utilisateurs peuvent toujours les remplacer manuellement en utilisant les paramètres de l’éditeur de blocs de WordPress. S’ils modifient les couleurs, le remplissage ou la typographie, les boutons risquent de ne plus correspondre aux directives de la marque.
Nous pouvons utiliser l’API Supports pour désactiver ces options de personnalisation, empêchant ainsi les utilisateurs d’apporter des modifications involontaires. Ajoute ceci à functions.php:
function restrict_button_customization($args, $block_type) {
if ($block_type === 'core/button') {
// Disable specific color settings (text, background, link)
$args['supports']['color'] = [
'text' => false,
'background' => false,
'link' => false,
];
// Disable typography settings (font size, font weight, line height)
$args['supports']['typography'] = false;
// Disable spacing settings (padding, margin)
$args['supports']['spacing'] = false;
}
return $args;
}
add_filter('register_block_type_args', 'restrict_button_customization', 10, 2);Avec ceci en place :
- Les utilisateurs ne peuvent pas changer la couleur des boutons, donc tous les boutons doivent adhérer à la palette de couleurs de la marque.
- Les contrôles de typographie sont supprimés, ce qui permet de conserver un formatage de texte cohérent.
- Les ajustements d’espacement sont désactivés, ce qui empêche les utilisateurs de modifier le rembourrage et les marges.
Maintenant, au lieu de laisser les utilisateurs créer un mélange aléatoire de styles de boutons, ils choisiront simplement entre les styles primaire et secondaire, ce qui permettra de conserver une conception professionnelle et structurée.
Résumé
Nous n’avons fait qu’effleurer la surface de ce qui est possible avec la personnalisation des blocs WordPress. WordPress fournit une vaste collection d’API qui facilitent l’extension et la personnalisation des blocs, ce qui permet aux développeurs d’adapter l’expérience de l’éditeur tout en gardant les choses structurées et conviviales.
Si vous voulez vraiment maîtriser la personnalisation des blocs, il y a encore beaucoup de choses à explorer. Consultez la documentation officielle destinée aux développeurs de WordPress, assistez aux WordCamps et aux meetups, et continuez d’apprendre grâce à d’excellentes ressources telles que le blog Kinsta, où nous décomposons régulièrement des concepts avancés de WordPress.
Bien sûr, le fait d’avoir un fournisseur d’hébergement solide permet d’expérimenter ces changements sans effort. Que vous tesitez de nouvelles modifications de blocs ou que vous gériez un site à fort trafic, un hébergement fiable garantit des performances fluides et une évolutivité facile. Chez Kinsta, nous avons construit notre plateforme pour gérer exactement cela. En fait, nous avons récemment été classés numéro 1 de l’hébergement WordPress par G2, grâce à plus de 930 avis clients.
Cela en dit long : Vous pouvez nous faire confiance pour alimenter ton expérience WordPress.
Joel est un développeur d'interfaces publiques qui travaille chez Kinsta en tant que rédacteur technique. Il est un enseignant passionné par l'open source et a écrit plus de 200 articles techniques, principalement autour de JavaScript et de ses frameworks.
