Siirry sisältöön

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 ja baseUrl niiden lataamista varten.
  • blocks.json sijaitsee 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/:

Koodi
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ä:

JSON
{
  "$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"
      }
    ]
  }
}
PHP
<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:

JSON
{
  "$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:

  • files on 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ä.
  • baseUrl on oltava absoluuttinen URL. CLI tarkistaa sen URL-arvoksi ja hylkää suhteelliset arvot. Lohkotiedostot haetaan aina osoitteesta baseUrl, ei sijainnista suhteessa siihen, mistä registry.json ladattiin.
  • dependencies nimeävät lohkoja samassa rekisterissä. tabs asentaa ensin tab-item-lohkon. Puuttuvat ja kehämäiset riippuvuudet keskeyttävät asennuksen virheeseen.
  • name on pakollinen, mutta sitä ei näytetä. Komennot ja tulosteet käyttävät avainta, jonka käyttäjä antaa rekisterille kohdassa blocks.json; avainten ei tarvitse olla samat.
  • type on vain tiedoksi. Se hyväksyy arvot blockstudio, create-block tai wordpress, 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:

Koodi
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
  • baseUrl kohteessa registry.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:

Koodi
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:

Shell
npx blockstudio init --yes
Koodi
Created .../acme-theme/blocks.json

init --yes luo tyhjän registries-objektin. Lisää rekisteri sen nimiavaruuden alle, jota haluat käyttää komennoissa:

JSON
{
  "$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:

Shell
npx blockstudio list
Koodi
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:

Shell
npx blockstudio search tab
Koodi
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:

Shell
npx blockstudio add acme/tabs --dry-run
Koodi
Would install:
  tab-item (2 files)
  tabs (3 files)

Asenna sitten:

Shell
npx blockstudio add acme/tabs
Koodi
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:

Koodi
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:

Shell
npx blockstudio add hero card
Koodi
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:

Shell
npx blockstudio add tab-item
Koodi
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:

Shell
npx blockstudio add acme/tab-item --dry-run
Koodi
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:

Shell
npx blockstudio remove tabs --yes
Koodi
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:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

Tee sitten commit, luo tunniste ja pushaa:

Shell
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:

JSON
{
  "$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:

Shell
npx blockstudio list
Koodi
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Koodi
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. add lataa kaikki rekisterit kohdassa blocks.json ennen kuin se ratkaisee mitään, joten yhdenkin rekisterin tavoittamattomuus kaataa komennon, vaikka acme/hero ei 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, --yes valitsee ensimmäisen kohdan blocks.json järjestyksessä, ja ei-vuorovaikutteinen suoritus päättyy arvoon Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Yksityiset repositoriot vaativat otsakkeita. Käytä rekisterimerkinnän objektimuotoa valitsimilla url ja headers. 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