Blokų registro publikavimas platformoje GitHub
Sukūrus kelis gerus blokus, norisi juos panaudoti ir kitame projekte. Rankiniu būdu kopijuoti aplankus iš vienos temos į kitą veikia tol, kol kopijos ima skirtis ir niekas nebeprisimena, kurioje temoje yra pataisyta versija. Kiekvieną bloką supakuoti į atskirą paketą su savo kūrimo procesu – daug papildomų veiksmų dėl aplanko, kuriame yra block.json ir šablonas.
Blokų registras užima tarpinę vietą. Tai registry.json failas ir blokų aplankų rinkinys, pateikiami paprastu HTTP protokolu. Naudotojai paleidžia komandą CLI, bloko šaltinio failai nukopijuojami į jų temą, o nuo tada jie tvarko tą kopiją patys. Registrui talpinti pakanka GitHub saugyklos, nes GitHub pateikia kiekvieną viešos saugyklos failą neapdorotu URL adresu.
Šiame vadove sukursime registrą acme su keturiais blokais, paskelbsime jį saugykloje acme/acme-blocks, įdiegsime iš jo blokus į temą ir prisegsime leidimą naudodami git žymą.
Paketo blockstudio versija 0.0.1 platformoje npm jau paskelbta. Tai tik vietos rezervavimo leidimas: vienintelė jo komanda add išveda Adding block: <name> ir baigia darbą nieko neatsiuntusi. Šiame vadove pateikiamos komandos ir jų išvestis yra iš registro CLI, esančio saugykloje Blockstudio (packages/registry). Tai CLI, kurį aprašo Registro dokumentacija.
Kaip susiję komponentai
Reikia žinoti du failus:
registry.jsonpublikuoja blokų autorius. Jame išvardyti blokai, kiekvieno bloko failai irbaseUrl, iš kur jų atsisiųsti.blocks.jsonlaikomas naudotojo temoje arba įskiepyje. Jame nurodyti naudotini registrai ir katalogas, į kurį diegiami blokai.
Įdiegus bloką, CLI atsisiunčia kiekvieną registre, nurodytame faile blocks.json, esantį elementą, suranda bloką, išsprendžia jo priklausomybes, atsisiunčia kiekvieną failą iš {baseUrl}/{block}/{file} ir įrašo jį į {directory}/{block}/{file}. Nieko netransformuoja, todėl diske esantys failai yra tiksliai tokie, kaip ir saugykloje.
1 žingsnis: sutvarkykite saugyklą
Sukurkite saugyklą su registry.json šakniniame kataloge ir po vieną aplanką kiekvienam blokui kataloge 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
Aplanko pavadinimas yra bloko pavadinimas registre; jis tampa ir aplanko pavadinimu naudotojo temoje. Sutapatinkite jį su antrąja bloko pavadinimo dalimi faile block.json (acme/hero yra hero/), kad įdiegtą aplanką būtų lengva atpažinti.
2 žingsnis: parašykite blokus
Kiekviename aplanke yra įprastas Blockstudio blokas. Pagrindinės sekcijos blokas turi vieną lauką:
{
"$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 laikosi to paties šablono ir prideda style.scss. tabs atvaizduoja <InnerBlocks allowedBlocks='["acme/tab-item"]' />, o tab-item deklaruoja "parent": ["acme/tabs"], todėl be tab-item naudoti tabs nėra prasminga. Šį ryšį registre aprašysime kitame žingsnyje.
Šiuose blokuose nėra nieko, kas būtų skirta tik registrui. CLI kopijuoja aplankus, todėl tokiu pačiu būdu galima paskelbti ir bloką, sukurtą naudojant @wordpress/create-block arba užregistruotą įprastu PHP.
3 žingsnis: parašykite registry.json
registry.json išvardija kiekvieną bloką ir visus failus, kuriuos turi atsisiųsti 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"]
}
]
}
Ar šis failas veiks, lemia kelios taisyklės:
filesyra aiškus sąrašas. CLI atsisiunčia tiksliai šiuos kelius ir nieko daugiau. Šablonai nenaudojami, todėl naujas išteklius bus įtrauktas tik pridėjus jį čia. Keliuose gali būti pakatalogių, kurie sukuriami diegiant.baseUrlturi būti absoliutus URL. CLI jį patikrina kaip URL ir atmeta santykines reikšmes. Blokų failai visada gaunami išbaseUrl, o ne iš vietos, santykinės tai vietai, iš kurios įkeltasregistry.json.dependenciesturi nurodyti blokus tame pačiame registre. Pridėjustabs, pirmiausia įdiegiamastab-item. Dėl trūkstamų ar ciklinių priklausomybių diegimas sustabdomas ir pateikiama klaida.nameyra būtinas, bet nerodomas. Komandose ir išvestyje naudojamas raktas, kurį naudotojas priskiria registrui perblocks.json; jis gali skirtis.typeyra informacinis. Galimos reikšmės:blockstudio,create-blockarbawordpress; jos nekeičia, ką daro CLI.
CLI kiekvieną kartą gaudamas failą patikrina visą jo turinį ir praneša apie
kiekvieną klaidingą lauką, todėl rašybos klaida išryškėja dar prieš atsisiunčiant
bet kokį failą. $schema eilutėje pateikiami tie patys patikrinimai jūsų redaktoriuje.
4 veiksmas: paskelbkite per neapdoroto turinio URL
Pateikite saugyklos pakeitimus ir nusiųskite juos į GitHub. Tada kiekvienas viešos saugyklos failas pasiekiamas adresu:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> yra šaka, žyma arba pakeitimo SHA. Šiame registre svarbūs du URL:
- Registro URL, kurį sukonfigūruoja naudotojai:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrlišregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Naudojant šį baseUrl, hero gaunamas iš https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
index.php.
Neapdoroto turinio priegloba grąžina failo turinį, o ne GitHub HTML puslapį,
kurio reikia CLI. Neteisingas savininkas, saugykla ar nuoroda išryškės kaip
404 jau paleidus pirmąją komandą:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
5 veiksmas: įdiekite blokus temoje
Vartotojo temos šakniniame kataloge sukurkite blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes įrašo tuščią registries objektą. Įtraukite registrą į vardų sritį,
kurią norite rašyti komandose:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Paleiskite init terminale be --yes, kad interaktyviai atsakytumėte į tuos
pačius klausimus apie blokų katalogą, registrų pavadinimus ir URL.
Patikrinkite, ar registras randamas:
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 ieško didžiųjų ir mažųjų raidžių neskirdamas, ar pavadinimuose,
antraštėse ir aprašuose yra nurodyta eilutė:
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.
Peržiūrėkite diegimą naudodami --dry-run. Priklausomybė pateikiama pirma,
nes ji įdiegiama pirmiausia:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Dabar įdiekite:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Abu aplankai dabar yra temos blockstudio kataloge, tiksliai tokie patys kaip
saugykloje:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Kai bloką turi tik vienas sukonfigūruotas registras, vardų srities nurodyti nereikia; vienu metu galima perduoti kelis blokus:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio aptinka naujus aplankus kaip ir kitus temos blokus.
Įdiegtų blokų atnaujinimas
Įdiegti failai yra kopija. Nei įdiegta versija nėra sekama, nei CLI pats atnaujina blokus. Norėdami gauti naujesnę versiją, pridėkite bloką dar kartą. Jei terminalo nėra arba naudojama CI, komandą sustabdo jau esantis aplankas:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Terminale CLI vietoj to paklausia, ar perrašyti. --dry-run pateikia aplankus,
kuriuos pakeistų, o --yes juos pakeičia:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Perrašant nurodyti failai pakeičiami registro versija, todėl pirmiausia
įrašykite vietinius pakeitimus į Git, o tada peržiūrėkite rezultatą naudodami git diff.
Norėdami pašalinti bloką, ištrinkite aplanką pagal pavadinimą:
npx blockstudio remove tabs --yes
Removed tabs
remove priima aplanko pavadinimą, o ne namespace/block. Priklausomybės nepašalinamos,
todėl pašalinus tabs, tab-item lieka įdiegtas.
Versijų valdymas naudojant git nuorodas
CLI neturi nei versijos lauko, nei versijos parinkties. Tai, ką jis gauna,
visiškai priklauso nuo URL, o naudojant GitHub, URL nurodyta nuoroda yra
versija. Nurodžius main, diegimo metu gaunama tai, ką tuo metu turi main.
Norint paskelbti nekintantį leidimą, žymos registry.json taip pat turi siųstis iš
žymos. Prieš sukurdami žymą, nustatykite baseUrl į žymą:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Tada įrašykite pakeitimus, sukurkite žymą ir nusiųskite ją:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Vėliau vėl nustatykite baseUrl į main ir įrašykite pakeitimus, kad šaka
ir toliau teiktų naujausius failus. Jei praleisite pirmąjį veiksmą, žymą
nurodęs naudotojas gaus pažymėtą blokų sąrašą, bet failai bus atsisiųsti iš main.
Naudotojai užfiksuoja versiją savo registro URL nurodydami žymą:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Šiame pavyzdyje v1.0.0 buvo pažymėtas dar neegzistuojant tabs ir tab-item,
todėl užfiksuotame registre siūlomi tik du pradiniai blokai:
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".
Registro URL taip pat tinka pakeitimo SHA, tačiau pakeitime negali būti
savo SHA lauko baseUrl. Todėl SHA fiksuoja blokų sąrašą, o failai vis tiek
gaunami iš tos nuorodos, kurią nurodo to pakeitimo baseUrl. Dėl to leidimams
verčiau naudoti žymas.
Ką verta turėti omenyje
- Pirmiausia gaunamas kiekvienas registras.
addįkelia visusblocks.jsonesančius registrus prieš ką nors išspręsdamas, todėl dėl nepasiekiamo registro komanda nepavyks net ir naudojantacme/hero. Pašalinkite nebenaudojamus registrus. - Dviprasmiškiems pavadinimams reikia vardų srities. Jei tą patį
heroturi du registrai, terminalo seanso metu paklausiama, kurį naudoti,--yespasirenka pirmąjį pagalblocks.jsontvarką, o neinteraktyvus paleidimas baigiasi suBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Privačioms saugykloms reikia antraščių. Naudokite registro įrašo objekto
formą su
urlirheaders. Antraščių reikšmėse galima naudoti${VAR}vietos rezervavimo ženklus, kurių reikšmės nuskaitomos iš aplinkos. CLI siunčia antraštes gaudamas registrą ir atsisiųsdamas kiekvieną failą. Žr. GitHubGitHub privačių saugyklų prieglobos instrukcijas apie žetonų sąranką.
Tolesni veiksmai
- Registro apžvalga: kas yra registras ir kaip veikia CLI
- registry.json: visi aprašo laukai
- blocks.json: naudotojo konfigūracija, autentifikavimas ir konfigūracijos aptikimas
- pridėjimas: vardų sričių parinkimas, priklausomybės ir perrašymo elgsena
- GitHubGitHub privačių saugyklų priegloba: GitHub Pages ir privačios saugyklos
- Pasirinktinis serveris: registro teikimas iš savo infrastruktūros