Comment ajouter une sélection d’image dans votre bloc WordPress Gutenberg personnalisé

Ce message est pour vous qui créez un bloc Gutenberg personnalisé et avez besoin d’un moyen de sélectionner ou de télécharger une image à partir de la médiathèque. La plupart des autres types de champs, tels que les cases à cocher, les entrées de texte ou les sélecteurs de couleurs, sont assez faciles à ajouter, mais un téléchargeur de médias nécessite un peu plus de code. Nous allons créer un composant Inspector qui est responsable du rendu d’un bouton pour ouvrir la bibliothèque multimédia, sélectionner une image et éventuellement la supprimer ou la modifier ultérieurement. Le tout utilisant des composants WordPress standard.

Avant de plonger dans le code, veuillez garder à l’esprit que cet article nécessite certaines connaissances de Gutenberg sur la façon d’écrire des blocs personnalisés. Nous nous concentrerons uniquement sur la partie téléchargeur de médias et non sur la manière de s’enregistrer et de créer un bloc Gutenberg en soi. Si vous ne savez pas comment écrire un bloc Gutenberg personnalisé, j’ai une série de tutoriels couvrant exactement ceci :

Avec cela à l’écart, plongeons dedans !

Ce que nous ferons

La fonction de sélection de média sera fonctionnellement exactement la même que la fonction d’image en vedette de WordPress. Nous allons à l’intérieur d’Inspector ajouter un panneau composé d’un bouton pour choisir une image.

Lorsque vous cliquez sur le bouton, la fenêtre "Sélectionner ou télécharger un média" s’affiche, vous permettant de sélectionner un fichier dans la bibliothèque multimédia. Nous limitons la bibliothèque multimédia pour afficher uniquement les images. Une fois qu’une image est sélectionnée, la fenêtre contextuelle se ferme et le panneau prévisualise un petite vignette de l’image sélectionnée. Sous les boutons de prévisualisation pour modifier et supprimer l’image apparaîtront. Exactement comme avec l’image sélectionnée.

Ce didacticiel suppose que vous utiliserez l’image sélectionnée comme arrière-plan du bloc – juste à titre d’exemple. C’est pourquoi nous stockons l’URL de l’image. J’inclurai un exemple sur la façon d’utiliser l’image sélectionnée (à la fois dans editet dans la savefonction). Lors du choix d’une image, l’image apparaîtra en arrière-plan de notre bloc, à la fois dans l’éditeur et dans le frontend.

Nous stockons l’ID et l’URL du média dans les attributs du bloc. Le code utilise withSelect, un composant d’ordre supérieur fourni dans wp.datale package, pour demander plus d’informations sur le média sélectionné, par ID.

J’emprunte également des noms de classe à la fonctionnalité d’image en vedette de WordPress pour m’assurer que tout a l’air bien et qu’il n’est pas nécessaire d’écrire de CSS vous-même. Ceci est bien sûr facultatif.

Enregistrement du média sélectionné dans les attributs

Ce que vous devez enregistrer dans les attributs de votre bloc dépend un peu de vous. Au minimum, nous devons stocker l’ID du média, évidemment. Cela peut suffire si vous n’avez pas besoin d’utiliser l’URL du média n’importe où dans le code du script. Par exemple, si vous utilisez ServerSideRenderoù PHP est responsable du rendu de la sortie du bloc. Dans ce cas, vous pouvez facilement obtenir l’URL de l’image à partir de l’ID de média en utilisant par exemple [wp_get_attachment_image_src](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src/)(). Cependant, dans l’exemple ci-dessous, je montre un exemple simple d’affichage de l’image en arrière-plan de notre bloc, donc je stocke également l’URL du média en tant qu’attribut. Nous utiliserons l’attribut URL à la fois dans edit(pour ajouter l’arrière-plan dans l’éditeur) et dans save(pour ajouter l’arrière-plan dans l’interface).

Commençons par définir nos attributs. L’ID de média doit être un numéro de type et la valeur par défaut est 0. Cela facilite la comparaison. Et l’URL du média doit être une chaîne de type avec une chaîne vide par défaut.

attributes: {
    mediaId: {
        type: 'number',
        default: 0
    },
    mediaUrl: {
        type: 'string',
        default: ''
    }
},

Création du composant

Pour rendre notre code plus ordonné, nous définissons un composant séparé pour la fonction du bloc edit. Nous passerons plus tard ce composant à withSelectas pour l’envelopper autour de notre composant.

Dans le retour du composant, nous rendons un simple <div>pour le contenu du bloc. Je suppose que vous aurez ou aurez plus de contenu de bloc réel pour remplacer l’exemple de contenu factice. Nous rendons également InspectorControls(package wp.blockEditor) afin d’ajouter une section à l’inspecteur. Pour l’instant j’ajoute un vide PanelBodyà l’intérieur du InspectorControls. J’ajoute un <div>avec la même classe que la section d’images en vedette de WordPress. Cela garantit que notre style est beau. Plus tard, nous le remplirons PanelBodyavec le code de la fonctionnalité de sélection de média.

Mais d’abord, déstructurons le composant nécessaire au début du fichier :

const { InspectorControls } = wp.blockEditor;
const { PanelBody } = wp.components;
const { Fragment } = wp.element;

Au-dessus registerBlockType, je définis un composant simple appelé BlockEdit. Si vous préférez déplacer ceci dans un fichier séparé, vous pouvez le faire. C’est courant et recommandé, mais pour ce tutoriel, je garde les choses simples et je le garde dans le même fichier.

Maintenant, nous voulons rendre ce composant dans notre editfonction. Mais nous voulons l’envelopper dans un fichier withSelect.

Utilisation withSelectdans la editfonction

Si vous n’êtes pas familier avec withSelect, il s’agit d’un composant utile d’ordre supérieur qui nous permet d’effectuer des requêtes. Vous pouvez par exemple interroger les publications avec ceci. Nous utiliserons cependant la fonction select('core').getMedia()pour interroger l’ID du média. En réponse, nous recevrons un objet avec toutes les informations du média. L’objet multimédia que nous obtenons en réponse sera ensuite fourni comme accessoire dans notre BlockEditcomposant, prêt à l’emploi. Astucieux.

Nous nous assurons de n’interroger le média que si l’attribut d’ID de média est réellement défini sur autre chose que 0. Voici à quoi ressemblera notre fonction d’édition :

À la toute fin, après fermeture withSelectde la ligne, #3c’est là que nous demandons withSelectde retourner notre BlockEditcomposant. Avec cela, notre BlockEditcomposant a maintenant accès à props.media.

Rendu d’une sélection de média

Vient enfin la partie amusante: la partie dans l’inspecteur.

Le composant qui nous intéresse est MediaUpload(package wp.blockEditor). Si vous êtes intéressé, le repo WordPress Github pour Gutenberg contient de la documentation sur ce composant. Nous allons également envelopper ce composant dans un composant appelé MediaUploadCheck(package wp.blockEditor). Ce composant s’assure que l’utilisateur actuel a les capacités d’utiliser la bibliothèque multimédia, il est donc recommandé de l’utiliser.

Le MediaUploadcomposant a un accessoire requis : render. La façon dont ce composant fonctionne est que nous définissons une fonction pour le renderprop où nous rendons la sortie pour la "zone de téléchargement de médias". Dans notre cas, nous rendrons un Button(package wp.components). Dans le prop de rendu de MediaUpload, nous avons accès à la openfonction que nous pouvons appeler pour que WordPress ouvre la fenêtre contextuelle de la bibliothèque multimédia :

Il y a quelques autres accessoires disponibles pour MediaUpload. Nous couvrirons les éléments importants pour le rendre fonctionnel dans ce didacticiel, mais il y en a quelques autres avec lesquels vous pouvez jouer. Vous pourriez au moins être intéressé par le prop allowedTypesoù vous pouvez limiter les types de fichiers qu’il est possible de sélectionner dans la bibliothèque. Dans notre cas, nous l’avons configuré pour n’autoriser que les images.

Ajout de laMediaUpload

Déstructurez d’abord les nouveaux composants ;

const { Button } = wp.components;
const { MediaUpload, MediaUploadCheck } = wp.blockEditor;

Ajoutons MediaUploadChecket MediaUploadà l’intérieur de notre divdans notre PanelBody:

Le code ci-dessus déstructure openà l’intérieur de la fonction pour render. Nous rendons un simple Buttonoù sa onClickpropriété exécutera la openfonction. J’ai également ajouté les mêmes noms de classe que la fonctionnalité d’image en vedette de WordPress pour nous assurer que nous n’avons pas besoin d’ajouter de style.

À l’intérieur du Buttoncomposant, nous vérifions si une image a été définie ou non (attributes.mediaId). Si ce n’est pas le cas, nous faisons écho au texte « Choisissez une image ». Nous devrions maintenant avoir ceci dans notre bloc.

Lorsque vous cliquez sur le bouton, la fenêtre contextuelle de la bibliothèque multimédia doit apparaître. Cependant, la sélection d’une image ne fonctionne pas pour le moment, car il nous manque les accessoires onSelectet sur. Réglons cela maintenant. Nous définissons l’ID de média sélectionné et nous définissons pour exécuter une fonction que nous définirons plus tard dans notre composant.value``MediaUpload``value``onSelect

Définissons la onSelectMediafonction dans notre composant.

Gestion de la sélection des médias

Remarque: je définis mes fonctions comme des fonctions fléchées (onSelectMedia =() => { }). Les fonctions fléchées sont assez nouvelles dans ESNext et plutôt astucieuses. L’inconvénient est que l’utilisation des fonctions fléchées nécessite que vous ajoutiez la prise en charge de cela dans votre configuration Babel. Si vous ne l’avez pas encore fait, je vous recommande de regarder sous le titre "Configurer Babel" dans cet article.

Juste avant l’instruction return du composant, je définis une onSelectMediafonction. Tout ce dont nous avons besoin est de mettre à jour nos attributs en utilisant setAttributes(). En tant que paramètre, onSelectMedianous obtenons un objet multimédia. Nous extrayons simplement ce dont nous avons besoin de l’objet média. Dans notre cas, il s’agit de l’ID de média et de l’URL complète, qui sont respectivement les propriétés idet url.

Essayez-le maintenant et vous pourrez désormais sélectionner une image dans la médiathèque. Le média sélectionné est enregistré dans les attributs du bloc. Cependant, il n’y a pas encore de prévisualisation dans l’Inspecteur, et parce que vous avez sélectionné une image, le bouton de sélection d’une image disparaît. Le panneau est maintenant vide. L’étape suivante consiste à afficher l’aperçu chaque fois qu’une image a été sélectionnée, ainsi qu’à fournir des options pour la supprimer ou la modifier.

Rendu d’une image d’aperçu

À l’intérieur du Buttoncomposant, nous rendons à l’intérieur MediaUploadde la renderprop de nous écho un texte "Choisissez une image" si une image n’est pas encore définie. Mais nous devons ajouter du code lorsqu’une image est définie à l’intérieur ici ; un aperçu.

Pour nous aider à rendre un bel aperçu, nous utilisons le composant ResponsiveWrapper(package wp.components). Afin de ResponsiveWrapperfonctionner pleinement, nous devons fournir des accessoires pour la hauteur et la largeur. Nous avons également besoin de l’URL de la vignette. Il ne sert à rien d’utiliser l’URL complète (qui peut être gigantesque) pour afficher un aperçu dans l’inspecteur. C’est là qu’intervient l’accessoire withSelect. À l’intérieur du composant, nous rendons une simple <img>balise HTML.

On déstructure d’abord le composant nécessaire :

const { ResponsiveWrapper } = wp.components;

Comme vous pouvez le voir, nous accédons à l’accessoire withSelectfourni par le composant, props.media. Nous récupérons la largeur, la hauteur et l’URL de la taille de la vignette du média à partir de l’objet.

Vous devriez maintenant avoir un bel aperçu de l’image sélectionnée !

Parce que nous rendons l’image d’aperçu à l’intérieur, le fait Buttonde cliquer sur l’image d’aperçu déclenchera la Buttonfonction de onClick– qui consiste à ouvrir la médiathèque. De cette façon, vous pouvez déjà modifier l’image sélectionnée.

Il n’existe actuellement aucun moyen de supprimer ou de réinitialiser l’image sélectionnée. Réparons ça !

Ajout d’une fonction de suppression

Nous devrions à tout le moins offrir la possibilité à l’utilisateur de supprimer l’image sélectionnée. À partir de maintenant, une fois que vous avez sélectionné une image, vous pouvez uniquement la modifier, mais pas la supprimer.

Nous le ferons de la même manière que WordPress le fait pour l’image sélectionnée : un nouveau Buttonsous l’image d’aperçu (entièrement en dehors de son MediaUploadCheck). En fournissant quelques accessoires astucieux au Buttonnous le faisons ressembler à un lien (isLink) avec une couleur de texte rouge (isDestructive). Lisez la documentation de Button pour voir ce qui est possible d’autre. Nous enveloppons le bouton dans un autre MediaUploadCheck, juste pour nous assurer que l’utilisateur dispose des bonnes capacités.

Pour cet événement, nous Buttonexécutons onClickune nouvelle fonction dans notre composant: removeMedia(). Nous le définissons quelque part juste avant la fonction de retour du composant, comme nous l’avons fait avec onSelectMedia.

Cette fonction ne fait que réinitialiser nos deux valeurs d’attribut.

Nous aurons maintenant un joli lien clair pour supprimer l’image :

Lorsque vous cliquez sur le nouveau bouton, l’image sélectionnée et le bouton lui-même disparaissent, et le bouton de sélection d’une image réapparaît.

Ajout d’un bouton de remplacement

Cette étape est entièrement facultative. Comme mentionné précédemment, cliquer sur l’image d’aperçu de l’image ouvrira la bibliothèque multimédia et vous permettra de modifier l’image. Cependant, cela pourrait ne pas être aussi intuitif pour tout le monde à comprendre. WordPress ajoute un bouton séparé pour changer l’image, juste pour le rendre très clair. Nous pouvons faire la même chose.

Pour rendre un bouton de changement d’image, nous répétons essentiellement le code que nous avons pour sélectionner l’image: un autre MediaUploadcomposant. Nous fournissons la même fonction pour onSelect, allowedFileTypeset valuecomme précédemment. À l’intérieur de l’ renderaccessoire, MediaUploadnous en rendons simplement un autre Buttonqui ouvre la médiathèque. Plaçons ce bouton avant le bouton Supprimer – car cela a plus de sens pour l’utilisateur final :

Alors maintenant, vous devriez obtenir ceci :

Utilisation de l’image sélectionnée

À présent, il devrait être assez clair comment vous pouvez utiliser l’image sélectionnée. L’ID et l’URL du média sont stockés dans les attributs de votre bloc. Cependant, à titre d’exemple simple, j’inclurai du code qui définit l’image sélectionnée comme arrière-plan du bloc. Le code peut être fait exactement de la même manière dans les fonctions editet dans les save. Nous créons simplement un objet de style que nous appliquons sur la div d’habillage du bloc. Dans l’objet de style, nous définissons l’image d’arrière-plan sur l’URL du média.

Avec le reste de votre contenu de bloc personnalisé, cela pourrait facilement ressembler à ceci :

Si vous appliquez le style de bloc dans editet save, votre bloc devrait maintenant avoir le média sélectionné en arrière-plan. À la fois dans l’éditeur et dans le frontend.

Conclusion

La sélection d’une image (ou d’un fichier) dans la médiathèque est une fonction dont vous, en tant que développeur Gutenberg, aurez sans aucun doute besoin pour vos blocs. Nous avons appris à ajouter une fonction pour sélectionner une image de la médiathèque dans notre bloc Gutenberg personnalisé. Nous l’avons fait de la même manière que WordPress lui-même le fait pour l’image en vedette. (Edit mai 2020: WordPress a maintenant mis à jour l’image sélectionnée pour utiliser useSelect, le crochet React à la place). Cela garantit que notre code n’est pas "hack-ish" avec un risque élevé de rupture dans les futures mises à jour.

Faites-moi savoir si vous avez eu une utilisation de cela!

Code complet

Vous trouverez ci-dessous le code complet d’un bloc personnalisé qui présente la fonctionnalité de sélection de média. Et rien d’autre vraiment. Cette partie dépend de vous!