Cet article expliquera en profondeur comment ajouter des paramètres de couleur à votre bloc WordPress Gutenberg personnalisé. Nous apprendrons comment ajouter le même composant de paramètres de couleur, qui permet de choisir parmi les couleurs de la palette et la couleur personnalisée, comme de nombreux blocs par défaut de WordPress l’utilisent.
Voici ce que nous allons ajouter à notre bloc personnalisé :
En utilisant les composants de Gutenberg, nous pouvons très facilement implémenter cette palette/section de couleurs dans notre propre bloc personnalisé. Vous pouvez définir les paramètres de couleur pour affecter la couleur de votre choix ; arrière-plan, couleur de texte, couleur de bordure ou quoi que ce soit d’autre. Vous pouvez également ajouter autant de paramètres de couleur que vous le souhaitez dans ce panneau.
Avant de plonger dans le code, il y a certaines choses dont vous devez être conscient. Ne passez pas directement au code car la section suivante expliquera en grande partie pourquoi le code doit le faire comme il le fait.
Ce que vous devez savoir en premier
Les composants pour implémenter les paramètres de palette/couleur sont PanelColorSettingset withColorsdu wp.blockEditorpackage. Le composant withColorsest un soi-disant composant d’ordre supérieur et doit être implémenté un peu différemment de la simple sortie d’un composant normal. J’entrerai dans un peu plus de détails plus tard. Mais nous devons d’abord connaître les bases de la façon dont Gutenberg gère les paramètres de couleur de bloc.
Comment les blocs Gutenberg gèrent les paramètres de couleur
Il existe certaines règles sur la façon dont Gutenberg gère les paramètres de couleur dans les blocs. Si vous avez déjà créé un thème pris en charge par Gutenberg, vous connaissez probablement déjà ces règles. Nous allons néanmoins les parcourir rapidement car nous devons gérer cela dans notre code de bloc.
- Lorsqu’une couleur de palette est choisie, l’élément de bloc de nœud obtiendra une classe d’un certain motif. La classe commence par "
has-", puis le slug de la palette vient après. La fin dépend de l’élément que la couleur doit affecter. Pour la couleur du texte, il se termine par "-color". Pour la couleur d’arrière-plan, il se termine par "-background-color". Par exemple, un bloc avec une palette de couleur "rouge" choisie comme couleur d’arrière-plan obtiendra la classe "has-red-background-color". - Lorsqu’une couleur personnalisée est choisie (à partir du sélecteur de couleurs), l’élément de bloc de nœud obtiendra un style en ligne avec le code hexadécimal. Par exemple, une couleur personnalisée #DD0000 choisie pour la couleur de fond recevra l’attribut "
style="background-color: #DD0000;".
Lorsque nous implémenterons les paramètres de couleur pour notre bloc, nous devrons implémenter la classe et le style en ligne corrects. Nous le ferons à la fin de ce tutoriel.
Comment travailler avecwithColors
Comme mentionné précédemment, il withColorss’agit d’un composant d’ordre supérieur. Cela signifie essentiellement que c’est un composant qui prend un composant et renvoie un nouveau composant. Dans le composant renvoyé, nous obtenons des accessoires utiles du composant d’ordre supérieur. Pour faire simple, nous utiliserons withColorspour retourner notre propre composant pour notre bloc personnalisé. Notre composant de bloc obtient les accessoires nécessaires pour travailler avec les couleurs de withColors.
Le composant withColorsgère l’état et de nombreuses fonctionnalités pour travailler avec les couleurs. Et nous obtenons beaucoup d’automatisation dans ce processus. C’est très pratique pour déterminer si la couleur choisie est une couleur de palette (nous devons ajouter une classe) ou une couleur personnalisée (nous devons ajouter un style en ligne). withColorssimplifier une grande partie du processus de stockage de la couleur choisie, quelle qu’elle soit, dans les attributs de notre bloc. En parlant d’attributs..
Attributs etwithColors
Évidemment, votre bloc a besoin d’attributs pour stocker la couleur choisie. Afin de bénéficier de l’automatisation de withColor pour stocker la couleur correcte, vous devez en fait définir deux attributs pour chaque paramètre de couleur. Un pour stocker le slug de la palette de couleurs et un autre pour stocker le code hexadécimal. Il y a quand même quelques règles.
Supposons que vous souhaitiez ajouter un paramètre de couleur pour la couleur du texte du bloc – vous décidez donc de définir un attribut bien nommé " textColor". Vous devrez alors définir un autre attribut dans le pattern «customYourOriginalAttribute». Dans cet exemple, le deuxième attribut devra être nommé " customTextColor". Attention au camelCase (majuscule) ici. Suivre ce modèle withColorsentraînera automatiquement :
- Si une couleur de palette a été choisie, l’attribut «
textColor» contiendra le slug de la palette. - Si une couleur personnalisée a été choisie, "
customTextColor" sera rempli avec le code hexadécimal.
Ces deux-là travaillent en tandem. Si une couleur personnalisée est choisie, textColorsera automatiquement undefined, et vice versa.
Et enfin, une dernière chose à retenir: vous n’aurez pas besoin d’utiliser setAttributes()pour mettre à jour vos attributs de couleur! Les accessoires fournis par withColorsincluent une fonction qui met automatiquement à jour vos attributs pour vous. Tout ce que vous avez à faire est de passer cette fonction à l’ onChangeévénement au PanelColorSettingscomposant, et vos attributs seront automatiquement mis à jour.
Ok, il est temps de voir tout cela en pratique !
Implémentation des paramètres de couleur dans un bloc personnalisé
Pour commencer, j’ai un bloc personnalisé assez inutile qui ne fait rien d’autre que d’afficher un texte codé en dur. Cela facilite simplement la séparation de ce que nous devons coder pour ajouter des paramètres de couleur. J’ai une série de tutoriels sur la façon de créer vos propres blocs personnalisés si vous souhaitez en savoir plus.
Remarque : J’écris tout le code dans ES6/ESNext. Cela inclut les fonctions fléchées qui nécessitent une attention particulière dans votre configuration Babel/webpack. Si vous obtenez des erreurs sur certains des codes ci-dessous, suivez mon guide sur la façon de configurer Webpack et Babel pour ES6/ESNext ou ajustez le code pour ne pas utiliser de "syntaxes expérimentales".
Ceci est mon bloc personnalisé de base avant de faire quoi que ce soit avec les paramètres de couleur :
C’est assez basique. Notez que la editfonction fait simplement référence à un composant séparé, BlockWithColorSettings, au lieu de l’écrire en ligne. Cela facilite la mise en œuvre withColorsultérieure.
D’accord, il est temps d’implémenter les paramètres de couleur dans notre bloc ! Par exemple, je veux configurer la couleur du texte.
Ajout d’attributs
Comme mentionné précédemment, nous devons définir deux attributs pour chaque paramètre de couleur. Et nous devons faire très attention à leur dénomination. Je souhaite ajouter un attribut de couleur de texte, je nomme donc l’attribut textColor. Ce qui signifie que je vais également ajouter un attribut customTextColor. Les deux doivent être de type chaîne.
Nos attributs sont prêts à stocker le paramètre de couleur du texte du bloc. Il est maintenant temps de mettre en œuvre withColorset PanelColorSettings.
ExécutionwithColors
Comme mentionné précédemment withColors, il s’agit d’un composant d’ordre supérieur qui devrait prendre un composant à retourner. Nous voulons évidemment qu’il renvoie notre composant d’édition, BlockWithColorSettings. Mais comme paramètre, withColorsnous fournissons un objet.
Dans l’objet passé à, withColorsnous devons indiquer withColorsquel attribut nous voulons utiliser pour stocker la couleur et quel type d’élément il colorera (dans notre cas, la couleur du texte, qui signifie la règle CSS "couleur"). L’information sur la règle CSS permet de s’assurer que les noms de classe renvoyés sont corrects. Comme il s’agit de la couleur du texte, nous voulons des noms de classe tels que "a–couleur".
D’abord quelques déstructurations en haut. withColorsréside dans le wp.blockEditorpackage.
const { withColors } = wp.blockEditor;Nous allons changer la editfonction en :
Avec ce code, notre composant BlockWithColorSettingsrecevra quelques accessoires supplémentaires :
props.textColor: Est un objet qui se compose de toutes les informations sur la couleur choisie. Si une couleur de palette a été choisie, elle stockera les propriétés du code hexadécimal, du slug de palette, du nom de la classe, etc. Si une couleur personnalisée a été choisie, l’objet contiendra le code hexadécimal. Le code hexadécimal se trouve toujours dans la propriétécolor. Et le nom de la classe (uniquement si une couleur de palette a été choisie) sera défini dans la propriétéclass.props.setTextColor: Une fonction qui mettra à jour nos attributs pour nous. Nous le fournissons pour l’événement des paramètres de couleuronChangecomme nous le verrons plus tard. La fonction mettra à jour les attributstextColoret.customTextColorParce que nous avons suivi les règles de dénomination, il sera automatiquement mis à jourcustomTextColormême si nous n’avons jamais fourni ce nom d’attribut.
Notez que la fonction "set" fournie comme accessoire suivra la règle : " setYourAttributeName". Parce que nous avons fourni textColor, la fonction est nommée setTextColor. Si nous nommions plutôt notre attribut awesomeColoret le fournissions dans l’ withColorsobjet, la fonction set serait nommée setAwesomeColor().
ExécutionPanelColorSettings
La prochaine étape consiste à implémenter la section Inspecteur proprement dite. Pour ce faire, nous ajoutons PanelColorSettingsà l’intérieur d’un InspectorControlscomposant. Parce que React exige que tout soit à l’intérieur d’un nœud racine, nous utilisons également Fragment(from wp.elements) pour tout envelopper à l’intérieur.
D’abord quelques déstructurations en haut du fichier :
const { Fragment } = wp.element;
const { InspectorControls, PanelColorSettings, withColors } = wp.blockEditor;Et nous mettons à jour notre BlockWithColorSettingscomposant en quelque chose comme ceci :
Comme vous pouvez le voir en ligne, #2nous déstructurons les accessoires reçus de withColors, textColoret setTextColor. Gardez à l’esprit que props.textColorc’est l’objet reçu de withColors, et props.attributes.textColorc’est l’attribut. Nous n’avons cependant pas besoin de nous référer à l’attribut.
En tant qu’accessoires du composant, PanelColorSettingsnous pouvons fournir un titre pour la section (titre dans la boîte réductible dans l’inspecteur). La chose importante ici est l’accessoire colorSettingsoù nous devons fournir un tableau d’objets de réglage de couleur. Pour chaque paramètre de couleur (nous n’en avons actuellement qu’un), nous devons fournir certaines propriétés. La propriété valueattend le code hexadécimal actuellement choisi (même si une couleur de palette a été choisie). Ceci nous est fourni dans l’ textColoraccessoire, à l’intérieur de la propriété color. Pour la onChangepropriété, nous fournissons simplement la fonction "set" fournie par withColors, setTextColor. Et enfin, nous devrions donner un labelafin que l’utilisateur sache quel élément cette couleur affectera. Il apparaîtra juste au-dessus de la zone de choix d’une couleur.
Voici comment notre composant apparaît actuellement dans l’éditeur Gutenberg :
Il met maintenant à jour avec succès nos attributs lors du choix des couleurs. Vous pouvez voir qu’il se souvient de votre choix de couleur lors de l’enregistrement du message.
Cependant, rien ne se passe visuellement lorsque vous changez de couleur. Le choix de couleur est stocké dans les attributs, mais aucun changement de couleur ne se produit dans l’éditeur, ni lors de la prévisualisation de la publication. C’est parce que nous devons ajouter du code pour les classes et les styles du bloc. Nous devons le faire à la fois pour la editfonction (qui est pour l’éditeur) et savela fonction (frontend). C’est la prochaine étape.
Gestion des styles de classe et en ligne dansedit
Nous devons créer les attributs de classe et de style de nœud du bloc en fonction du paramètre de couleur choisi. Heureusement, withColorsnous obtenons une certaine automatisation dans ce domaine. N’oubliez pas qu’il props.textColors’agit d’un objet qui contient toutes les informations dont nous avons besoin, y compris le nom de la classe.
Nous pourrions faire quelque chose comme ceci :
À la ligne, #20nous appliquons la classe critique et le style en ligne au nœud racine de notre bloc. Avant cela, nous construisons la classe et l’attribut de style en ligne en vérifiant l’ props.textColorobjet.
Après ce changement, votre bloc personnalisé devrait maintenant être entièrement fonctionnel dans l’éditeur. Chaque fois que vous changez de couleur, le bloc change la couleur du texte. Impressionnant! La dernière étape consiste à le faire saveégalement pour la fonction, afin que nous obtenions également ces classes et ces styles dans le frontend.
Gestion des styles de classe et en ligne danssave
Le concept de construction des styles de classe et en ligne et de leur application au nœud racine est le même dans saveque dans edit. Mais il y a une différence cruciale. Dans savenous n’avons pas les accessoires fournis par withColors. Et nous ne pouvons pas ajouter de composants d’ordre supérieur à la savefonction. Ainsi, dans la savefonction, toutes les informations dont nous disposons sont les attributs.
C’est une bonne règle d’or d’éviter de coder en dur les noms de classe "has-". Et si WordPress décidait de changer cette règle à l’avenir? Heureusement, nous avons une fonction qui peut nous aider à générer les bons noms de classe pour nous: getColorClassName().
Avant d’oublier, déstructurons-le. C’est aussi dans le wp.blockEditorpaquet.
const { InspectorControls, PanelColorSettings, withColors, getColorClassName } = wp.blockEditor;L’utilisation de la getColorClassName()fonction nécessite deux paramètres. D’abord une chaîne pour la règle CSS. Étant donné que notre paramètre de couleur concerne la couleur du texte, nous fournissons ‘ color‘. Cela indique à la fonction qu’elle doit renvoyer un nom de classe "a-quelque chose-couleur" et non "a-quelque chose-couleur-arrière-plan" par exemple. Comme deuxième paramètre, nous devons fournir la valeur de l’attribut.
L’attribut style est simplement construit en définissant «color» sur la valeur de l’attribut customTextColor, s’il est défini.
Et bien sûr, n’oubliez pas d’appliquer la classe et le style sur le nœud racine de votre bloc ; comme en ligne #12.
PS: Si vous testez votre bloc dans l’éditeur en écrivant ce code, vous obtiendrez maintenant une erreur de bloc. Cela se produit parce que nous avons maintenant modifié la sortie de la savefonction et que tout ce que vous avez enregistré précédemment est en conflit. Vous devrez supprimer le bloc et le rajouter à nouveau.
Après ce changement, votre bloc devrait maintenant appliquer correctement la couleur de texte choisie dans le frontend également.
Et c’est tout! Vous avez maintenant implémenté avec succès les paramètres de couleur dans votre bloc. Si vous souhaitez ajouter plusieurs paramètres de couleur (pas seulement la couleur du texte), lisez la suite.
Remarque sur les paramètres de couleurs multiples
À présent, vous devriez être en mesure d’implémenter plusieurs paramètres de couleur. Vous voudrez peut-être ajouter des paramètres pour la couleur d’arrière-plan, la couleur du texte, la couleur de la bordure ou quoi que ce soit d’autre pour votre bloc. Dans cette section, je vais faire un bref aperçu de ce que nous devons faire pour implémenter plusieurs paramètres de couleur.
Supposons que je souhaite également ajouter une couleur d’arrière-plan à mon bloc.
Je dois d’abord définir un nouvel attribut nommé de manière créative backgroundColor. Je définis également un autre attribut customBackgroundColor.
Dans la editfonction, je change l’objet fourni en withColorstant que tel:
withColors({textColor: 'color', backgroundColor: 'background-color'})Cela indique withColorsque mon textColorattribut est pour la règle CSS " color" (pour la couleur du texte), et l’attribut backgroundColorest pour la règle CSS " background-color". withColorsreconnaîtra et mettra également à jour automatiquement les attributs et customTextColor.customBackgroundColor
Dans le PanelColorSettingscomposant, je fournis un autre objet au tableau au prop colorSettings. Ainsi:
Avec cela, vous devriez obtenir deux paramètres de couleur distincts dans la zone Inspecteur pour les paramètres de couleur.
La dernière étape consiste à créer les noms et les styles de classe appropriés dans editet save. Il s’agit d’une étape assez simple car il s’agit simplement de créer correctement une chaîne ou un objet de style. N’oubliez pas que votre nom de classe doit prendre en charge plusieurs classes de couleurs (par exemple, si la couleur du texte et la couleur d’arrière-plan ont été choisies). Ajoutez simplement un espace entre chaque nom de classe.
PS : si vous devez gérer de nombreux noms de classe pour votre bloc, vous pourriez bénéficier de l’installation du classnamespackage. Presque tous les composants de Gutenberg utilisent cette bibliothèque pour combiner plus facilement les noms de classe.
Conclusion et code complet
Vous devriez maintenant avoir appris à implémenter les paramètres de couleur dans votre bloc personnalisé. J’espère que cela vous a été utile! J’ai dû ajouter cette fonctionnalité à mon projet, et je n’ai vraiment trouvé aucune information ou bonne documentation. C’est donc le résultat de la consolidation de tout ce que j’ai appris sur ce sujet, après de nombreux essais et erreurs.
Voici le code final, au total, pour l’exemple de bloc personnalisé avec réglage de la couleur du texte :