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.jsonobjavi avtor bloka. Vsebuje seznam blokov, datotek vsakega bloka inbaseUrlza njihov prenos.blocks.jsonje 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/:
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:
{
"$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 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:
{
"$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:
filesje 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.baseUrlmora biti absolutni URL. CLI ga preveri kot URL in zavrne relativne vrednosti. Datoteke blokov se vedno prenesejo izbaseUrl, nikoli z lokacije glede na to, kje je bil naloženregistry.json.dependenciespoimenuje bloke v istem registru. Če dodatetabs, se najprej namestitab-item. Manjkajoče in krožne odvisnosti prekinejo namestitev z napako.nameje obvezen, vendar ni prikazan. Ukazi in izpis uporabljajo ključ, ki ga porabnik dodeli registru vblocks.json; ta se lahko razlikuje.typeje informativen. Sprejemablockstudio,create-blockaliwordpressin 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:
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 baseUrlvregistry.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:
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:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes zapiše prazen objekt registries. Dodajte register pod imenskim prostorom, ki ga želite vnesti v ukaze:
{
"$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:
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 išče podniz brez razlikovanja med velikimi in malimi črkami v imenih, naslovih in opisih:
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.
Namestitev si oglejte z ukazom --dry-run. Odvisnost je na seznamu prva, ker se namesti prva:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Nato bloke dejansko namestite:
npx blockstudio add acme/tabs
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:
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:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Nato potrdite spremembe, dodajte oznako in jih pošljite:
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:
{
"$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:
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".
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.
addpred razreševanjem česar koli naloži vse registre vblocks.json, zato nedosegljiv register povzroči neuspeh ukaza, tudi če gre zaacme/hero. Odstranite registre, ki jih ne uporabljate več. - Dvoumna imena zahtevajo imenski prostor. Če imata dva registra
hero, terminalna seja vpraša, katerega uporabiti,--yesuporabi prvega po vrstnem redu vblocks.json, neinteraktivni zagon pa se konča zBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Zasebni repozitoriji zahtevajo glave. Uporabite objektno obliko vnosa registra z
urlinheaders. 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
- Pregled registra: kaj je register in kako deluje CLI
- registry.json: vsa polja manifesta
- blocks.json: konfiguracija porabnika, preverjanje pristnosti in odkrivanje konfiguracije
- dodaj: razreševanje imenskih prostorov, odvisnosti in vedenje pri prepisovanju
- GitHub gostovanje: GitHub Pages in zasebni repozitoriji
- Strežnik po meri: streženje registra iz lastne infrastrukture