Blokkregiszter közzététele itt: GitHub
Miután elkészített néhány jó blokkot, a következő projektben is használni szeretné őket. A mappák kézi másolása a témák között addig működik, amíg a másolatok el nem térnek, és senki sem emlékszik, melyik témában van a javított változat. Minden blokk saját builddel rendelkező csomagba foglalása túl sok formaság egy olyan mappáért, amely egy block.json fájlt és egy sablont tartalmaz.
A blokkregiszter a kettő között helyezkedik el. Ez egy registry.json fájl és blokkmappák gyűjteménye, amelyet egyszerű HTTP protokollon szolgálnak ki. A felhasználók egy CLI parancsot futtatnak, a blokk forrása bekerül a témájukba, és onnantól ők kezelik ezt a másolatot. Egy GitHub-tároló elegendő a regiszter tárolására, mivel az GitHub minden nyilvános tároló fájljait elérhetővé teszi nyers URL-címen.
Ez az útmutató létrehoz egy acme nevű regisztert négy blokkal, közzéteszi a acme/acme-blocks tárolóból, telepíti belőle a blokkokat egy témába, majd egy git címkével rögzít egy kiadást.
Az npm webhelyen található blockstudio csomag verziója 0.0.1. Ez a kiadás helyőrző: egyetlen parancsa, az add, kiírja ezt: Adding block: <name>, majd bármi letöltése nélkül kilép. Az útmutatóban szereplő parancsok és kimenetek a Blockstudio tároló CLI regiszteréből származnak (packages/registry), amely az az CLI, amelyet a Regiszter dokumentációja ismertet.
Hogyan illeszkednek egymáshoz az elemek
Két fájlt kell ismernie:
- Az
registry.jsonfájlt a blokk szerzője teszi közzé. Felsorolja a blokkokat, az egyes blokkok fájljait és a letöltésükhöz használtbaseUrlcímet. - Az
blocks.jsonfájl a felhasználó témájában vagy bővítményében található. Megadja a használandó regisztereket és azt a könyvtárat, ahová a blokkok települnek.
Blokk telepítésekor az CLI lekéri az blocks.json fájlban szereplő összes regisztert, megkeresi a blokkot, feloldja a függőségeit, letölti a felsorolt fájlokat innen: {baseUrl}/{block}/{file}, majd ide írja őket: {directory}/{block}/{file}. Semmit sem alakít át, így a lemezen lévő fájlok pontosan megegyeznek a tárolóban lévőkkel.
1. lépés: A tároló felépítése
Hozzon létre egy tárolót, amelynek gyökerében egy registry.json fájl található, az blocks/ mappában pedig minden blokknak saját mappája van:
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
A mappa neve a blokk regiszterbeli neve lesz, és a felhasználó témájában is ez lesz a mappanév. Egyezzen meg pontosan a block.json blokknevének második felével (az acme/hero helye: hero/), így könnyű lesz felismerni a telepített mappát.
2. lépés: A blokkok megírása
Minden mappa egy hagyományos Blockstudio blokkot tartalmaz. A hero blokk egy mezővel rendelkezik:
{
"$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>
Az card ugyanazt a mintát követi, és hozzáad egy style.scss elemet. Az tabs rendereli az <InnerBlocks allowedBlocks='["acme/tab-item"]' /> elemet, az tab-item pedig deklarálja ezt: "parent": ["acme/tabs"], ezért az tabs nem használható az tab-item nélkül. A regiszter a következő lépésben fejezi ki ezt a kapcsolatot.
Ezek a blokkok nem függnek a regisztertől. Az CLI mappákat másol, így a @wordpress/create-block használatával készült vagy egyszerű PHP segítségével regisztrált blokk ugyanígy közzétehető.
3. lépés: Az registry.json megírása
Az registry.json felsorolja az összes blokkot és minden fájlt, amelyet az CLI-nek le kell töltenie:
{
"$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"]
}
]
}
Néhány szabály határozza meg, hogy ez a fájl működik-e:
- A
filesexplicit lista. A CLI pontosan ezeket az útvonalakat tölti le, és semmi mást. Nincs globbing, ezért egy új eszköz csak akkor kerül bele, ha itt hozzáadod. Az útvonalak alkönyvtárakat is tartalmazhatnak, amelyeket a rendszer telepítéskor létrehoz. - A
baseUrlértékének abszolút URL-nek kell lennie. A CLI URL-ként ellenőrzi, és elutasítja a relatív értékeket. A blokkfájlok mindig abaseUrlhelyről töltődnek le, soha nem onnan, ahová aregistry.jsonfájlt betöltötték. - A
dependenciesugyanabban a nyilvántartásban nevezik meg a blokkokat. Atabshozzáadásakor először atab-itemtelepül. A hiányzó és körkörös függőségek hibaüzenettel megszakítják a telepítést. - A
namekötelező, de nem jelenik meg. A parancsok és a kimenet azt a kulcsot használják, amelyet a fogyasztó a nyilvántartásnak ablocks.jsonfájlban megad; ennek nem kell egyeznie. - A
typetájékoztató jellegű. Elfogadja ablockstudio,create-blockvagywordpressértéket, és nem változtat azon, hogy mit csinál a CLI.
A CLI minden lekéréskor ellenőrzi a teljes fájlt, és megadja az összes hibás mezőt, így az elírás még bármely fájl letöltése előtt kiderül. A $schema sor ugyanezeket az ellenőrzéseket biztosítja a szerkesztőben.
4. lépés: Közzététel nyers URL-eken keresztül
Véglegesítsd és küldd fel a tárházat a GitHub helyre. Egy nyilvános tárház minden fájlja ezután itt érhető el:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
A <ref> lehet ág, címke vagy commit SHA. Ennél a nyilvántartásnál két fontos URL van:
- A nyilvántartás URL címe, amelyet a fogyasztók konfigurálnak:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json - A
baseUrlhelye aregistry.jsonfájlban:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Ezzel a baseUrl értékkel a hero index.php-je a következő helyről töltődik le:
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
A nyers tárhely a fájl tartalmát adja vissza a GitHub HTML oldal helyett, erre van szüksége a CLI eszköznek. A hibás tulajdonos, tárház vagy ref már az első parancsnál 404 hibát okoz:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
5. lépés: Blokkok telepítése egy témába
A fogyasztó témájának gyökérkönyvtárában hozd létre ezt: blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
A init --yes egy üres registries objektumot ír ki. Add hozzá a nyilvántartást a kívánt parancsnévtér alatt:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Ha terminálban, --yes nélkül futtatod a init parancsot, ugyanezekre a kérdésekre interaktívan válaszolhatsz (blokk könyvtára, nyilvántartásnevek és URL-ek).
Ellenőrizd, hogy a nyilvántartás feloldható-e:
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
A search kis- és nagybetűtől független részszövegre keres a nevekben, címekben és leírásokban:
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.
Telepítés előnézetéhez használd a --dry-run parancsot. A függőség jelenik meg először, mert azt telepíti először:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Ezután végezd el a telepítést:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Most mindkét mappa a téma blockstudio könyvtárában található, pontosan úgy, ahogy a tárházban:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Ha a blokk csak egy konfigurált nyilvántartásban szerepel, elhagyhatod a névteret, és egyszerre több blokkot is megadhatsz:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
A Blockstudio ugyanúgy megtalálja az új mappákat, mint a téma bármely más blokkját.
Telepített blokkok frissítése
A telepített fájlok másolatok. Semmi nem követi, melyik verziót telepítetted, és a CLI soha nem frissíti önállóan a blokkokat. Újabb verzió letöltéséhez add hozzá újra a blokkot. Terminál nélkül vagy CI-ben a meglévő mappa leállítja a parancsot:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Terminálban a CLI ehelyett rákérdez a felülírásra. A --dry-run felsorolja a lecserélendő mappákat, a --yes pedig lecseréli őket:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Felülíráskor a felsorolt fájlok a nyilvántartásban lévő verzióra cserélődnek, ezért előbb véglegesítsd a helyi módosításokat, majd a git diff paranccsal nézd át az eredményt.
Eltávolításhoz töröld a mappát a neve alapján:
npx blockstudio remove tabs --yes
Removed tabs
A remove a mappa nevét kéri, nem a namespace/block értékét. A függőségeket nem távolítja el, így a tab-item a tabs eltávolítása után is telepítve marad.
Verziókezelés git-hivatkozásokkal
A CLI nem tartalmaz verziómezőt vagy verziójelzőt. A letöltött tartalmat teljes egészében az URL-ek határozzák meg, a GitHub esetében pedig a URL-ben megadott ref jelöli a verziót. Ha a fogyasztó a main értékre mutat, azt kapja, amit a main a telepítés időpontjában tartalmaz.
Egy változatlan kiadás közzétételéhez a címkéhez tartozó registry.json-nak is a címkéről kell letöltenie. Címkézés előtt állítsd a baseUrl értékét a címkére:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Ezután véglegesítsd, címkézd és küldd fel:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Utána állítsd vissza a baseUrl értékét erre: main, majd véglegesítsd a módosítást, hogy az ág továbbra is az aktuális fájlokat szolgálja ki. Ha kihagyod az első lépést, a címkéhez rögzített fogyasztó a címkézett blokkok listáját kapja, de a fájlokat a main refből tölti le.
A fogyasztók úgy rögzítenek verziót, hogy a címkét használják a nyilvántartásuk URL értékeként:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Ebben a példában a v1.0.0 címkézése a tabs és tab-item létrehozása előtt történt, ezért a rögzített nyilvántartás csak az eredeti két blokkot kínálja:
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".
A nyilvántartás URL értéke commit SHA is lehet, de egy commit nem tartalmazhatja a saját SHA-ját a baseUrl fájlban. A SHA szerinti rögzítés ezért a blokkok listáját rögzíti, miközben a fájlok továbbra is attól a reftől érkeznek, amelyet az adott commit baseUrl értéke megad. Kiadásokhoz ezért inkább címkéket használj.
Amit érdemes észben tartani
- Először minden nyilvántartás lekérése történik. A
addbetölti ablocks.jsonösszes nyilvántartását, mielőtt bármit feloldana, ezért egy elérhetetlen nyilvántartás miatt a parancs akkor is hibával leáll, ha aacme/hero-ről van szó. Távolítsd el a már nem használt nyilvántartásokat. - Kétértelmű nevekhez névtér szükséges. Ha két nyilvántartásban is szerepel a
hero, a terminálos munkamenet megkérdezi, melyiket használja; a--yesablocks.jsonsorrendben az elsőt választja, a nem interaktív futtatás pedigBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/herohibával leáll. - A privát tárházakhoz fejlécek szükségesek. A nyilvántartás bejegyzéséhez használd az objektumformátumot a
urlésheadersmezővel. A fejlécértékek környezeti változókból beolvasott${VAR}helyőrzőket fogadnak el, a CLI pedig a nyilvántartás lekérésekor és minden fájl letöltésekor is elküldi a fejléceket. A token beállításához lásd a GitHub tárhely útmutatóját.
Következő lépések
- Nyilvántartási áttekintés: mi a nyilvántartás, és hogyan működik a CLI
- registry.json: a jegyzékfájl minden mezője
- blocks.json: fogyasztói konfiguráció, hitelesítés és konfigurációfelderítés
- hozzáadás: névtérfeloldás, függőségek és felülírási viselkedés
- GitHub tárhely: GitHub Pages és privát tárházak
- Egyéni szerver: nyilvántartás kiszolgálása saját infrastruktúráról