Treci la conținut

Publicarea unui registru de blocuri pe GitHub

După ce ați creat câteva blocuri bune, veți dori să le folosiți și în următorul proiect. Copierea manuală a dosarelor între teme funcționează până când copiile ajung să difere și nimeni nu își mai amintește în ce temă se află versiunea reparată. Împachetarea fiecărui bloc într-un pachet cu propriul proces de compilare înseamnă multă formalitate pentru un dosar care conține un block.json și un șablon.

Un registru de blocuri oferă o soluție intermediară. Este un fișier registry.json și un set de dosare cu blocuri, servite printr-un HTTP simplu. Utilizatorii rulează o comandă CLI, sursa blocului este copiată în tema lor, iar de atunci copia le aparține. Pentru a găzdui un astfel de registru este suficient un depozit GitHub, deoarece GitHub servește fiecare fișier dintr-un depozit public la o adresă URL brută.

Acest ghid creează un registru numit acme cu patru blocuri, îl publică din depozitul acme/acme-blocks, instalează blocuri din acesta într-o temă și fixează o versiune printr-o etichetă git.

Pachetul blockstudio de pe npm este la versiunea 0.0.1. Acea versiune este doar un substituent: singura sa comandă, add, afișează Adding block: <name> și se închide fără să descarce nimic. Comenzile și rezultatele din acest ghid provin din registrul CLI din depozitul Blockstudio (packages/registry), pe care îl descriu documentele pentru CLI Registru.

Cum se îmbină componentele

Sunt două fișiere pe care trebuie să le cunoașteți:

  • registry.json este publicat de autorul blocurilor. Enumeră blocurile, fișierele din care este alcătuit fiecare și un baseUrl de unde să fie descărcate.
  • blocks.json se află în tema sau pluginul utilizatorului. Specifică registrele de folosit și directorul în care se instalează blocurile.

Când instalați un bloc, CLI preia fiecare registru din blocks.json, găsește blocul, rezolvă dependențele, descarcă fiecare fișier enumerat din {baseUrl}/{block}/{file} și îl scrie în {directory}/{block}/{file}. Nu transformă nimic, așa că fișierele de pe disc sunt identice cu cele din depozit.

Pasul 1: Structurați depozitul

Creați un depozit cu un registry.json în directorul rădăcină și câte un dosar pentru fiecare bloc în blocks/:

Cod
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

Numele dosarului este numele blocului în registru și devine numele dosarului din tema utilizatorului. Păstrați-l identic cu a doua parte a numelui blocului din block.json (acme/hero se află în hero/), astfel încât dosarul instalat să fie ușor de identificat.

Pasul 2: Scrieți blocurile

Fiecare dosar conține un bloc obișnuit Blockstudio. Blocul de secțiune principală are un singur câmp:

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 urmează același model și adaugă un style.scss. tabs randează <InnerBlocks allowedBlocks='["acme/tab-item"]' />, iar tab-item declară "parent": ["acme/tabs"], așa că tabs nu este util fără tab-item. Registrul va descrie această relație în pasul următor.

Nimic din aceste blocuri nu este specific registrului. CLI doar copiază dosare, așa că un bloc creat cu @wordpress/create-block sau înregistrat prin PHP simplu poate fi publicat în același mod.

Pasul 3: Scrieți registry.json

registry.json enumeră fiecare bloc și fiecare fișier pe care CLI trebuie să îl descarce:

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

Câteva reguli stabilesc dacă acest fișier funcționează:

  • files este o listă explicită. CLI descarcă exact aceste căi și nimic altceva. Nu există potrivire cu modele globale, așa că un activ nou este inclus doar după ce îl adăugați aici. Căile pot conține subdirectoare, care sunt create la instalare.
  • baseUrl trebuie să fie un URL absolut. CLI îl validează ca URL și respinge valorile relative. Fișierele blocurilor sunt descărcate întotdeauna din baseUrl, niciodată dintr-o locație relativă la locul din care a fost încărcat registry.json.
  • dependencies numește blocurile din același registru. Adăugarea lui tabs instalează mai întâi tab-item. Dependențele lipsă și cele circulare opresc instalarea cu o eroare.
  • name este obligatoriu, dar nu este afișat. Comenzile și rezultatul folosesc cheia cu care consumatorul înregistrează registrul în blocks.json, care nu trebuie să coincidă.
  • type are rol informativ. Acceptă blockstudio, create-block sau wordpress și nu schimbă ce face CLI.

CLI validează întregul fișier la fiecare descărcare și raportează fiecare câmp cu probleme, astfel încât o greșeală de scriere este identificată înainte de descărcarea oricărui fișier. Linia $schema oferă aceleași verificări în editor.

Pasul 4: Publicarea prin URL-uri raw

Faceți commit și push la depozit pe GitHub. Fiecare fișier dintr-un depozit public este apoi disponibil la:

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

<ref> este o ramură, o etichetă sau un SHA de commit. Pentru acest registru, contează două URL-uri:

  • Registrul URL configurat de consumatori: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl din registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Cu acel baseUrl, index.php din hero este descărcat din https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Gazda raw returnează conținutul fișierului în locul paginii GitHub HTML, de care are nevoie CLI. Un proprietar, un depozit sau o referință incorectă va genera o 404 la prima comandă:

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

Pasul 5: Instalarea blocurilor într-o temă

În rădăcina temei consumatoare, creați blocks.json:

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

init --yes scrie un obiect registries gol. Adăugați registrul în spațiul de nume pe care doriți să îl tastați în comenzi:

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

Rulați init fără --yes într-un terminal pentru a răspunde interactiv la aceleași întrebări (directorul blocurilor, numele și URL-urile registrelor).

Verificați dacă registrul este găsit:

Shell
npx blockstudio list
Cod
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 caută un fragment de text fără a ține cont de majuscule și minuscule în nume, titluri și descrieri:

Shell
npx blockstudio search tab
Cod
Results for "tab"

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

Previzualizați o instalare cu --dry-run. Dependența este afișată prima, fiindcă se instalează prima:

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

Apoi instalați efectiv:

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

Ambele dosare se află acum în directorul blockstudio al temei, exact ca în depozit:

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

Puteți omite spațiul de nume dacă blocul se află într-un singur registru configurat și puteți transmite mai multe blocuri deodată:

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

Blockstudio descoperă noile dosare ca pe orice alt bloc din temă.

Actualizarea blocurilor instalate

Fișierele instalate sunt o copie. Nu se urmărește versiunea instalată, iar CLI nu actualizează niciodată automat un bloc. Pentru a descărca o versiune mai nouă, adăugați din nou blocul. Fără un terminal sau în CI, un dosar existent oprește comanda:

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

Într-un terminal, CLI vă întreabă înainte să suprascrie. --dry-run afișează dosarele pe care le-ar înlocui, iar --yes le înlocuiește:

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

Suprascrierea înlocuiește fișierele listate cu versiunea din registru, așa că faceți mai întâi commit la modificările locale și verificați rezultatul cu git diff.

Pentru dezinstalare, eliminați dosarul după nume:

Shell
npx blockstudio remove tabs --yes
Cod
Removed tabs

remove primește numele dosarului, nu namespace/block. Nu elimină dependențele, așa că tab-item rămâne instalat după eliminarea lui tabs.

Gestionarea versiunilor cu referințe git

CLI nu are niciun câmp de versiune și nicio opțiune de versiune. Ce descarcă este stabilit în întregime de URL-uri, iar pe GitHub versiunea este referința din URL. Un consumator care indică spre main primește tot ce conține main în momentul instalării.

Pentru a publica o versiune fixă, și registry.json de la etichetă trebuie să descarce din etichetă. Înainte de a crea eticheta, setați baseUrl la etichetă:

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

Apoi faceți commit, creați eticheta și faceți push:

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

După aceea, setați baseUrl din nou la main și faceți commit, astfel încât ramura să continue să servească fișierele actuale. Dacă omiteți primul pas, un consumator fixat la etichetă primește lista de blocuri etichetată, dar descarcă fișierele din main.

Consumatorii fixează versiunea folosind eticheta în URL registrului:

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

În acest exemplu, v1.0.0 a fost etichetat înainte să existe tabs și tab-item, așa că registrul fixat oferă doar cele două blocuri inițiale:

Shell
npx blockstudio list
Cod
acme (2 blocks)

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

Un SHA de commit funcționează și în URL registrului, dar un commit nu își poate include propriul SHA în baseUrl. Prin urmare, fixarea după SHA stabilește lista de blocuri, dar fișierele provin în continuare din referința denumită de baseUrl al acelui commit. De aceea, pentru versiuni publicate, preferați etichetele.

Aspecte de reținut

  • Fiecare registry este preluat mai întâi. add încarcă toate registry-urile din blocks.json înainte să rezolve ceva, așa că un registry inaccesibil face comanda să eșueze chiar și pentru acme/hero. Eliminați registry-urile pe care nu le mai folosiți.
  • Numele ambigue necesită un namespace. Dacă două registry-uri au ambele hero, o sesiune de terminal vă întreabă pe care să o folosească, --yes îl alege pe primul în ordinea blocks.json, iar o rulare non-interactivă se încheie cu Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Depozitele private au nevoie de antete. Folosiți forma obiect a unei intrări de registry cu url și headers. Valorile antetelor acceptă substituenți ${VAR}, care sunt preluați din mediu, iar CLI trimite antetele împreună cu solicitarea de preluare a registry-ului și cu fiecare descărcare de fișier. Consultați GitHub găzduire pentru configurarea tokenului.

Pașii următori