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.jsoneste publicat de autorul blocurilor. Enumeră blocurile, fișierele din care este alcătuit fiecare și unbaseUrlde unde să fie descărcate.blocks.jsonse 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/:
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:
{
"$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 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:
{
"$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ă:
fileseste 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.baseUrltrebuie să fie un URL absolut. CLI îl validează ca URL și respinge valorile relative. Fișierele blocurilor sunt descărcate întotdeauna dinbaseUrl, niciodată dintr-o locație relativă la locul din care a fost încărcatregistry.json.dependenciesnumește blocurile din același registru. Adăugarea luitabsinstalează mai întâitab-item. Dependențele lipsă și cele circulare opresc instalarea cu o eroare.nameeste obligatoriu, dar nu este afișat. Comenzile și rezultatul folosesc cheia cu care consumatorul înregistrează registrul înblocks.json, care nu trebuie să coincidă.typeare rol informativ. Acceptăblockstudio,create-blocksauwordpressș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:
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 baseUrldinregistry.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ă:
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:
npx blockstudio init --yes
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:
{
"$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:
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 caută un fragment de text fără a ține cont de majuscule și minuscule în nume, titluri și descrieri:
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.
Previzualizați o instalare cu --dry-run. Dependența este afișată prima, fiindcă se instalează prima:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Apoi instalați efectiv:
npx blockstudio add acme/tabs
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:
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ă:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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ă:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Apoi faceți commit, creați eticheta și faceți push:
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:
{
"$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:
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".
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 dinblocks.jsonînainte să rezolve ceva, așa că un registry inaccesibil face comanda să eșueze chiar și pentruacme/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 ordineablocks.json, iar o rulare non-interactivă se încheie cuBlock "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șiheaders. 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
- Prezentare generală a registrului: ce este registrul și cum funcționează CLI
- registry.json: toate câmpurile manifestului
- blocks.json: configurarea consumatorului, autentificarea și descoperirea configurației
- adăugare: rezolvarea spațiilor de nume, dependențele și comportamentul la suprascriere
- GitHub configurarea găzduirii: GitHub Pages și depozitele private
- Server personalizat: servirea unui registru de pe propria infrastructură