Come aggiungere un’immagine Seleziona nel blocco Gutenberg di WordPress personalizzato

Questo post è per te che stai creando un blocco Gutenberg personalizzato e hai bisogno di un modo per selezionare o caricare un’immagine dalla Libreria multimediale. La maggior parte degli altri tipi di campo, come caselle di controllo, input di testo o colorpicker, sono abbastanza facili da aggiungere, ma un caricatore multimediale richiede un po’ più di codice. Creeremo un componente Inspector che è responsabile del rendering di un pulsante per aprire il Catalogo multimediale, selezionare un’immagine e, facoltativamente, rimuoverla o modificarla in un secondo momento. Il tutto utilizzando componenti standard di WordPress.

Prima di approfondire il codice, tieni presente che questo post richiede alcune conoscenze di Gutenberg su come scrivere blocchi personalizzati. Ci concentreremo solo sulla parte dell’uploader multimediale e non su come registrarsi e creare un blocco Gutenberg in sé. Se non sei sicuro di come scrivere un blocco Gutenberg personalizzato, ho una serie di tutorial che copre esattamente questo:

Detto questo, tuffiamoci subito!

Cosa faremo

La funzione di selezione dei media sarà funzionalmente esattamente la stessa della funzione di immagine in primo piano di WordPress. All’interno di Inspector aggiungeremo un pannello che consiste in un pulsante per scegliere un’immagine.

Quando si fa clic sul pulsante, viene visualizzata la finestra "Seleziona o carica file multimediali" che consente di selezionare un file dal Catalogo multimediale. Limitiamo il Catalogo multimediale a mostrare solo le immagini. Una volta selezionata un’immagine, il popup si chiude e il pannello visualizza in anteprima un piccola miniatura dell’immagine selezionata. Sotto appariranno i pulsanti di anteprima per modificare e rimuovere l’immagine. Esattamente come con l’immagine in primo piano.

Questo tutorial presuppone che utilizzerai l’immagine selezionata come sfondo del blocco, solo come esempio. Questo è il motivo per cui memorizziamo l’URL dell’immagine. Includerò un esempio su come utilizzare l’immagine selezionata (sia nella funzione editche nella savefunzione). Quando si sceglie un’immagine, l’immagine apparirà come sfondo del nostro blocco, sia all’interno dell’editor che nel frontend.

Memorizziamo l’ID del supporto e l’URL del supporto negli attributi del blocco. Il codice utilizza withSelect, un componente di ordine superiore fornito nel wp.datapacchetto, per richiedere ulteriori informazioni sul supporto selezionato, in base all’ID.

Sto anche "prendendo in prestito" i nomi delle classi dalla funzionalità dell’immagine in primo piano di WordPress per assicurarmi che tutto appaia a posto e non sia necessario scrivere alcun CSS da soli. Questo è ovviamente facoltativo.

Salvataggio del supporto selezionato negli attributi

Quello che devi salvare negli attributi del tuo blocco dipende un po’ da te. Come minimo dobbiamo memorizzare l’ID del supporto, ovviamente. Questo potrebbe essere sufficiente se non è necessario utilizzare l’URL del supporto in un punto qualsiasi del codice dello script. Ad esempio, se utilizzi ServerSideRenderdove PHP è responsabile del rendering dell’output del blocco. In tal caso puoi facilmente ottenere l’URL dell’immagine dall’ID del supporto utilizzando ad esempio [wp_get_attachment_image_src](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src/)(). Tuttavia, nell’esempio seguente sto mostrando un semplice esempio di visualizzazione dell’immagine come sfondo del nostro blocco, quindi memorizzo anche l’URL multimediale come attributo. Useremo l’attributo URL sia in edit(per aggiungere lo sfondo nell’editor) che in save(per aggiungere lo sfondo nel frontend).

Iniziamo definendo i nostri attributi. L’ID supporto deve essere il numero del tipo e il valore predefinito è 0. Ciò semplifica il confronto. E l’URL del supporto dovrebbe essere di tipo string con una stringa vuota predefinita.

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

Creazione del componente

Per rendere il nostro codice più ordinato definiamo un componente separato per la editfunzione del blocco. In seguito passeremo questo componente withSelectper avvolgerlo attorno al nostro componente.

Nella restituzione del componente rendiamo semplice <div>per il contenuto del blocco. Presumo che avrai o avrai più contenuti di blocco effettivi per sostituire il contenuto di esempio fittizio. Eseguiamo anche il rendering InspectorControls(pacchetto wp.blockEditor) per aggiungere una sezione all’ispettore. Per ora aggiungo un vuoto PanelBodyall’interno del file InspectorControls. Aggiungo una <div>con la stessa classe utilizzata dalla sezione delle immagini in primo piano di WordPress. Questo assicura che il nostro stile abbia un bell’aspetto. In seguito lo riempiremo PanelBodycon il codice per la funzionalità del supporto selezionato.

Ma prima, destrutturamo il componente necessario all’inizio del file:

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

Sopra registerBlockTypedefinisco un semplice componente chiamato BlockEdit. Se preferisci spostarlo in un file separato, puoi farlo. Questo è comune e consigliato, ma per questo tutorial manterrò le cose semplici e lo tengo nello stesso file.

Ora vogliamo rendere questo componente nella nostra editfunzione. Ma vogliamo avvolgerlo in un withSelect.

Utilizzo withSelectnella editfunzione

Se non hai familiarità con withSelect, è un utile componente di ordine superiore che ci consente di eseguire query. Ad esempio, puoi interrogare i post con questo. Utilizzeremo tuttavia la funzione select('core').getMedia()per interrogare l’ID del supporto. Come risposta otterremo un oggetto con tutte le informazioni dei media. L’oggetto multimediale che otteniamo in risposta verrà quindi fornito come supporto nel nostro BlockEditcomponente, pronto per l’uso. Elegante.

Ci assicuriamo di interrogare il supporto solo se l’attributo ID supporto è effettivamente impostato su qualcosa di diverso da 0. Ecco come apparirà la nostra funzione di modifica:

Alla fine, dopo aver chiuso withSelectin fila, #3è dove chiediamo withSelectdi restituire il nostro BlockEditcomponente. Con questo il nostro BlockEditcomponente ora ha accesso a props.media.

Rendering di una selezione multimediale

Infine arriva la parte divertente: la parte nell’ispettore.

Il componente che ci interessa è MediaUpload(pacchetto wp.blockEditor). Se sei interessato, il repository Github di WordPress per Gutenberg ha della documentazione su questo componente. Avvolgeremo anche questo componente all’interno di un componente chiamato MediaUploadCheck(package wp.blockEditor). Questo componente si assicura che l’utente corrente disponga delle capacità per utilizzare il Catalogo multimediale, quindi è buona norma utilizzarlo.

Il MediaUploadcomponente ha un prop richiesto: render. Il modo in cui funziona questo componente è che definiamo una funzione per l’ oggetto di renderscena in cui eseguiamo il rendering dell’output per "l’area di caricamento multimediale". Nel nostro caso renderemo un Button(pacchetto wp.components). All’interno del supporto di rendering di MediaUpload otteniamo l’accesso alla openfunzione che possiamo chiamare per fare in modo che WordPress apra il popup della Libreria multimediale:

Sono disponibili altri oggetti di scena per MediaUpload. Tratteremo quelli importanti per renderlo funzionale in questo tutorial, ma ce ne sono altri con cui puoi giocare. Potresti almeno essere interessato al supporto allowedTypesin cui puoi limitare i tipi di file che è possibile selezionare nella Libreria. Nel nostro caso lo impostiamo per consentire solo le immagini.

Aggiungendo ilMediaUpload

Destrutturare prima i nuovi componenti;

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

Aggiungiamo MediaUploadChecke MediaUploaddentro il nostro divnel nostro PanelBody:

Il codice sopra destruttura openall’interno della funzione per render. Rendiamo semplice Buttondove la sua onClickproprietà eseguirà la openfunzione. Ho anche aggiunto gli stessi nomi di classe della funzionalità dell’immagine in primo piano di WordPress per assicurarci di non dover aggiungere alcuno stile.

All’interno del Buttoncomponente controlliamo se è stata impostata o meno un’immagine (attributes.mediaId). In caso contrario, facciamo eco al testo "Scegli un’immagine". Ora dovremmo averlo nel nostro blocco.

Quando si fa clic sul pulsante, dovrebbe apparire il popup Catalogo multimediale. Tuttavia, la selezione di un’immagine non funziona al momento, perché ci mancano gli oggetti di scena onSelecte su. Risolviamolo ora. Impostiamo l’ID del supporto selezionato e impostiamo l’esecuzione di una funzione che definiremo in seguito all’interno del nostro componente.value``MediaUpload``value``onSelect

Definiamo la onSelectMediafunzione all’interno del nostro componente.

Gestione della selezione dei media

Nota: sto definendo le mie funzioni come funzioni freccia (onSelectMedia =() => { }). Le funzioni delle frecce sono piuttosto nuove in ESNext e piuttosto eleganti. Lo svantaggio è che l’utilizzo delle funzioni freccia richiede l’aggiunta del supporto per questo nella configurazione di Babel. Se non l’hai fatto, ti consiglio di guardare sotto il titolo "Impostazione di Babel" in questo post.

Subito prima dell’istruzione di ritorno del componente definisco una onSelectMediafunzione. Tutto quello che dobbiamo fare è aggiornare i nostri attributi usando setAttributes(). Come parametro onSelectMediaotteniamo un oggetto multimediale. Estraiamo semplicemente ciò di cui abbiamo bisogno dall’oggetto multimediale. Nel nostro caso sono l’ID del supporto e l’URL a grandezza naturale, che sono rispettivamente le proprietà ide url.

Provalo ora e ora sarai in grado di selezionare un’immagine dalla Libreria multimediale. Il supporto selezionato viene salvato negli attributi del blocco. Tuttavia non c’è ancora un’anteprima nell’Inspector e poiché hai selezionato un’immagine il pulsante per selezionare un’immagine scompare. Il pannello ora è vuoto. Il passaggio successivo è il rendering dell’anteprima ogni volta che è stata selezionata un’immagine, oltre a fornire le opzioni per rimuoverla o modificarla.

Rendering di un’immagine di anteprima

All’interno del Buttoncomponente che renderizziamo all’interno MediaUploaddel renderprop di ‘ echeggiamo un testo "Scegli un’immagine" se un’immagine non è ancora impostata. Ma abbiamo bisogno di aggiungere del codice per quando un’immagine è impostata all’interno qui; un’anteprima.

Per aiutarci a rendere una bella anteprima utilizziamo il componente ResponsiveWrapper(pacchetto wp.components). Al fine di ResponsiveWrapperfunzionare completamente, dobbiamo fornire puntelli per l’altezza e la larghezza. Abbiamo anche bisogno dell’URL della miniatura. Non ha senso usare l’URL completo (che può essere gigantesco) per eseguire il rendering di un’anteprima all’interno dell’Inspector. È qui che withSelectentra in gioco il sostegno. All’interno del componente eseguiamo il rendering di un semplice <img>tag HTML.

Per prima cosa destrutturiamo il componente necessario:

const { ResponsiveWrapper } = wp.components;

Come puoi vedere accediamo all’elica che il withSelectcomponente ci ha fornito, props.media. Recuperiamo la larghezza, l’altezza e l’URL in base alle dimensioni della miniatura del supporto dall’oggetto.

Ora dovresti ottenere una bella anteprima dell’immagine selezionata!

Poiché eseguiamo il rendering dell’immagine di anteprima all’interno del Buttonclic sull’immagine di anteprima si attiverà la funzione Buttondi ‘ onClick, che è quella di aprire il Catalogo multimediale. In questo modo puoi già modificare l’immagine selezionata.

Al momento non è possibile rimuovere o ripristinare l’immagine selezionata. Risolviamolo!

Aggiunta di una funzione di rimozione

Dovremmo almeno offrire all’utente la possibilità di rimuovere l’immagine selezionata. A partire da ora, una volta selezionata un’immagine, puoi solo cambiarla, ma non rimuoverla.

Lo faremo come fa WordPress per l’immagine in primo piano: una nuova Buttonimmagine sotto l’anteprima (interamente al di fuori del suo MediaUploadCheck). Fornendo alcuni oggetti di scena intelligenti, lo Buttonfacciamo sembrare un collegamento (isLink) con il colore del testo rosso (isDestructive). Leggi la documentazione per Button per vedere cos’altro è possibile. Avvolgiamo il pulsante all’interno dell’ennesimo MediaUploadCheck, solo per garantire che l’utente abbia le giuste capacità.

Per questo evento eseguiamo una nuova funzione all’interno del nostro componente Button:. Lo definiamo da qualche parte subito prima della funzione di ritorno del componente, come abbiamo fatto con .onClick``removeMedia()``onSelectMedia

Tutto ciò che fa questa funzione è ripristinare i nostri due valori di attributo.

Ora avremo un link carino e chiaro per rimuovere l’immagine:

Quando si fa clic sul nuovo pulsante, l’immagine selezionata e il pulsante stesso scompaiono e viene visualizzato nuovamente il pulsante per la selezione di un’immagine.

Aggiunta di un pulsante di sostituzione

Questo passaggio è completamente facoltativo. Come accennato in precedenza, facendo clic sull’immagine di anteprima dell’immagine si aprirà la Libreria multimediale e ti consentirà di modificare l’immagine. Tuttavia questo potrebbe non essere così intuitivo da capire per tutti. WordPress aggiunge un pulsante separato per modificare l’immagine, solo per renderlo molto chiaro. Possiamo fare lo stesso.

Per rendere un pulsante cambia immagine ripetiamo sostanzialmente il codice che abbiamo per selezionare l’immagine: un altro MediaUploadcomponente. Forniamo la stessa funzione per e onSelectcome prima. All’interno dell’oggetto di scena ne realizziamo semplicemente un altro che apre la Libreria multimediale. Mettiamo questo pulsante prima del pulsante Rimuovi, poiché ha più senso per l’utente finale:allowedFileTypes``value``render``MediaUpload``Button

Quindi ora dovresti ottenere questo:

Utilizzando l’immagine selezionata

A questo punto dovrebbe essere abbastanza chiaro come utilizzare l’immagine selezionata. Hai l’ID media e l’URL media memorizzati negli attributi del tuo blocco. Tuttavia, come semplice esempio includerò del codice che imposta l’immagine selezionata come sfondo del blocco. Il codice può essere eseguito esattamente allo stesso modo in entrambe editle savefunzioni e. Creiamo semplicemente un oggetto di stile che applichiamo sul div di wrapping del blocco. Nell’oggetto di stile impostiamo l’immagine di sfondo sull’URL del media.

Con il resto del contenuto del tuo blocco personalizzato potrebbe facilmente assomigliare a questo:

Se applichi lo stile del blocco in entrambi edite save, il tuo blocco dovrebbe ora avere il supporto selezionato come sfondo. Sia all’interno dell’editor che nel frontend.

Conclusione

La selezione di un’immagine (o file) dalla Libreria multimediale è una funzione di cui senza dubbio tu, come sviluppatore Gutenberg, avrai bisogno per i tuoi blocchi. Abbiamo imparato come aggiungere una funzione per selezionare un’immagine dalla Libreria multimediale nel nostro blocco Gutenberg personalizzato. L’abbiamo fatto allo stesso modo in cui lo stesso WordPress lo fa per l’immagine in primo piano. (Modifica maggio 2020: WordPress ha ora aggiornato l’immagine in primo piano da utilizzare useSelect, invece l’hook React). Questo assicura che il nostro codice non sia "hack-ish" con un alto rischio di violazione degli aggiornamenti futuri.

Fammi sapere se l’hai usato in qualche modo!

Codice completo

Di seguito è riportato il codice completo per un blocco personalizzato che presenta la funzionalità di selezione del supporto. E nient’altro davvero. Quella parte dipende da te!