Preskoči na vsebino

Objava registra blokov na GitHub

Ko izdelate nekaj dobrih blokov, jih boste želeli uporabiti tudi v naslednjem projektu. Ročno kopiranje map med temami deluje, dokler se kopije ne razhajajo in se nihče več ne spomni, katera tema vsebuje popravljeno različico. Ovijanje vsakega bloka v paket z lastno gradnjo je precej zapleteno za mapo, ki vsebuje block.json in predlogo.

Register blokov je vmesna rešitev. Gre za datoteko registry.json in nabor map blokov, ki se strežejo prek navadnega HTTP. Uporabniki zaženejo ukaz CLI, izvorna koda bloka se kopira v njihovo temo, nato pa je ta kopija v njihovi lasti. Za gostovanje zadostuje repozitorij GitHub, saj GitHub streže vsako datoteko v javnem repozitoriju na surovem URL.

Ta vodnik izdela register acme s štirimi bloki, ga objavi iz repozitorija acme/acme-blocks, namesti bloke iz njega v temo in pripne izdajo z oznako git.

Paket blockstudio na npm je različice 0.0.1. Ta izdaja je nadomestna: njen edini ukaz, add, izpiše Adding block: <name> in se konča, ne da bi kar koli prenesel. Ukazi in izpis v tem vodniku izvirajo iz registra CLI v repozitoriju Blockstudio (packages/registry), ki je CLI, ki ga opisuje dokumentacija za register.

Kako se deli povežejo

Poznati morate dve datoteki:

  • registry.json objavi avtor bloka. Vsebuje seznam blokov, datotek vsakega bloka in baseUrl za njihov prenos.
  • blocks.json je v temi ali vtičniku uporabnika. V njem so navedeni registri za uporabo in imenik, kamor se namestijo bloki.

Ko namestite blok, CLI pridobi vse registre v blocks.json, poišče blok, razreši njegove odvisnosti, prenese vsako navedeno datoteko iz {baseUrl}/{block}/{file} in jo zapiše v {directory}/{block}/{file}. Ničesar ne preoblikuje, zato so datoteke na disku povsem enake kot v repozitoriju.

1. korak: uredite strukturo repozitorija

Ustvarite repozitorij z datoteko registry.json v korenski mapi in po eno mapo za vsak blok v blocks/:

Koda
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

Ime mape je ime bloka v registru in postane ime mape v temi uporabnika. Naj bo enako drugi polovici imena bloka v block.json (acme/hero je v hero/), da bo nameščeno mapo lahko prepoznati.

2. korak: napišite bloke

Vsaka mapa vsebuje običajen blok Blockstudio. Uvodni blok ima eno polje:

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 sledi enakemu vzorcu in doda style.scss. tabs upodobi <InnerBlocks allowedBlocks='["acme/tab-item"]' />, tab-item pa določa "parent": ["acme/tabs"], zato tabs ni uporabno brez tab-item. Register to povezavo opredeli v naslednjem koraku.

Ti bloki niso na noben način vezani na register. CLI kopira mape, zato lahko na enak način objavite blok, izdelan z @wordpress/create-block ali registriran z navadnim PHP.

3. korak: napišite registry.json

registry.json navaja vsak blok in vsako datoteko, ki naj jo prenese 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"]
    }
  ]
}

O delovanju te datoteke odloča nekaj pravil:

  • files je izrecen seznam. CLI prenese natanko te poti in ničesar drugega. Nadomestnih vzorcev ni, zato se nov vir namesti šele, ko ga dodate sem. Poti lahko vsebujejo podimenike, ki se ustvarijo med namestitvijo.
  • baseUrl mora biti absolutni URL. CLI ga preveri kot URL in zavrne relativne vrednosti. Datoteke blokov se vedno prenesejo iz baseUrl, nikoli z lokacije glede na to, kje je bil naložen registry.json.
  • dependencies poimenuje bloke v istem registru. Če dodate tabs, se najprej namesti tab-item. Manjkajoče in krožne odvisnosti prekinejo namestitev z napako.
  • name je obvezen, vendar ni prikazan. Ukazi in izpis uporabljajo ključ, ki ga porabnik dodeli registru v blocks.json; ta se lahko razlikuje.
  • type je informativen. Sprejema blockstudio, create-block ali wordpress in ne spremeni delovanja CLI.

CLI ob vsakem prenosu preveri celotno datoteko in sporoči vsako polje z napako, zato se zatipkana beseda pokaže, še preden se prenese katera koli datoteka. Vrstica $schema omogoča enaka preverjanja v urejevalniku.

4. korak: Objavite prek neposrednih URL-jev

Potrdite spremembe in pošljite repozitorij v GitHub. Nato je vsaka datoteka v javnem repozitoriju na voljo na naslovu:

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

<ref> je veja, oznaka ali SHA potrditve. Za ta register sta pomembna dva URL-ja:

  • URL registra URL, ki ga konfigurirajo porabniki: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl v registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

S tem baseUrl se index.php od hero prenese iz https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Neobdelani gostitelj vrne vsebino datoteke namesto strani GitHub HTML, ki jo potrebuje CLI. Napačen lastnik, repozitorij ali referenca se ob prvem ukazu pokaže kot 404:

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

5. korak: Namestite bloke v temo

V korenu teme, ki bo uporabljala bloke, ustvarite blocks.json:

Lupina
npx blockstudio init --yes
Koda
Created .../acme-theme/blocks.json

init --yes zapiše prazen objekt registries. Dodajte register pod imenskim prostorom, ki ga želite vnesti v ukaze:

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

V terminalu zaženite init brez --yes, da na ista vprašanja odgovorite interaktivno (imenik blokov, imena registrov in URL-je).

Preverite, ali register deluje:

Lupina
npx blockstudio list
Koda
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 išče podniz brez razlikovanja med velikimi in malimi črkami v imenih, naslovih in opisih:

Lupina
npx blockstudio search tab
Koda
Results for "tab"

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

Namestitev si oglejte z ukazom --dry-run. Odvisnost je na seznamu prva, ker se namesti prva:

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

Nato bloke dejansko namestite:

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

Obe mapi sta zdaj v imeniku blockstudio teme, povsem enako kot v repozitoriju:

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

Imenski prostor lahko izpustite, če ima blok samo en konfiguriran register, in hkrati podate več blokov:

Lupina
npx blockstudio add hero card
Koda
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio odkrije nove mape kot vse druge bloke v temi.

Posodabljanje nameščenih blokov

Nameščene datoteke so kopija. Sistem ne beleži, katero različico ste namestili, in CLI bloka nikoli ne posodobi samodejno. Če želite prenesti novejšo različico, blok dodajte znova. Brez terminala ali v okolju CI ukaz ustavi že obstoječa mapa:

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

V terminalu CLI namesto tega pred prepisom vpraša za potrditev. --dry-run navede mape, ki bi jih zamenjal, --yes pa jih zamenja:

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

Pri prepisu se navedene datoteke zamenjajo z različico iz registra, zato najprej potrdite lokalne spremembe in rezultat preverite z ukazom git diff.

Za odstranitev izbrišite mapo po imenu:

Lupina
npx blockstudio remove tabs --yes
Koda
Removed tabs

remove sprejme ime mape, ne pa namespace/block. Odvisnosti ne odstrani, zato tab-item ostane nameščen tudi po odstranitvi tabs.

Različice z referencami git

CLI nima polja za različico in nima zastavice za različico. Kaj se prenese, je v celoti odvisno od URL-jev; pri GitHub pa različico določa referenca v URL. Porabnik, ki uporabi main, dobi tisto, kar ta vsebuje ob namestitvi: main.

Če želite objaviti nespremenljivo izdajo, mora registry.json pri oznaki prav tako prenašati datoteke z oznake. Pred dodajanjem oznake nastavite baseUrl na oznako:

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

Nato potrdite spremembe, dodajte oznako in jih pošljite:

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

Nato baseUrl nastavite nazaj na main in spremembo potrdite, da veja še naprej streže aktualne datoteke. Če preskočite prvi korak, porabnik, pripet na oznako, dobi seznam blokov z oznake, datoteke pa prenese iz main.

Porabniki pripnejo različico tako, da v registru uporabijo oznako URL:

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

V tem primeru je bila oznaka v1.0.0 ustvarjena, preden sta obstajala tabs in tab-item, zato pripeti register ponuja samo prvotna dva bloka:

Lupina
npx blockstudio list
Koda
acme (2 blocks)

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

SHA potrditve deluje tudi v registru URL, vendar potrditev ne more vsebovati lastnega SHA v baseUrl. Pripetje na SHA torej določi seznam blokov, datoteke pa še vedno prihajajo iz reference, ki jo poimenuje baseUrl te potrditve. Zato za izdaje raje uporabite oznake.

Pomembne opombe

  • Najprej se prenese vsak register. add pred razreševanjem česar koli naloži vse registre v blocks.json, zato nedosegljiv register povzroči neuspeh ukaza, tudi če gre za acme/hero. Odstranite registre, ki jih ne uporabljate več.
  • Dvoumna imena zahtevajo imenski prostor. Če imata dva registra hero, terminalna seja vpraša, katerega uporabiti, --yes uporabi prvega po vrstnem redu v blocks.json, neinteraktivni zagon pa se konča z Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Zasebni repozitoriji zahtevajo glave. Uporabite objektno obliko vnosa registra z url in headers. Vrednosti glav podpirajo nadomestne oznake ${VAR}, ki se preberejo iz okolja; CLI pošlje glave ob prenosu registra in vsake datoteke. Za nastavitev žetona glejte gostovanje GitHub.

Naslednji koraki