So fügen Sie eine Bildauswahl in Ihrem benutzerdefinierten WordPress-Gutenberg-Block hinzu

Dieser Beitrag richtet sich an Sie, die einen benutzerdefinierten Gutenberg-Block erstellen und eine Möglichkeit benötigen, ein Bild aus der Medienbibliothek auszuwählen oder hochzuladen. Die meisten anderen Feldtypen, wie z. B. Kontrollkästchen, Texteingaben oder Farbwähler, lassen sich ziemlich einfach hinzufügen, aber ein Medien-Uploader erfordert etwas mehr Code. Wir werden eine Inspector-Komponente erstellen, die für das Rendern einer Schaltfläche zum Öffnen der Medienbibliothek, zum Auswählen eines Bilds und zum optionalen Entfernen oder Ändern zu einem späteren Zeitpunkt verantwortlich ist. Alle verwenden Standard-WordPress-Komponenten.

Bevor wir in den Code eintauchen, denken Sie bitte daran, dass dieser Beitrag einige Gutenberg-Kenntnisse zum Schreiben benutzerdefinierter Blöcke erfordert. Wir werden uns nur auf den Medien-Uploader-Teil konzentrieren und nicht darauf, wie man sich registriert und einen Gutenberg-Block an sich erstellt. Wenn Sie sich nicht sicher sind, wie Sie einen benutzerdefinierten Gutenberg-Block schreiben, habe ich eine Tutorial-Serie, die genau dies behandelt:

Wenn das aus dem Weg ist, lass uns gleich eintauchen!

Was wir machen werden

Die Funktion „Medien auswählen” ist funktional genau die gleiche wie die Featured-Image-Funktion von WordPress. Wir werden innerhalb von Inspector ein Bedienfeld hinzufügen, das aus einer Schaltfläche zum Auswählen eines Bildes besteht.

Wenn Sie auf die Schaltfläche klicken, wird das Fenster „Medien auswählen oder hochladen” angezeigt, in dem Sie eine Datei aus der Medienbibliothek auswählen können. Wir beschränken die Medienbibliothek auf die Anzeige von Bildern. Sobald ein Bild ausgewählt ist, wird das Popup geschlossen und das Fenster zeigt eine Vorschau an kleine Miniaturansicht des ausgewählten Bildes. Darunter erscheinen die Vorschau-Buttons zum Ändern und Entfernen des Bildes. Genau wie beim Beitragsbild.

Dieses Tutorial geht davon aus, dass Sie das ausgewählte Bild als Hintergrund des Blocks verwenden – nur als Beispiel. Aus diesem Grund speichern wir die URL des Bildes. Ich füge ein Beispiel zur Verwendung des ausgewählten Bildes hinzu (sowohl in der als auch editin der saveFunktion). Wenn Sie ein Bild auswählen, erscheint das Bild als Hintergrund für unseren Block, sowohl im Editor als auch im Frontend.

Wir speichern die Medien-ID und die Medien-URL in den Attributen des Blocks. Der Code verwendet withSelect, eine im Paket bereitgestellte Komponente höherer Ordnung wp.data, um weitere Informationen zu den ausgewählten Medien nach ID abzufragen.

Ich „leihe” mir auch Klassennamen aus der WordPress-Featured-Image-Funktionalität, um sicherzustellen, dass alles gut aussieht und Sie kein CSS selbst schreiben müssen. Dies ist natürlich optional.

Speichern der ausgewählten Medien in Attributen

Was Sie in den Attributen Ihres Blocks speichern müssen, liegt ein wenig bei Ihnen. Als Minimum müssen wir natürlich die Medien-ID speichern. Dies kann ausreichen, wenn Sie die URL des Mediums nirgendwo im Skriptcode verwenden müssen. Zum Beispiel, wenn Sie ServerSideRenderwhere verwenden, ist PHP für das Rendern der Ausgabe des Blocks verantwortlich. In diesem Fall können Sie die Bild-URL beispielsweise einfach aus der Medien-ID abrufen [wp_get_attachment_image_src](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src/)(). Im folgenden Beispiel zeige ich jedoch ein einfaches Beispiel für die Anzeige des Bildes als Hintergrund für unseren Block, daher speichere ich auch die Medien-URL als Attribut. Wir werden das URL-Attribut sowohl in edit(um den Hintergrund im Editor hinzuzufügen) als auch in save(um den Hintergrund im Frontend hinzuzufügen) verwenden.

Beginnen wir mit der Definition unserer Attribute. Die Medien-ID sollte vom Typ Nummer und standardmäßig 0 sein. Dies erleichtert den Vergleich. Und die Medien-URL sollte vom Typ Zeichenfolge mit standardmäßiger leerer Zeichenfolge sein.

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

Erstellen der Komponente

Um unseren Code übersichtlicher zu gestalten, definieren wir eine separate Komponente für die editFunktion des Blocks. Wir werden diese Komponente später an übergeben withSelect, um sie um unsere Komponente zu wickeln.

In der Rückgabe der Komponente rendern wir ein einfaches <div>für den Blockinhalt. Ich nehme an, Sie werden oder haben aktuellere Blockinhalte, um den Dummy-Beispielinhalt zu ersetzen. Wir rendern auch InspectorControls(package wp.blockEditor), um dem Inspektor einen Abschnitt hinzuzufügen. Im Moment füge ich ein Leerzeichen PanelBodyin die InspectorControls. Ich füge ein <div>mit der gleichen Klasse hinzu, die der Abschnitt mit den vorgestellten Bildern von WordPress verwendet. Das sorgt dafür, dass unser Styling gut aussieht. Später werden wir dies PanelBodymit dem Code für die ausgewählten Medienfunktionen füllen.

Aber lassen Sie uns zuerst die notwendige Komponente am Anfang der Datei destrukturieren:

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

Oberhalb registerBlockTypedefiniere ich eine einfache Komponente namens BlockEdit. Wenn Sie dies lieber in eine separate Datei verschieben möchten, können Sie dies gerne tun. Dies ist üblich und wird empfohlen, aber für dieses Tutorial halte ich die Dinge einfach und behalte es in derselben Datei.

Nun wollen wir diese Komponente in unserer editFunktion rendern. Aber wir wollen es in eine withSelect.

Verwendung withSelectin der editFunktion

Wenn Sie mit nicht vertraut sind withSelect, handelt es sich um eine nützliche Komponente höherer Ordnung, mit der wir Abfragen durchführen können. Damit können Sie zum Beispiel Beiträge abfragen. Wir nutzen jedoch die Funktion select('core').getMedia()zur Abfrage der Media-ID. Als Antwort erhalten wir ein Objekt mit allen Medieninformationen. Das Medienobjekt, das wir als Antwort erhalten, wird dann als Requisite in unserer BlockEditKomponente bereitgestellt und kann sofort verwendet werden. Raffiniert.

Wir stellen sicher, dass die Medien nur dann abgefragt werden, wenn das Medien-ID-Attribut tatsächlich auf etwas anderes als 0 gesetzt ist. So sieht unsere Bearbeitungsfunktion aus:

Ganz am Ende, nach dem Schließen withSelectder Schlange #3, bitten wir um withSelectRückgabe unserer BlockEditKomponente. Damit hat unsere BlockEditKomponente nun Zugriff auf props.media.

Rendern einer Medienauswahl

Zum Schluss kommt der spaßige Teil: Der Teil im Inspektor.

Die Komponente, an der wir interessiert sind, ist MediaUpload(Paket wp.blockEditor). Wenn Sie interessiert sind, hat das WordPress Github Repo für Gutenberg eine Dokumentation zu dieser Komponente. Wir werden diese Komponente auch in eine Komponente namens MediaUploadCheck(package wp.blockEditor) packen. Diese Komponente stellt sicher, dass der aktuelle Benutzer die Möglichkeit hat, die Medienbibliothek zu verwenden, daher ist es empfehlenswert, dies zu verwenden.

Die MediaUploadKomponente hat eine erforderliche Requisite: render. Die Funktionsweise dieser Komponente besteht darin, dass wir eine Funktion für die renderRequisite definieren, in der wir die Ausgabe für den „Medien-Uploader-Bereich” rendern. In unserem Fall werden wir ein Button(Paket wp.components) rendern. Innerhalb der Render-Prop von MediaUpload erhalten wir Zugriff auf die openFunktion, die wir aufrufen können, damit WordPress das Popup der Medienbibliothek öffnet:

Es gibt ein paar weitere Requisiten für MediaUpload. Wir werden die wichtigsten behandeln, damit es in diesem Tutorial funktioniert, aber es gibt noch ein paar mehr, mit denen Sie spielen können. Sie könnten zumindest an der Requisite interessiert sein, mit der allowedTypesSie einschränken können, welche Dateitypen in der Bibliothek ausgewählt werden können. In unserem Fall haben wir es so eingestellt, dass nur Bilder zugelassen werden.

Hinzufügen derMediaUpload

Destrukturieren Sie zuerst die neuen Komponenten;

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

MediaUploadCheckLassen Sie uns und MediaUploadin unserem divin unserem hinzufügen PanelBody:

Der obige Code destrukturiert openinnerhalb der Funktion für render. Wir rendern ein einfaches, Buttondessen onClickEigenschaft die openFunktion ausführt. Ich habe auch die gleichen Klassennamen wie die Featured-Image-Funktionalität von WordPress hinzugefügt, um sicherzustellen, dass wir kein Styling hinzufügen müssen.

Innerhalb der ButtonKomponente prüfen wir, ob ein Bild gesetzt wurde (attributes.mediaId). Wenn dies nicht der Fall ist, wiederholen wir den Text „Wählen Sie ein Bild”. Das sollten wir jetzt in unseren Block bekommen.

Wenn Sie auf die Schaltfläche klicken, sollte das Popup-Fenster Medienbibliothek erscheinen. Die Auswahl eines Bildes funktioniert jedoch derzeit nicht, da uns die onSelectund valueRequisiten auf fehlen MediaUpload. Lassen Sie uns das jetzt beheben. Wir legen valuedie ausgewählte Medien-ID fest und legen fest onSelect, dass eine Funktion ausgeführt wird, die wir später in unserer Komponente definieren werden.

Lassen Sie uns die onSelectMediaFunktion innerhalb unserer Komponente definieren.

Umgang mit der Auswahl von Medien

Hinweis: Ich definiere meine Funktionen als Pfeilfunktionen (onSelectMedia =() => { }). Pfeilfunktionen sind ziemlich neu in ESNext und ziemlich raffiniert. Der Nachteil ist, dass Sie für die Verwendung von Pfeilfunktionen Unterstützung in Ihrer Babel-Konfiguration hinzufügen müssen. Wenn Sie dies noch nicht getan haben, empfehle ich Ihnen, in diesem Beitrag unter der Überschrift „Babel einrichten” nachzuschauen .

Unmittelbar vor der return-Anweisung der Komponente definiere ich eine onSelectMediaFunktion. Alles, was wir tun müssen, ist, unsere Attribute mit zu aktualisieren setAttributes(). Als Parameter onSelectMediaerhalten wir ein Medienobjekt. Wir extrahieren einfach das, was wir brauchen, aus dem Medienobjekt. In unserem Fall sind es die Medien-ID und die URL in voller Größe, die die Eigenschaften idbzw. urlsind.

Probieren Sie es jetzt aus und Sie können jetzt ein Bild aus der Medienbibliothek auswählen. Das ausgewählte Medium wird in den Attributen des Blocks gespeichert. Allerdings gibt es noch keine Vorschau davon im Inspektor, und weil Sie ein Bild ausgewählt haben, verschwindet die Schaltfläche zum Auswählen eines Bildes. Das Panel ist jetzt leer. Der nächste Schritt ist das Rendern der Vorschau, wenn ein Bild ausgewählt wurde, sowie das Bereitstellen von Optionen zum Entfernen oder Ändern.

Rendern eines Vorschaubildes

Innerhalb der ButtonKomponente, die wir innerhalb der Requisite von rendern MediaUpload, rendergeben wir einen Text „Choose an image” aus, wenn noch kein Bild festgelegt wurde. Aber wir müssen etwas Code hinzufügen, wenn hier ein Bild gesetzt wird; eine Vorschau.

Um uns beim Rendern einer schönen Vorschau zu helfen, verwenden wir die Komponente ResponsiveWrapper(Paket wp.components). Um ResponsiveWrappervoll funktionsfähig zu sein, müssen wir Requisiten für die Höhe und Breite bereitstellen. Wir benötigen auch die Thumbnail-URL. Es hat keinen Sinn, die vollständige URL (die gigantisch sein kann) zu verwenden, um eine Vorschau im Inspector zu rendern. Hier kommt die Stütze ins Spiel withSelect. Innerhalb der Komponente rendern wir ein einfaches <img>HTML-Tag.

Zuerst destrukturieren wir die notwendige Komponente:

const { ResponsiveWrapper } = wp.components;

Wie Sie sehen können, greifen wir auf die Requisite zu, die withSelectuns die Komponente bereitgestellt hat, props.media. Wir holen die Breite, Höhe und URL zur Thumbnail-Größe des Mediums aus dem Objekt.

Sie sollten jetzt eine schöne Vorschau des ausgewählten Bildes erhalten!

Da wir das Vorschaubild innerhalb des Vorschaubilds rendern, wird durch ButtonKlicken auf das Vorschaubild die Funktion von ausgelöst Button, onClickdie darin besteht, die Medienbibliothek zu öffnen. Auf diese Weise können Sie das ausgewählte Bild bereits ändern.

Derzeit gibt es keine Möglichkeit, das ausgewählte Bild zu entfernen oder zurückzusetzen. Lassen Sie uns das beheben!

Hinzufügen einer Entfernungsfunktion

Wir sollten dem Benutzer zumindest die Möglichkeit bieten, das ausgewählte Bild zu entfernen. Ab sofort können Sie ein einmal ausgewähltes Bild nur ändern, aber nicht entfernen.

Wir machen es genauso wie WordPress für das vorgestellte Bild: Ein neues Buttonunter dem Vorschaubild (ganz außerhalb seines MediaUploadCheck). Indem wir einige clevere Requisiten für den bereitstellen, Buttonlassen wir ihn wie einen Link (isLink) mit roter Textfarbe (isDestructive) aussehen. Lesen Sie die Dokumentation für Button, um zu sehen, was sonst noch möglich ist. Wir packen die Schaltfläche in eine weitere MediaUploadCheck, nur um sicherzustellen, dass der Benutzer über die richtigen Fähigkeiten verfügt.

Für dieses Ereignis führen wir eine neue Funktion in unserer Komponente aus Button:. Wir definieren es irgendwo direkt vor der Rückgabefunktion der Komponente, wie wir es mit getan haben .onClick``removeMedia()``onSelectMedia

Diese Funktion setzt lediglich unsere beiden Attributwerte zurück.

Wir haben jetzt einen schönen, klaren Link, um das Bild zu entfernen:

Wenn Sie auf die neue Schaltfläche klicken, verschwinden das ausgewählte Bild und die Schaltfläche selbst, und die Schaltfläche zum Auswählen eines Bildes wird wieder angezeigt.

Hinzufügen einer Ersetzen-Schaltfläche

Dieser Schritt ist vollkommen optional. Wie bereits erwähnt, wird durch Klicken auf das Vorschaubild des Bildes die Medienbibliothek geöffnet und Sie können das Bild ändern. Dies ist jedoch möglicherweise nicht für jeden so intuitiv verständlich. WordPress fügt eine separate Schaltfläche zum Ändern des Bildes hinzu, nur um es ganz klar zu machen. Das können wir auch.

Um eine Schaltfläche zum Ändern des Bildes zu rendern, wiederholen wir im Grunde den Code, den wir zum Auswählen des Bildes haben: eine andere MediaUploadKomponente. Wir bieten die gleiche Funktion für onSelect, allowedFileTypesund valuewie zuvor. Innerhalb der renderRequisite für MediaUploadrendern wir einfach eine andere Button, die die Medienbibliothek öffnet. Lassen Sie uns diese Schaltfläche vor der Schaltfläche Entfernen platzieren – da dies für den Endbenutzer sinnvoller ist:

Also jetzt solltest du das bekommen:

Verwenden des ausgewählten Bildes

Jetzt sollte ziemlich klar sein, wie Sie das ausgewählte Bild verwenden können. Sie haben die Medien-ID und die Medien-URL in den Attributen Ihres Blocks gespeichert. Als einfaches Beispiel werde ich jedoch einen Code einfügen, der das ausgewählte Bild als Hintergrund des Blocks festlegt. Der Code kann sowohl in den als auch in editden saveFunktionen genau gleich ausgeführt werden. Wir erstellen einfach ein Stilobjekt, das wir auf das Wrapping-Div des Blocks anwenden. Im Style-Objekt setzen wir das Hintergrundbild auf die Medien-URL.

Mit dem Rest Ihres benutzerdefinierten Blockinhalts könnte es leicht so aussehen:

Wenn Sie den Blockstil sowohl in als auch anwenden edit, savesollte Ihr Block jetzt die ausgewählten Medien als Hintergrund erhalten. Sowohl im Editor als auch im Frontend.

Fazit

Die Auswahl eines Bildes (oder einer Datei) aus der Medienbibliothek ist eine Funktion, die Sie als Gutenberg-Entwickler zweifellos für Ihre Blöcke benötigen werden. Wir haben gelernt, wie man eine Funktion zum Auswählen eines Bildes aus der Medienbibliothek in unserem benutzerdefinierten Gutenberg-Block hinzufügt. Wir haben es genauso gemacht wie WordPress selbst es für das vorgestellte Bild tut. (Bearbeiten Mai 2020: WordPress hat jetzt das vorgestellte Bild aktualisiert, um useSelectstattdessen, den React-Hook, zu verwenden). Dadurch wird sichergestellt, dass unser Code nicht „hack-isch” ist und ein hohes Risiko besteht, dass er in zukünftigen Updates beschädigt wird.

Lassen Sie mich wissen, ob Sie davon Gebrauch gemacht haben!

Vollständiger Code

Nachfolgend finden Sie den vollständigen Code für einen benutzerdefinierten Block, der die ausgewählte Medienfunktionalität bietet. Und eigentlich nichts anderes. Dieser Teil liegt bei Ihnen!