Publikovanie registra blokov na GitHub
Keď vytvoríte niekoľko dobrých blokov, budete ich chcieť použiť aj v ďalšom projekte. Ručné kopírovanie priečinkov medzi témami funguje dovtedy, kým sa kópie nezačnú rozchádzať a nikto si nepamätá, ktorá téma obsahuje opravenú verziu. Zabaliť každý blok do balíka s vlastnou zostavou je priveľa práce pre priečinok, ktorý obsahuje block.json a šablónu.
Medzi tým je register blokov. Ide o súbor registry.json a súbor priečinkov blokov, ktoré sa sprístupňujú cez obyčajné HTTP. Používatelia spustia príkaz CLI, zdrojový kód bloku sa skopíruje do ich témy a od tej chvíle túto kópiu spravujú sami. Na jeho hostovanie stačí repozitár GitHub, pretože GitHub sprístupňuje každý súbor vo verejnom repozitári na surovej adrese URL.
Táto príručka vytvorí register s názvom acme so štyrmi blokmi, publikuje ho z repozitára acme/acme-blocks, nainštaluje z neho bloky do témy a pripne vydanie prostredníctvom značky git.
Balík blockstudio na npm má verziu 0.0.1. Toto vydanie je zástupné: jeho jediný príkaz add vypíše Adding block: <name> a skončí bez načítania čohokoľvek. Príkazy a výstupy v tejto príručke pochádzajú z registra CLI v repozitári Blockstudio (packages/registry), čo je CLI, ktorý opisuje Dokumentácia registra.
Ako do seba jednotlivé časti zapadajú
Treba poznať dva súbory:
registry.jsonpublikuje autor bloku. Uvádza bloky, súbory, z ktorých sa každý blok skladá, abaseUrlna ich stiahnutie.blocks.jsonsa nachádza v téme alebo doplnku používateľa. Uvádza registre, ktoré treba použiť, a priečinok, do ktorého sa bloky inštalujú.
Pri inštalácii bloku CLI načíta každý register z blocks.json, vyhľadá blok, vyrieši jeho závislosti, stiahne každý uvedený súbor z {baseUrl}/{block}/{file} a zapíše ho do {directory}/{block}/{file}. Nič nemení, takže súbory na disku sú presne také ako v repozitári.
Krok 1: Usporiadanie repozitára
Vytvorte repozitár, ktorého koreň obsahuje registry.json a ktorý má v priečinku blocks/ samostatný priečinok pre každý blok:
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
Názov priečinka je názvom bloku v registri a stane sa názvom priečinka v téme používateľa. Nechajte ho rovnaký ako druhú časť názvu bloku v block.json (acme/hero sa nachádza v hero/), aby sa nainštalovaný priečinok dal ľahko rozpoznať.
Krok 2: Zápis blokov
Každý priečinok obsahuje obyčajný blok Blockstudio. Úvodný blok má jedno pole:
{
"$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 sa riadi rovnakým vzorom a pridáva style.scss. tabs vykresľuje <InnerBlocks allowedBlocks='["acme/tab-item"]' /> a tab-item deklaruje "parent": ["acme/tabs"], takže tabs nie je užitočné bez tab-item. Register tento vzťah vyjadruje v ďalšom kroku.
Na týchto blokoch nie je nič špecifické pre register. CLI kopíruje priečinky, takže rovnakým spôsobom možno publikovať blok vytvorený pomocou @wordpress/create-block alebo zaregistrovaný pomocou obyčajného PHP.
Krok 3: Zápis registry.json
registry.json uvádza každý blok a každý súbor, ktorý má CLI stiahnuť:
{
"$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 funkčnosti tohto súboru rozhoduje niekoľko pravidiel:
filesje explicitný zoznam. CLI sťahuje presne tieto cesty a nič iné. Nepoužívajú sa zástupné znaky, takže nový súbor sa zahrnie až po jeho pridaní sem. Cesty môžu obsahovať podadresáre, ktoré sa pri inštalácii vytvoria.baseUrlmusí byť absolútna URL. CLI ju overí ako URL a relatívne hodnoty odmietne. Súbory blokov sa vždy načítavajú zbaseUrl, nikdy z umiestnenia vzhľadom na miesto, odkiaľ sa načítaloregistry.json.dependenciespomenúvajú bloky v tom istom registri. Pridanímtabssa najprv nainštalujetab-item. Chýbajúce a kruhové závislosti inštaláciu zastavia chybou.nameje povinný, ale nezobrazuje sa. Príkazy a výstup používajú kľúč, ktorý používateľ zadá registru vblocks.json; nemusí sa zhodovať.typeslúži iba na informáciu. Prijímablockstudio,create-blockalebowordpressa nemení správanie CLI.
CLI pri každom načítaní overí celý súbor a nahlási každé pole s chybou,
takže preklep sa odhalí ešte pred stiahnutím súborov. Riadok $schema poskytuje
tie isté kontroly v editore.
Krok 4: Publikovanie cez nespracované adresy URL
Potvrďte zmeny a odošlite úložisko do GitHub. Každý súbor vo verejnom úložisku bude dostupný na adrese:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> je vetva, značka alebo SHA potvrdenia. Pre tento register sú dôležité dve
adresy URL:
- Adresa URL registra URL, ktorú nastavia používatelia:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrlvregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
S týmto baseUrl sa index.php v hero načíta z
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Surový hostiteľ vracia obsah súboru namiesto stránky GitHub HTML, ktorú
CLI potrebuje. Nesprávny vlastník, úložisko alebo referencia sa prejaví ako 404 pri
prvom príkaze:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Krok 5: Inštalácia blokov do témy
V koreňovom priečinku témy, ktorá bloky používa, vytvorte blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes vytvorí prázdny objekt registries. Pridajte register pod
menným priestorom, ktorý chcete zadávať v príkazoch:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Spustite init bez --yes v termináli a na tie isté otázky
(umiestnenie priečinka s blokmi, názvy registrov a adresy URL) odpovedzte interaktívne.
Skontrolujte, či sa register správne načíta:
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 vyhľadáva podreťazec bez rozlišovania veľkých a malých písmen v názvoch, titulkoch a
opisoch:
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.
Náhľad inštalácie zobrazíte pomocou --dry-run. Závislosť je uvedená ako prvá, pretože
sa inštaluje ako prvá:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Potom vykonajte samotnú inštaláciu:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Oba priečinky sa teraz nachádzajú v priečinku blockstudio témy, presne tak, ako
sú uložené v úložisku:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Menný priestor môžete vynechať, ak má blok iba jeden nakonfigurovaný register, a môžete zadať viacero blokov naraz:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio nájde nové priečinky rovnako ako každý iný blok v téme.
Aktualizácia nainštalovaných blokov
Nainštalované súbory sú kópiou. Nesleduje sa, ktorú verziu ste nainštalovali, a CLI nikdy neaktualizuje blok samostatne. Ak chcete získať novšiu verziu, pridajte blok znova. Ak nie je k dispozícii terminál alebo sa príkaz spúšťa v CI, existujúci priečinok vykonanie príkazu zastaví:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
V termináli sa CLI najprv opýta, či chcete súbory prepísať. --dry-run vypíše
priečinky, ktoré by nahradil, a --yes ich nahradí:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Prepísaním sa uvedené súbory nahradia verziou z registra. Preto najprv potvrďte
miestne zmeny a výsledok skontrolujte pomocou git diff.
Ak chcete blok odinštalovať, odstráňte priečinok podľa názvu:
npx blockstudio remove tabs --yes
Removed tabs
remove preberá názov priečinka, nie namespace/block. Závislosti neodstraňuje, takže
tab-item zostane nainštalovaný aj po odstránení tabs.
Správa verzií pomocou referencií git
CLI nemá pole verzie ani príznak verzie. O tom, čo načíta, rozhodujú výlučne
adresy URL; na GitHub je referencia v URL verziou. Používateľ, ktorý nastaví
main, získa pri inštalácii obsah, ktorý tam práve v tom čase uchováva main.
Ak chcete zverejniť vydanie, ktoré zostane nemenné, aj registry.json v značke musí
načítavať súbory zo značky. Pred vytvorením značky nastavte baseUrl na jej hodnotu:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Potom potvrďte zmeny, vytvorte značku a odošlite ju:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Potom nastavte baseUrl späť na main a potvrďte zmeny, aby vetva naďalej
poskytovala aktuálne súbory. Ak preskočíte prvý krok, používateľ, ktorý si nastavil značku,
získa zoznam blokov zo značky, ale súbory stiahne z main.
Používatelia si nastavia konkrétnu verziu použitím značky v URL registra:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
V tomto príklade bola značka v1.0.0 vytvorená skôr, než vznikli tabs a tab-item, takže
register s touto pevne nastavenou verziou ponúka iba dva pôvodné bloky:
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".
V adrese URL registra funguje aj SHA potvrdenia URL, no potvrdenie nemôže obsahovať svoje vlastné
SHA v baseUrl. Nastavenie verzie pomocou SHA preto zafixuje zoznam blokov, zatiaľ čo súbory
sa naďalej načítavajú z referencie, ktorú uvádza baseUrl daného potvrdenia. Preto pri
vydaniach uprednostnite značky.
Na čo pamätať
- Najprv sa načítajú všetky registre.
addnačíta všetky registre vblocks.jsonešte predtým, ako čokoľvek vyrieši, takže ak je niektorý register nedostupný, príkaz zlyhá aj preacme/hero. Odstráňte registre, ktoré už nepoužívate. - Nejednoznačné názvy vyžadujú menný priestor. Ak majú dva registre položku
hero, terminálová relácia sa opýta, ktorú použiť,--yesvyberie prvú v poradíblocks.jsona neinteraktívne spustenie skončí s kódomBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Súkromné repozitáre vyžadujú hlavičky. Použite objektovú podobu položky registra s
urlaheaders. Hodnoty hlavičiek podporujú zástupné symboly${VAR}, ktoré sa načítavajú z prostredia, a CLI odosiela hlavičky pri načítaní registra aj pri každom sťahovaní súboru. Nastavenie tokenu nájdete v dokumentácii hostingu GitHub.
Ďalšie kroky
- Prehľad registra: čo je register a ako funguje CLI
- registry.json: všetky polia manifestu
- blocks.json: konfigurácia používateľa, overovanie a zisťovanie konfigurácie
- pridať: riešenie menných priestorov, závislosti a správanie pri prepísaní
- GitHubhosting: GitHub Pages a súkromné úložiská
- Vlastný server: poskytovanie registra z vlastnej infraštruktúry