Pereiti prie turinio

Blokų registro publikavimas platformoje GitHub

Sukūrus kelis gerus blokus, norisi juos panaudoti ir kitame projekte. Rankiniu būdu kopijuoti aplankus iš vienos temos į kitą veikia tol, kol kopijos ima skirtis ir niekas nebeprisimena, kurioje temoje yra pataisyta versija. Kiekvieną bloką supakuoti į atskirą paketą su savo kūrimo procesu – daug papildomų veiksmų dėl aplanko, kuriame yra block.json ir šablonas.

Blokų registras užima tarpinę vietą. Tai registry.json failas ir blokų aplankų rinkinys, pateikiami paprastu HTTP protokolu. Naudotojai paleidžia komandą CLI, bloko šaltinio failai nukopijuojami į jų temą, o nuo tada jie tvarko tą kopiją patys. Registrui talpinti pakanka GitHub saugyklos, nes GitHub pateikia kiekvieną viešos saugyklos failą neapdorotu URL adresu.

Šiame vadove sukursime registrą acme su keturiais blokais, paskelbsime jį saugykloje acme/acme-blocks, įdiegsime iš jo blokus į temą ir prisegsime leidimą naudodami git žymą.

Paketo blockstudio versija 0.0.1 platformoje npm jau paskelbta. Tai tik vietos rezervavimo leidimas: vienintelė jo komanda add išveda Adding block: <name> ir baigia darbą nieko neatsiuntusi. Šiame vadove pateikiamos komandos ir jų išvestis yra iš registro CLI, esančio saugykloje Blockstudio (packages/registry). Tai CLI, kurį aprašo Registro dokumentacija.

Kaip susiję komponentai

Reikia žinoti du failus:

  • registry.json publikuoja blokų autorius. Jame išvardyti blokai, kiekvieno bloko failai ir baseUrl, iš kur jų atsisiųsti.
  • blocks.json laikomas naudotojo temoje arba įskiepyje. Jame nurodyti naudotini registrai ir katalogas, į kurį diegiami blokai.

Įdiegus bloką, CLI atsisiunčia kiekvieną registre, nurodytame faile blocks.json, esantį elementą, suranda bloką, išsprendžia jo priklausomybes, atsisiunčia kiekvieną failą iš {baseUrl}/{block}/{file} ir įrašo jį į {directory}/{block}/{file}. Nieko netransformuoja, todėl diske esantys failai yra tiksliai tokie, kaip ir saugykloje.

1 žingsnis: sutvarkykite saugyklą

Sukurkite saugyklą su registry.json šakniniame kataloge ir po vieną aplanką kiekvienam blokui kataloge blocks/:

Kodas
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

Aplanko pavadinimas yra bloko pavadinimas registre; jis tampa ir aplanko pavadinimu naudotojo temoje. Sutapatinkite jį su antrąja bloko pavadinimo dalimi faile block.json (acme/hero yra hero/), kad įdiegtą aplanką būtų lengva atpažinti.

2 žingsnis: parašykite blokus

Kiekviename aplanke yra įprastas Blockstudio blokas. Pagrindinės sekcijos blokas turi vieną lauką:

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 laikosi to paties šablono ir prideda style.scss. tabs atvaizduoja <InnerBlocks allowedBlocks='["acme/tab-item"]' />, o tab-item deklaruoja "parent": ["acme/tabs"], todėl be tab-item naudoti tabs nėra prasminga. Šį ryšį registre aprašysime kitame žingsnyje.

Šiuose blokuose nėra nieko, kas būtų skirta tik registrui. CLI kopijuoja aplankus, todėl tokiu pačiu būdu galima paskelbti ir bloką, sukurtą naudojant @wordpress/create-block arba užregistruotą įprastu PHP.

3 žingsnis: parašykite registry.json

registry.json išvardija kiekvieną bloką ir visus failus, kuriuos turi atsisiųsti CLI:

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"]
    }
  ]
}

Ar šis failas veiks, lemia kelios taisyklės:

  • files yra aiškus sąrašas. CLI atsisiunčia tiksliai šiuos kelius ir nieko daugiau. Šablonai nenaudojami, todėl naujas išteklius bus įtrauktas tik pridėjus jį čia. Keliuose gali būti pakatalogių, kurie sukuriami diegiant.
  • baseUrl turi būti absoliutus URL. CLI jį patikrina kaip URL ir atmeta santykines reikšmes. Blokų failai visada gaunami iš baseUrl, o ne iš vietos, santykinės tai vietai, iš kurios įkeltas registry.json.
  • dependencies turi nurodyti blokus tame pačiame registre. Pridėjus tabs, pirmiausia įdiegiamas tab-item. Dėl trūkstamų ar ciklinių priklausomybių diegimas sustabdomas ir pateikiama klaida.
  • name yra būtinas, bet nerodomas. Komandose ir išvestyje naudojamas raktas, kurį naudotojas priskiria registrui per blocks.json; jis gali skirtis.
  • type yra informacinis. Galimos reikšmės: blockstudio, create-block arba wordpress; jos nekeičia, ką daro CLI.

CLI kiekvieną kartą gaudamas failą patikrina visą jo turinį ir praneša apie kiekvieną klaidingą lauką, todėl rašybos klaida išryškėja dar prieš atsisiunčiant bet kokį failą. $schema eilutėje pateikiami tie patys patikrinimai jūsų redaktoriuje.

4 veiksmas: paskelbkite per neapdoroto turinio URL

Pateikite saugyklos pakeitimus ir nusiųskite juos į GitHub. Tada kiekvienas viešos saugyklos failas pasiekiamas adresu:

Kodas
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> yra šaka, žyma arba pakeitimo SHA. Šiame registre svarbūs du URL:

  • Registro URL, kurį sukonfigūruoja naudotojai: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl iš registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Naudojant šį baseUrl, hero gaunamas iš https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. index.php. Neapdoroto turinio priegloba grąžina failo turinį, o ne GitHub HTML puslapį, kurio reikia CLI. Neteisingas savininkas, saugykla ar nuoroda išryškės kaip 404 jau paleidus pirmąją komandą:

Kodas
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

5 veiksmas: įdiekite blokus temoje

Vartotojo temos šakniniame kataloge sukurkite blocks.json:

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

init --yes įrašo tuščią registries objektą. Įtraukite registrą į vardų sritį, kurią norite rašyti komandose:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

Paleiskite init terminale be --yes, kad interaktyviai atsakytumėte į tuos pačius klausimus apie blokų katalogą, registrų pavadinimus ir URL.

Patikrinkite, ar registras randamas:

Shell
npx blockstudio list
Kodas
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 ieško didžiųjų ir mažųjų raidžių neskirdamas, ar pavadinimuose, antraštėse ir aprašuose yra nurodyta eilutė:

Shell
npx blockstudio search tab
Kodas
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

Peržiūrėkite diegimą naudodami --dry-run. Priklausomybė pateikiama pirma, nes ji įdiegiama pirmiausia:

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

Dabar įdiekite:

Shell
npx blockstudio add acme/tabs
Kodas
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Abu aplankai dabar yra temos blockstudio kataloge, tiksliai tokie patys kaip saugykloje:

Kodas
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Kai bloką turi tik vienas sukonfigūruotas registras, vardų srities nurodyti nereikia; vienu metu galima perduoti kelis blokus:

Shell
npx blockstudio add hero card
Kodas
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio aptinka naujus aplankus kaip ir kitus temos blokus.

Įdiegtų blokų atnaujinimas

Įdiegti failai yra kopija. Nei įdiegta versija nėra sekama, nei CLI pats atnaujina blokus. Norėdami gauti naujesnę versiją, pridėkite bloką dar kartą. Jei terminalo nėra arba naudojama CI, komandą sustabdo jau esantis aplankas:

Shell
npx blockstudio add tab-item
Kodas
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

Terminale CLI vietoj to paklausia, ar perrašyti. --dry-run pateikia aplankus, kuriuos pakeistų, o --yes juos pakeičia:

Shell
npx blockstudio add acme/tab-item --dry-run
Kodas
Would overwrite tab-item
Would install:
  tab-item (2 files)

Perrašant nurodyti failai pakeičiami registro versija, todėl pirmiausia įrašykite vietinius pakeitimus į Git, o tada peržiūrėkite rezultatą naudodami git diff.

Norėdami pašalinti bloką, ištrinkite aplanką pagal pavadinimą:

Shell
npx blockstudio remove tabs --yes
Kodas
Removed tabs

remove priima aplanko pavadinimą, o ne namespace/block. Priklausomybės nepašalinamos, todėl pašalinus tabs, tab-item lieka įdiegtas.

Versijų valdymas naudojant git nuorodas

CLI neturi nei versijos lauko, nei versijos parinkties. Tai, ką jis gauna, visiškai priklauso nuo URL, o naudojant GitHub, URL nurodyta nuoroda yra versija. Nurodžius main, diegimo metu gaunama tai, ką tuo metu turi main.

Norint paskelbti nekintantį leidimą, žymos registry.json taip pat turi siųstis iš žymos. Prieš sukurdami žymą, nustatykite baseUrl į žymą:

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

Tada įrašykite pakeitimus, sukurkite žymą ir nusiųskite ją:

Shell
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Vėliau vėl nustatykite baseUrl į main ir įrašykite pakeitimus, kad šaka ir toliau teiktų naujausius failus. Jei praleisite pirmąjį veiksmą, žymą nurodęs naudotojas gaus pažymėtą blokų sąrašą, bet failai bus atsisiųsti iš main.

Naudotojai užfiksuoja versiją savo registro URL nurodydami žymą:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

Šiame pavyzdyje v1.0.0 buvo pažymėtas dar neegzistuojant tabs ir tab-item, todėl užfiksuotame registre siūlomi tik du pradiniai blokai:

Shell
npx blockstudio list
Kodas
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Kodas
Block "tabs" not found in registry "acme".

Registro URL taip pat tinka pakeitimo SHA, tačiau pakeitime negali būti savo SHA lauko baseUrl. Todėl SHA fiksuoja blokų sąrašą, o failai vis tiek gaunami iš tos nuorodos, kurią nurodo to pakeitimo baseUrl. Dėl to leidimams verčiau naudoti žymas.

Ką verta turėti omenyje

  • Pirmiausia gaunamas kiekvienas registras. add įkelia visus blocks.json esančius registrus prieš ką nors išspręsdamas, todėl dėl nepasiekiamo registro komanda nepavyks net ir naudojant acme/hero. Pašalinkite nebenaudojamus registrus.
  • Dviprasmiškiems pavadinimams reikia vardų srities. Jei tą patį hero turi du registrai, terminalo seanso metu paklausiama, kurį naudoti, --yes pasirenka pirmąjį pagal blocks.json tvarką, o neinteraktyvus paleidimas baigiasi su Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Privačioms saugykloms reikia antraščių. Naudokite registro įrašo objekto formą su url ir headers. Antraščių reikšmėse galima naudoti ${VAR} vietos rezervavimo ženklus, kurių reikšmės nuskaitomos iš aplinkos. CLI siunčia antraštes gaudamas registrą ir atsisiųsdamas kiekvieną failą. Žr. GitHubGitHub privačių saugyklų prieglobos instrukcijas apie žetonų sąranką.

Tolesni veiksmai