Oletko koskaan joutunut tilanteeseen, jossa haluat lisätä mukautetut asetuksesi WordPressin Gutenberg-lohkoihin? Tässä viestissä käymme yksityiskohtaisesti kuinka se tehdään. Löydät kaksi esimerkkikoodia tosielämän käyttötapauksista, joissa mukautettuja asetuksia lisätään WordPressin lohkoihin.
Muista, että koska Gutenberg-lohkot ovat Javascriptiä, niiden muokkaaminen edellyttää koodin kirjoittamista Javascriptillä. Aivan kuten WordPressin PHP-koodissa on koukkuja ja suodattimia, joiden avulla teeman tai laajennuksen kehittäjät voivat muokata sen koodia, myös WordPressin Javascript-koodissa on suodattimia. PHP:n [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)()funktion tapaan meillä on Javascript-toiminto [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().
Kirjoitan koodin Javascript ES6 -syntaksilla, joka vaatii kääntäjän sen muuttamiseksi. Voit kirjoittaa ES5-syntaksilla, mutta suosittelen käyttämään ES6/ESNextiä. Minulla on viesti, joka selittää muuntajan asettamisen ES6/ESNextille. Oletan myös, että sinulla on jonkin verran kokemusta React/JSX:stä, mahdollisesti kokemusta omien mukautettujen Gutenberg-lohkojen luomisesta.
Mitä voit suodattaa Gutenberg-lohkoilla
Saatavilla olevissa Gutenberg-koukuissa ja -suodattimissa ei ole paljon dokumentaatiota. Mutta tarkoitus on lisätä mukautettuja asetuksia ja jollakin tavalla soveltaa niitä olemassa oleviin lohkoihin; tämän olen löytänyt tähän mennessä. Olen keskittynyt yksinkertaisten asetusten lisäämiseen – en toimintoihin, jotka edellyttävät rajuja komponenttien muutoksia tai monimutkaista käyttäytymistä.
Mukautettujen asetusten lisääminen olemassa oleviin lohkoihin on kolme vaihetta:
- Lisäämme suodattimen olemassa olevan lohkon
[registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)asetustaulukkoon. Näin voimme lisätä uusia attribuuttejaattributestaulukkoon, jolloin voimme tallentaa lisätietoa lohkoon. Meidän on tallennettava mukautettu asetus jonnekin. - Kiinnitä lohkon
editkomponentti (komponentti, joka vastaa lohkon hahmontamisesta editorissa). Tässä koukussa voimme kiinnittää Inspectoriin (sivupalkkiin) ja lisätä omia komponenttejamme. Voimme joko lisätä uuden osion/paneelin tai kytkeytyä "Advanced"-osioon, joka on aina läsnä kaikissa lohkoissa. Sitten on meidän tehtävämme renderöidä asetussyötteet, kuten tekstisyötteet, valintaruudut tai mitä muuta. - Suodata lohkon
saverekvisiitta. Voimme säätää tallennuksen rekvisiitta, joka vastaa sekä lohkon tallentamisesta että sen renderöimisestä käyttöliittymässä (editorin ulkopuolella). Meidän tapauksessamme haluamme lisätä luokan tai rivin tyylin.
Voimme kohdistaa tiettyihin lohkoihin tai kaikkiin. Meillä on aina pääsy siihen, minkä tyyppisessä lohkossa olemme.
Toisin sanoen: Lisäämme joitain mukautettuja asetuksia Inspectoriin ja tallennamme ne mukautetuiksi määritteiksi, jotka olemme lisänneet lohkoon. Voimme sitten vaikuttaa lohkon luokan nimeen tai rivin tyyliin (joissain tapauksissa) tallennettujen attribuuttien mukaan. Mukautettujen luokkanimien avulla voimme helposti lisätä mukautettuja CSS-syötteitä, jotka visuaalisesti antavat asetuksillemme tehosteen.
Mitä emme voi tehdä (toistaiseksi?)
Valitettavasti joitakin asioita emme voi käyttää olemassa olevien lohkojen suodattimilla. Mitä tulee yksinkertaisten mukautettujen asetusten lisäämiseen lohkoihin, nämä ovat yleisiä asioita, joihin emme voi vaikuttaa.
Ei pääsyä lohkon rivityyliin editorin sisällä
Tapauksissa, joissa asetukset vaikuttavat lohkon suunnitteluun, meidän on lisättävä rivin tyyli lohkon rivityssolmuun. Pelkkä luokan nimi ei kelpaa. Jos esimerkiksi lisäät mukautetun väriasetuksen ja käyttäjä valitsee mukautetun värin (colorpickeristä), et voi ratkaista tätä lisäämällä luokkaa – tarvitset sisäänrakennetun tyylin.
Valitettavasti näyttää siltä, että WordPressin oletuslohkot käsittelevät tekstin sisäistä tyyliä editorissa täysin itsenäisesti ilman suodatus- tai "kiinnitysvaihtoehtoa". Näytän tavan kiertää tämä alla olevassa viimeisessä esimerkissä, mutta se ei ole ihanteellinen kaikissa tapauksissa.
Miksi välittää siitä, että lohko näyttää erilaiselta editorissa verrattuna käyttöliittymään, saatat kysyä? Gutenbergin koko idea on toteuttaa visuaalinen tapa muokata sisältöä, jossa se, mitä näemme, on todella sitä, mitä saamme. Haluamme saavuttaa saman visuaalisen ilmeen sekä editorissa että käyttöliittymässä.
Jotkut lohkot eivät sisällä luokan nimeä editorissa
Kuten edellä mainittiin, voimme suodattaa lohkon rivitysluokan nimen, koska tämä on rekvisiitta, joka välitetään kaikille Gutenberg-lohkoille. Mutta valitettavasti on joitain lohkoja, jotka eivät käytä lohkon luokkaa ollenkaan edit. Yksi esimerkki on kansilohko. Olen pelannut paljon käyttämällä Cover-lohkoja etusivujen "osioina" ja törmännyt jatkuvasti ongelmiin, koska Cover-lohko rakentaa oman luokkansa sisään edit. Se ohittaa kokonaan mukaan lukien lohkon "globaalin" luokan (johon meillä on pääsy suodattimien kautta).
Mutta ainakin voimme olla varmoja siitä, että suodatettuja luokkien nimiä käytetään aina save(frontend). Tämä tapahtuu automaattisesti kunkin lohkon koodin ulkopuolella.
Jos olen väärässä jonkin edellä mainitun suhteen, ilmoita minulle alla olevissa kommenteissa! Opin jatkuvasti Gutenbergiä, ja samalla myös Gutenberg kehittyy. Toivon, että jossain vaiheessa yllä oleva on mahdollista jossain vaiheessa tai että se on mahdollista, mutta minulta puuttuu vain olennainen tieto!
Kun se on poissa tieltä, aletaan tutkia jotain koodia.
Esimerkki 1: Lisää vaihtokenttä piilottaaksesi kansilohkon mobiililaitteessa
Oletetaan, että kehitämme teemaa, jossa kansilohkoja käytetään etusivun "osioissa". Ja haluamme tarjota käyttäjälle mahdollisuuden piilottaa tietty osio mobiilista. Tämän ratkaisemiseksi voimme lisätä vaihtokentän "Lisäasetukset"-osioon Cover block’s Inspectorissa. Jos kenttä on päällä, Cover-lohko saa ylimääräisen mukautetun luokan, johon voimme kohdistaa CSS- ja mediakyselyillä.
Muuten: Tämä on tapaus, jossa ongelma Cover-lohkosta, joka ei käytä mukautettuja luokkanimiämme editorissa, on itse asiassa etu! Kuvittele, jos olisi; silloin käyttäjän olisi mahdotonta muokata lohkoa editorissa, jos hänellä on pieni näyttö!
Kuten aiemmin mainittiin, meidän on koodattava kolme vaihetta. Meidän on myös lisättävä jonkin verran PHP:tä jonoon Javascript-tiedostomme editoriin. Tehdään se ensin.
Lisäämme skriptimme editoriin
Yhdistämme toimintaan funktion [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Toimintomme sisällä laitamme skriptin jonoon, aivan kuten tavallisesti teemme wp_enqueue_scriptshookissa.
add_action('enqueue_block_editor_assets', function() {
wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});Muista säätää polku siihen, missä skripti on! Huomautus: Jos kirjoitat ES6:ssa webpackilla, joka kääntää Javascriptiä, muista asettaa skriptin koontipolku, ei lähdettä.
Haluan lisätä wp-edit-postkomentosarjan riippuvuudeksi merkin, jotta se latautuu riittävän myöhään.
Siinä kaikki PHP, joka meidän on tehtävä. Loput on kirjoitettu Javascript-tiedostoomme.
Lisää mukautettu attribuutti
Ensimmäinen suodatin, jota käytämme, on blocks.registerBlockTypesuodattimen registerBlockTypeasetusobjekti.
Mutta ensin vähän suodattimien lisäämisestä Javascriptiin. Koska en ole löytänyt tälle mitään hyvää dokumentaatiota, selitän sitä hieman tässä. Funktio addFilteron wp.hooksnimiavaruudessa ja hyväksyy neljä argumenttia.
addFilter('hookName', 'namespace', 'functionName', 'priority');
Ensimmäinen parametri ‘hookName’ on sen suodattimen nimi, johon haluamme liittää. Tämä vastaa ensimmäistä parametria PHP:tä käytettäessä add_filter(). Toinen parametri, ‘nimiavaruus’, on mukautettu nimiavaruus koodillesi. Tämä on vain nimien törmäyksen välttämiseksi. Voit asettaa täällä melkein mitä tahansa, älä vain käytä WordPressin nimiavaruutta (‘wp’). Käytä nimesi tai projektin nimen lyhyttä muotoa. Kolmas parametri, ‘functionName’, on koukussa oleva funktio – joka on sama kuin PHP: add_filter()n toinen argumentti. Ja lopuksi neljäs parametri, ‘priority’, on valinnainen. Tämä on jälleen sama kuin PHP: add_filter()n kolmas argumentti.
Suodattimien prosessi Javascriptissä on sama kuin PHP:ssä. Määrittelemme funktion, jonka on palautettava suodatettu muuttuja. Joskus muuttuja on merkkijono, objekti tai komponentti. Muokkaamme muuttujaa funktion sisällä parhaaksi katsomallamme tavalla.
Meidän tapauksessamme haluamme lisätä uuden attribuutin lohkon attributeobjektiin. Kutsumme uutta attribuuttia hideOnMobileja asetamme sen tyypiksi boolean. Tämä tehdään näin:
function addCoverAttribute(settings, name) {
if (typeof settings.attributes !== 'undefined') {
if (name == 'core/cover') {
settings.attributes = Object.assign(settings.attributes, {
hideOnMobile: {
type: 'boolean',
}
});
}
}
return settings;
}
wp.hooks.addFilter(
'blocks.registerBlockType',
'awp/cover-custom-attribute',
addCoverAttribute
);Kohdistamme rivillä #3vain tyyppisiä lohkoja core/cover. Toinen blocks.registerBlockTypesuodatusargumentti on sopivasti lohkon nimi. Sitten lisäämme objektiin uuden settings.attributesobjektikohteen. Lopuksi varmistamme, että palautamme suodatetun muuttujan, settings.
Tässä vaiheessa Gutenbergissä visuaalisesti mikään ei muutu. Mutta kaikilla Cover-lohkoilla on nyt lisäattribuutti, jota voimme käyttää asetuksemme tallentamiseen.
Lisää asetus Inspectoriin (Lisäasetukset-paneeli)
Toista suodatinta kutsutaan editor.BlockEditja se suodattaa lohkon editkomponentin. Tämä suodatin vastaanottaa alkuperäisen lohkon BlockEditkomponentin ja palauttaa uuden paketoidun komponentin. Meidän on käytettävä wp.compose.createHigherOrderComponentkäärityn osan palauttamiseksi.
Komponenttimme sisällä varmistamme, että renderöimme kääritty komponentti BlockEditsiitä huolimatta. Mutta jos lohko on tyyppiä Cover, kiinnitämme myös komponenttiin InspectorAdvancedControls(joka on Inspectorin "Advanced"-paneeli) ja lisäämme ToggleControl. Kirjoitamme ToggleControlosoittamaan aiemmin lisäämämme mukautetun attribuutin arvon ja päivittämään sitä hideOnMobile.
Muista aina palauttaa alkuperäinen BlockEdit, minkä teemme linjalla #9. Rivillä #10 tarkistamme, onko lohkon tyyppi Cover, ja renderöimme InspectorAdvancedControlskomponentin. Lisäämme tähän sisään ToggleControl, joka on syöttösäädin, joka näkyy vaihtajana tosi tai epätosi välillä. Asetamme tunnisteen ja yhdistämme sen arvon hideOnMobilemääritteeseen. Jos olet lisännyt asetuksia Inspectoriin aiemmin, tämän pitäisi olla sinulle melko suoraviivaista.
Yllä olevalla koodilla meidän pitäisi nyt saada tämä "Lisäasetukset"-paneeliin Inspector on Cover blocksissa:
Syöte päivittää nyt mukautetun määritteen hideOnMobile. Viimeinen vaihe on tehdä jotain tämän attribuutin arvosta riippuen. Tällä hetkellä määrite on tallennettu, mutta se ei vaikuta varsinaisesti mihinkään.
Lisää mukautettu luokka
Viimeinen vaihe on mukautetun luokan lisääminen lohkon luokkaan. Teemme tämän suodattimen kanssa blocks.getSaveContent.extraProps. Tämä suodatin vaikuttaa lohkon savekomponentin tukiin. Yksi niistä on prop className, jota käytetään aina käyttöliittymässä. Lisäämme mukautetun luokkamme sen jälkeen, jos määrite oli true, ja palautamme sen sitten. Olen päättänyt lisätä luokan " hide-on-mobile", mutta voit kutsua sitä miksi haluat.
Tämä koodi on melko itsestään selvä. Rivillä #4tarkistamme, onko attribuutti hideOnMobileolemassa ja onko se true. Jos näin on, lisäämme classNamemerkkijonoon mukautetun luokan.
Kaikilla yllä olevilla kolmella suodattimella meidän pitäisi nyt saada mukautettu luokka "piilota matkapuhelimessa" Cover-lohkoon aina, kun asetus otetaan käyttöön.
Jäljelle jää vain CSS:n lisääminen teemasi käyttöliittymän tyylitaulukkoon. Jotain tällaista;
.wp-block-cover.hide-on-mobile { display: none; }
@media (min-width: 480px) {
.wp-block-cover.hide-on-mobile { display: block; }
}Esimerkki 2: Lisää Inspector-paneeli mukautetulla taustaväriasetuksella välikappaleelle
Toisessa käyttötapauksessa haluamme lisätä mukautettuja väriasetuksia Spacer-lohkoon. Spacer-lohkolla ei ole oletuksena muita asetuksia kuin sen korkeus. Oletetaan, että haluamme lisätä taustavärin, joka värittää välikappaleen täyden korkeuden. Näin käyttäjä voi lisätä tyhjiä, värillisiä "raitoja" sisältöönsä. Tässä tapauksessa haluamme lisätä väriasetukset omaan erilliseen paneeliinsa Inspectorissa tavallisen väriasetusten odotetun käyttäytymisen mukaisesti.
Huomautus: Värien käsittely on hieman monimutkaisempaa, koska meidän on käytettävä (toista) korkeamman asteen komponenttia withColors. Koska meidän on jo otettava käyttöön korkeamman asteen komponentti, editor.BlockEditmeidän on lisättävä composeuseita komponentteja. Lisäksi jokaiselle väriasetukselle on lisättävä kaksi attribuuttia. Yksi sisältää väripaletin slug ja toinen sisältää hex värikoodi – vain jos käyttäjä on valinnut mukautetun värin (käytti värivalitsin). Tämä kaikki on yleistä, kun työskentelet withColors. Minulla on <a href="https://wordpress.mediadoma.com/fi/kuinka-lisaetae-vaeriasetuksia-mukautettuun-gutenberg-lohkoon/" title="viesti, joka selittää väriasetusten lisäämisen ja withColorsyksityiskohtaisesti,” >viesti, joka selittää väriasetusten lisäämisen ja withColorsyksityiskohtaisesti, jos olet hämmentynyt.
Toiseksi törmäämme tässä tapauksessa edellä selostettuun asiaan; jossa emme voi lisätä sopivaa sisäistä tyyliä editoriin. Ratkaisu, jonka olen valinnut tässä tapauksessa, on kääriä välikappale diveditorissa a:n sisään ja soveltaa rivitykseen oikeita luokkia ja rivityyliä div. Tämä tekee valitusta väristä näkyvän editorissa, kun lohkoa ei ole valittu. Lohkon valinnan jälkeen WordPress lisää kuitenkin oman mukautetun vaaleanharmaan taustansa lohkoon peittäen mukautetun taustavärimme. Yksi CSS editorille korjaa tämän. Selitän lisää lopussa.
Vaiheet ovat samat kuin yllä olevassa esimerkissä. Asetamme skriptimme ensin editoriin PHP:llä. Sitten Javascriptissä attributessuodatamme objektin, Spacerin editkomponentin ja lopuksi Spacerin savekomponentin.
Lisäämme skriptimme editoriin
Yhdistämme toimintaan funktion [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Toimintomme sisällä laitamme skriptin jonoon, aivan kuten tavallisesti teemme wp_enqueue_scriptshookissa.
add_action('enqueue_block_editor_assets', function() {
wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});Muista säätää polku skriptiisi. Haluan lisätä wp-edit-postkomentosarjan riippuvuudeksi merkin, jotta se latautuu riittävän myöhään.
Siinä kaikki PHP, joka meidän on tehtävä. Loput on kirjoitettu Javascript-tiedostoomme.
Lisää mukautettuja määritteitä
Kuten yllä olevassa esimerkissä, lisäämme suodattimen blocks.registerBlockType, jotta voimme lisätä objektikohteita lohkon attributesobjektiin.
Kun työskentelemme kanssa, withColorsmeidän on lisättävä kaksi attribuuttia jokaiselle värille. Taustavärimääritteemme nimi on backgroundColor, mikä tarkoittaa, että toinen määrite on nimettävä customBackgroundColor. Tämä kaikki on selitetty viestissäni väriasetusten käsittelystä Gutenbergissä. Molempien tulee olla merkkijonotyyppiä, ja niitä tulee soveltaa vain välikappaleen tyyppisiin lohkoihin.
function addSpacerAttributes(settings, name) {
if (typeof settings.attributes !== 'undefined') {
if (name == 'core/spacer') {
settings.attributes = Object.assign(settings.attributes, {
backgroundColor: {
type: 'string',
},
customBackgroundColor: {
type: 'string'
}
});
}
}
return settings;
}
wp.hooks.addFilter(
'blocks.registerBlockType',
'awp/spacer-background-attribute',
addSpacerAttributes
);Lisää ColorSettings-paneeli Inspectoriin
Toinen vaihe on väriasetuspaneelin lisääminen Inspector for the Spacer -lohkoon suodattamalla editor.BlockEdit.
Meidän on käytettävä composeyhdistämään tästä suodattimesta palautettu korkeamman asteen komponentti ja withColors. Toisin sanoen yksinkertaisesti käärimme palautetun komponentin withColors. Parametrina withColorsannamme attribuuttimme backgroundColor.
Käärityn komponentin sisällä varmistamme, että palaamme aina BlockEdit(linja #9ja #39välikappaleille). Spacer-tyyppisille lohkoille kiinnitämme myös koukun InspectorControlslisätäksemme PanelColorSettingsvärivalintaamme. Tämä on vakiomenettely väriasetusten lisäämiseksi.
Linjalla #17 - 34luomme manuaalisesti tarvittavan luokan ja/tai rivin tyylin. Sitten riville #38lisäämme rivitysdiv BlockEdit:n näiden luokkien ja sisäisten tyylien kanssa.
Tuloksena on uusi väriasetuspaneeli Inspector for Spacer blocksissa, täysin toimiva.
Paletin värin tai mukautetun värin valinta vaikuttaa todellakin editorin sisällä olevaan kääre-div. Mutta näet sen vain, kun poistat välikappaleen valinnan!
Tämä johtuu siitä, että WordPress käyttää omaa tyyliään valitessaan välikappaletta. Korjaamme sen lopussa, ensin tarvitsee vain käyttää samaa luokkaa ja/tai sisäistä tyyliä myös käyttöliittymässä.
Lisää mukautettu luokka ja upotettu tyyli tallentaaksesi
Lopuksi meidän on suodatettava blocks.getSaveContent.extraPropsja käytettävä tarvittavaa luokkaa ja/tai sisäistä tyyliä käyttöliittymälle. Tämä on jälleen hyvin samanlainen kuin mitä teimme yllä olevassa esimerkissä 1. Jos valittiin paletin väri, meidän on lisättävä luokan nimi, joka noudattaa WordPressin väriasetusstandardeja (” has-<PALETTESLUG>-background-color“). Jos valittiin mukautettu väri, meidän on lisättävä sisäänrakennettu tyyli hex-värillä.
Huomautus: Jos joudut käsittelemään luokkien nimiä paljon, suosittelen classnameskirjaston tuomista. Tätä käytetään voimakkaasti Gutenbergissä, koska se yksinkertaistaa oikeiden luokkanimien asettamista paljon. Alla oleva koodi olettaa, että et ole, ja muodostaa luokan nimen manuaalisesti.
function applySpacerBackground(props, blockType, attributes) {
if (blockType.name == 'core/spacer') {
const { backgroundColor, customBackgroundColor } = attributes;
// For improved class name handling, use classnames library. Or do it manually like..
let className = (props.className != undefined)? props.className: '';
if (backgroundColor != undefined) {
className += ' has-' + backgroundColor + '-background-color';
}
props.className = className;
if (customBackgroundColor != undefined) {
Object.assign(props, { style: { ...props.style, backgroundColor: customBackgroundColor }});
}
}
return props;
}
wp.hooks.addFilter(
'blocks.getSaveContent.extraProps',
'awp/spacer-apply-class',
applySpacerBackground
);Yllä olevalla koodilla käyttöliittymä renderöi nyt täydellisesti Spacer-lohkot mukautetulla värivalinnallamme!
Lopullinen (valinnainen) korjaus on lisätä CSS:ää editoriin. Sinun on lisättävä joko upotettu CSS tai muokkaustyylitaulukko. Voit esimerkiksi asettaa tyylitaulukon jonoon samaan PHP-koukkuun, jota käytimme Javascript-tiedostomme jonoon. En mene yksityiskohtiin siitä, miten tämä tehdään; mutta tarvitsemasi CSS on jotain alla olevan kaltaista. Se vain asettaa välikappaleen background-colorperityn värin (se perii kääredivistämme), kun lohko valitaan:
.block-library-spacer__resize-container.is-selected {
background-color: inherit;
}PS: Muista, että tämä voi muuttua tulevaisuudessa. Gutenberg kehittyy edelleen voimakkaasti.
Johtopäätös
Tässä viestissä olemme oppineet kaksi tapaa toteuttaa mukautettuja asetuksia olemassa oleviin WordPress Gutenberg -lohkoihin. Se on täysin mahdollista yksinkertaisissa asetuksissa, jotka ehkä edellyttävät vain luokkaa tai sisäistä tyyliä. Olemme tarkastelleet varoitukset, jotka toivottavasti korjataan myöhemmissä Gutenberg-versioissa!