Lohkorekisterin julkaiseminen kohteessa GitHub
Kun olet rakentanut muutaman hyvän lohkon, haluat ne myös seuraavaan projektiin.
Kansioiden kopiointi teemojen välillä käsin toimii siihen asti, kunnes kopiot erkanevat toisistaan eikä kukaan enää muista, missä teemassa korjattu versio on. Jokaisen lohkon paketoiminen omaksi paketiksiksi, jolla on oma koontiprosessi, on turhan monimutkaista kansiolle, jossa on block.json ja mallipohja.
Lohkorekisteri ratkaisee tämän. Se on registry.json-tiedosto ja joukko lohkokansioita, joita tarjotaan tavallisen HTTP-protokollan kautta. Käyttäjät suorittavat CLI-komennon, lohkon lähdekoodi kopioidaan heidän teemaansa, ja siitä lähtien he hallitsevat kyseistä kopiota. Rekisterin isännöintiin riittää GitHub-säilö, koska GitHub tarjoaa kaikki julkisen säilön tiedostot raw-URL-osoitteessa.
Tässä oppaassa rakennetaan rekisteri nimeltä acme, jossa on neljä lohkoa. Se julkaistaan säilössä acme/acme-blocks, lohkot asennetaan sieltä teemaan ja julkaisuversio kiinnitetään git-tunnisteella.
Kohteen blockstudio paketti palvelussa npm on versiossa 0.0.1. Julkaisu on paikkamerkki: sen ainoa komento, add, tulostaa tekstin Adding block: <name> ja päättyy hakematta mitään. Tämän oppaan komennot ja tulosteet ovat rekisteristä CLI säilössä Blockstudio (packages/registry), joka on se CLI, josta rekisteridokumentaatio puhuu.
Osien yhteistoiminta
Tässä on kaksi tunnettavaa tiedostoa:
- Lohkon tekijä julkaisee tiedoston
registry.json. Siinä luetellaan lohkot, kunkin lohkon muodostavat tiedostot jabaseUrlniiden lataamista varten. blocks.jsonsijaitsee käyttäjän teemassa tai lisäosassa. Siinä määritetään käytettävät rekisterit ja hakemisto, johon lohkot asennetaan.
Kun asennat lohkon, CLI hakee jokaisen kohteessa blocks.json määritetyn rekisterin, etsii lohkon, selvittää sen riippuvuudet, lataa kunkin luettelossa olevan tiedoston kohteesta {baseUrl}/{block}/{file} ja kirjoittaa sen kohteeseen {directory}/{block}/{file}. Se ei muunna mitään, joten levyllä olevat tiedostot ovat täsmälleen samat kuin säilössä.
Vaihe 1: Säilön rakenne
Luo säilö, jonka juuressa on registry.json, ja yksi kansio kutakin lohkoa varten kohteessa blocks/:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
Kansion nimi on lohkon nimi rekisterissä, ja siitä tulee myös kansion nimi käyttäjän teemassa. Pidä nimi samana kuin lohkon nimen toinen osa kohteessa block.json (acme/hero sijaitsee kohteessa hero/), jotta asennettu kansio on helppo tunnistaa.
Vaihe 2: Lohkojen kirjoittaminen
Jokainen kansio on tavallinen Blockstudio-lohko. Sankariolohkossa on yksi kenttä:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
card noudattaa samaa mallia ja lisää siihen style.scss-ominaisuuden. tabs renderöi arvon <InnerBlocks allowedBlocks='["acme/tab-item"]' />, ja tab-item määrittää arvon "parent": ["acme/tabs"], joten tabs ei ole hyödyllinen ilman kohdetta tab-item. Rekisteri ilmaisee tämän yhteyden seuraavassa vaiheessa.
Näissä lohkoissa ei ole mitään rekisterikohtaista. CLI kopioi kansiot, joten @wordpress/create-block-työkalulla rakennettu tai tavallisella PHP-työkalulla rekisteröity lohko voidaan julkaista samalla tavalla.
Vaihe 3: Tiedoston registry.json kirjoittaminen
registry.json luettelee jokaisen lohkon ja kaikki tiedostot, jotka CLI lataa:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
Tämä tiedosto toimii muutaman säännön perusteella:
fileson nimenomainen luettelo. CLI lataa täsmälleen nämä polut eikä mitään muuta. Tiedostohakuja ei tehdä, joten uusi resurssi otetaan mukaan vasta, kun lisäät sen tähän. Poluissa voi olla alihakemistoja, jotka luodaan asennuksen yhteydessä.baseUrlon oltava absoluuttinen URL. CLI tarkistaa sen URL-arvoksi ja hylkää suhteelliset arvot. Lohkotiedostot haetaan aina osoitteestabaseUrl, ei sijainnista suhteessa siihen, mistäregistry.jsonladattiin.dependenciesnimeävät lohkoja samassa rekisterissä.tabsasentaa ensintab-item-lohkon. Puuttuvat ja kehämäiset riippuvuudet keskeyttävät asennuksen virheeseen.nameon pakollinen, mutta sitä ei näytetä. Komennot ja tulosteet käyttävät avainta, jonka käyttäjä antaa rekisterille kohdassablocks.json; avainten ei tarvitse olla samat.typeon vain tiedoksi. Se hyväksyy arvotblockstudio,create-blocktaiwordpress, eikä vaikuta siihen, mitä CLI tekee.
CLI tarkistaa koko tiedoston jokaisella hakukerralla ja ilmoittaa jokaisen virheellisen kentän, joten kirjoitusvirhe havaitaan ennen tiedostojen lataamista. Rivi $schema suorittaa samat tarkistukset editorissasi.
Vaihe 4: Julkaise raakamuotoisilla URL-osoitteilla
Tee commit ja pushaa repositorio osoitteeseen GitHub. Julkisen repositorion jokainen tiedosto on tämän jälkeen saatavilla osoitteessa:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> on haara, tunniste tai commitin SHA. Tämän rekisterin kannalta merkityksellisiä URL-osoitteita on kaksi:
- Rekisterin URL, jonka kuluttajat määrittävät asetuksissa:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrlkohteessaregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Kun käytössä on tämä baseUrl, kohteen hero index.php haetaan osoitteesta https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Raakamuotoinen isäntä palauttaa tiedoston sisällön GitHub HTML-sivun sijaan, mitä CLI tarvitsee. Väärä omistaja, repositorio tai viite tulee ilmi 404-virheenä ensimmäisessä komennossa:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Vaihe 5: Asenna lohkot teemaan
Luo kuluttavan teeman juurihakemistoon tiedosto blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes luo tyhjän registries-objektin. Lisää rekisteri sen nimiavaruuden alle, jota haluat käyttää komennoissa:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Suorita pääteikkunassa init ilman valitsinta --yes, niin voit vastata samoihin kysymyksiin vuorovaikutteisesti (lohkon hakemisto, rekisterien nimet ja URL-osoitteet).
Tarkista, että rekisteri löytyy:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
search etsii kirjainkoosta riippumatonta osamerkkijonoa nimistä, otsikoista ja kuvauksista:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
Esikatsele asennusta komennolla --dry-run. Riippuvuus näytetään ensin, koska se asennetaan ensin:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Asenna sitten:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Molemmat kansiot ovat nyt teeman hakemistossa blockstudio täsmälleen samassa muodossa kuin repositoriossa:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Voit jättää nimiavaruuden pois, jos vain yhdessä määritetyssä rekisterissä on kyseinen lohko, ja antaa useita lohkoja kerralla:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio löytää uudet kansiot kuten muutkin teeman lohkot.
Asennettujen lohkojen päivittäminen
Asennetut tiedostot ovat kopioita. Asennetun version tallennusta ei seurata, eikä CLI koskaan päivitä lohkoa itsestään. Hae uudempi versio lisäämällä lohko uudelleen. Ilman pääteikkunaa tai CI-ympäristössä olemassa oleva kansio keskeyttää komennon:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Pääteikkunassa CLI kysyy ennen ylikirjoittamista. --dry-run näyttää kansiot, jotka se korvaisi, ja --yes korvaa ne:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Ylikirjoitus korvaa luetellut tiedostot rekisterin versiolla, joten tee paikallisista muutoksista ensin commit ja tarkista tulos komennolla git diff.
Poista lohko poistamalla kansio nimensä perusteella:
npx blockstudio remove tabs --yes
Removed tabs
remove ottaa kansion nimen, ei nimeä namespace/block. Se ei poista riippuvuuksia, joten tab-item jää asennetuksi, kun poistat tabs-lohkon.
Versiointi git-viitteillä
CLI-määrityksessä ei ole versiokenttää eikä versiovalitsinta. Haettavat tiedostot määräytyvät kokonaan URL-osoitteiden perusteella; osoitteessa GitHub viite kohdassa URL on versio. Kuluttaja, joka käyttää osoitetta main, saa sen sisällön, mitä main sisältää asennushetkellä.
Jos haluat julkaista muuttumattomana pysyvän version, tunnisteen rekisterin registry.json täytyy myös ladata tiedostot tunnisteesta. Aseta ennen tunnisteen luomista baseUrl tunnisteeseen:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Tee sitten commit, luo tunniste ja pushaa:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Aseta sen jälkeen baseUrl takaisin arvoon main ja tee commit, jotta haara jatkaa ajantasaisten tiedostojen tarjoamista. Jos ohitat ensimmäisen vaiheen, tunnisteeseen kiinnitetty kuluttaja saa tunnisteen mukaisen lohkoluettelon, mutta lataa tiedostot kohteesta main.
Kuluttaja kiinnittää version käyttämällä tunnistetta rekisterin URL-arvossa:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Tässä esimerkissä v1.0.0 merkittiin tunnisteella ennen kuin tabs ja tab-item olivat olemassa, joten kiinnitetyssä rekisterissä on vain kaksi alkuperäistä lohkoa:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
Commitin SHA toimii myös rekisterin URL-arvona, mutta commit ei voi sisältää omaa SHA-tunnustaan kohdassa baseUrl. SHA-arvolla kiinnittäminen lukitsee siis lohkoluettelon, mutta tiedostot haetaan edelleen commitin baseUrl-arvossa nimeämästä viitteestä. Käytä siksi julkaisuissa mieluummin tunnisteita.
Huomioitavaa
- Jokainen rekisteri haetaan ensin.
addlataa kaikki rekisterit kohdassablocks.jsonennen kuin se ratkaisee mitään, joten yhdenkin rekisterin tavoittamattomuus kaataa komennon, vaikkaacme/heroei tarvitsisi sitä. Poista rekisterit, joita et enää käytä. - Samannimiset lohkot vaativat nimiavaruuden. Jos kahdessa rekisterissä on
hero, pääteistunto kysyy, kumpaa käytetään,--yesvalitsee ensimmäisen kohdanblocks.jsonjärjestyksessä, ja ei-vuorovaikutteinen suoritus päättyy arvoonBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Yksityiset repositoriot vaativat otsakkeita. Käytä rekisterimerkinnän objektimuotoa valitsimilla
urljaheaders. Otsakkeiden arvot hyväksyvät ympäristöstä luettavia${VAR}-paikkamerkkejä, ja CLI lähettää otsakkeet sekä rekisteriä haettaessa että jokaista tiedostoa ladattaessa. Katso kohdasta GitHub hosting, miten tunnus määritetään.
Seuraavat vaiheet
- Rekisterin yleiskatsaus: mikä rekisteri on ja miten CLI toimii
- registry.json: kaikki manifestin kentät
- blocks.json: kuluttajan asetukset, tunnistautuminen ja asetusten etsintä
- lisääminen: nimiavaruuden ratkaisu, riippuvuudet ja ylikirjoituskäyttäytyminen
- GitHub hosting: GitHub Pages ja yksityiset repositoriot
- Mukautettu palvelin: rekisterin tarjoaminen omasta infrastruktuurista