Plokiregistri avaldamine teenuses GitHub
Kui olete loonud mõned head plokid, soovite neid kasutada ka järgmises projektis. Kaustade käsitsi teemade vahel kopeerimine toimib seni, kuni koopiad lahknevad ja keegi ei mäleta, millises teemas on parandatud versioon. Iga ploki pakkimine oma koostamisprotsessiga paketti on liigne formaalsus kausta jaoks, mis sisaldab block.json-i ja malli.
Plokiregister pakub vahepealset lahendust. See koosneb registry.json failist ja plokikaustade komplektist, mida teenindatakse lihtsa HTTP kaudu. Kasutajad käivitavad käsu CLI, ploki lähtekood kopeeritakse nende teemasse ja edaspidi haldavad nad seda koopiat ise. Ühe majutamiseks piisab repositooriumist GitHub, sest GitHub teenindab avaliku repositooriumi iga faili töötlemata URL-il.
Selles juhendis luuakse register nimega acme, mis sisaldab nelja plokki; avaldatakse see repositooriumist acme/acme-blocks, installitakse selle plokid teemasse ja kinnitatakse väljalase git-sildiga.
Paketi blockstudio versioon 0.0.1 teenuses npm on praegu saadaval. See väljalase on kohatäide: selle ainus käsk add väljastab Adding block: <name> ja lõpetab töö midagi alla laadimata. Selle juhendi käsud ja väljund pärinevad registrist CLI repositooriumis Blockstudio (packages/registry), mida registri dokumentatsioon kirjeldab kui CLI.
Kuidas osad kokku sobituvad
Oluline on teada kahte faili:
- Ploki autor avaldab faili
registry.json. Selles on kirjas plokid, igasse plokki kuuluvad failid jabaseUrl, kust need alla laadida. blocks.jsonasub kasutaja teemas või lisandmoodulis. Selles nimetatakse kasutatavad registrid ja kataloog, kuhu plokid installitakse.
Ploki installimisel laadib CLI alla kõik failis blocks.json loetletud registrid, leiab ploki, lahendab selle sõltuvused, laadib iga loetletud faili alla asukohast {baseUrl}/{block}/{file} ja kirjutab selle asukohta {directory}/{block}/{file}. Midagi ei teisendata, seega on kettal olevad failid täpselt samad mis repositooriumis.
1. samm: repositooriumi struktuur
Looge repositoorium, mille juurkaustas on registry.json ja kataloogis blocks/ iga ploki jaoks eraldi kaust:
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
Kausta nimi on registris ploki nimi ja sellest saab kasutaja teemas oleva kausta nimi. Jätke see samaks ploki nime teise poolega failis block.json (acme/hero asub kataloogis hero/), et installitud kausta oleks lihtne ära tunda.
2. samm: kirjutage plokid
Iga kaust sisaldab tavalist Blockstudio plokki. Päiseplokil on üks väli:
{
"$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 järgib sama mustrit ja lisab välja style.scss. tabs renderdab <InnerBlocks allowedBlocks='["acme/tab-item"]' /> ja tab-item deklareerib "parent": ["acme/tabs"], seega pole tabs ilma tab-item-ta kasulik. Register kirjeldab seda seost järgmises etapis.
Nendes plokkides pole midagi registripõhist. CLI kopeerib kaustad, seega saab samamoodi avaldada ploki, mis on loodud @wordpress/create-block abil või registreeritud tavapärase PHP-ga.
3. samm: kirjutage registry.json
registry.json loetleb kõik plokid ja failid, mille CLI alla peab laadima:
{
"$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"]
}
]
}
Mõned reeglid määravad, kas see fail töötab:
fileson selgesõnaline loend. CLI laadib alla täpselt need teed ega midagi muud. Metamärke ei kasutata, seega lisatakse uus vara alles siis, kui lisate selle siia. Teed võivad sisaldada alamkaustu, mis installimisel luuakse.baseUrlpeab olema absoluutne URL. CLI valideerib selle kui URL ja lükkab suhtelised väärtused tagasi. Plokifailid hangitakse alati asukohastbaseUrl, mitte kohast, mis on suhteline selle asukohaga, kustregistry.jsonlaaditi.dependenciesnimetavad plokke samas registris.tabslisamine installib esmalttab-item. Puuduvad ja ringikujulised sõltuvused peatavad installimise veaga.nameon nõutav, kuid seda ei kuvata. Käskudes ja väljundis kasutatakse võtit, mille tarbija annab registrileblocks.json; see ei pea sellega ühtima.typeon informatiivne. See aktsepteerib väärtusiblockstudio,create-blockvõiwordpressega muuda seda, mida CLI teeb.
CLI valideerib kogu faili igal allalaadimisel ja teatab igast vigasest väljast, nii et kirjaviga tuleb ilmsiks enne ühegi faili allalaadimist. Rida $schema teeb samad kontrollid teie redaktoris.
4. samm: avaldamine toor-URL-ide kaudu
Salvestage hoidla muudatused ja laadige need üles asukohta GitHub. Seejärel on kõik avaliku hoidla failid saadaval aadressil:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> on haru, silt või sissekande SHA. Selle registri puhul on olulised kaks URL-i:
- Registri URL, mille tarbijad seadistavad:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrlasukohasregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Selle baseUrl abil hangitakse index.php hero-i https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php kaudu.
Toorhost tagastab faili sisu, mitte GitHub HTML-i lehe, mida CLI vajab. Vale omanik, hoidla või viide annab juba esimese käsu käivitamisel tulemuseks 404:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
5. samm: plokkide installimine teemasse
Looge tarbiva teema juurkaustas blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes loob tühja objekti registries. Lisage register selle nimeruumi alla, mida soovite käskudes kasutada:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Käivitage terminalis init ilma argumendita --yes, et vastata samadele küsimustele interaktiivselt (plokikaust, registrite nimed ja URL-id).
Kontrollige, kas register leitakse:
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 otsib nimede, pealkirjade ja kirjelduste seast tõstutundetut osalist vastet:
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.
Vaadake installi eelvaadet käsuga --dry-run. Sõltuvus kuvatakse esimesena, sest see installitakse esimesena:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Seejärel installige päriselt:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Mõlemad kaustad asuvad nüüd teema kataloogis blockstudio täpselt samamoodi nagu hoidlas:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Kui plokk on ainult ühes seadistatud registris, võite nimeruumi ära jätta ja anda korraga mitu plokki:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio leiab uued kaustad nagu kõik teisedki teemas olevad plokid.
Installitud plokkide värskendamine
Installitud failid on koopiad. Ükski mehhanism ei jälgi, millise versiooni installisite, ja CLI ei värskenda plokke kunagi ise. Uuema versiooni hankimiseks lisage plokk uuesti. Ilma terminalita või CI-s peatab olemasolev kaust käsu:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Terminalis küsib CLI enne ülekirjutamist luba. --dry-run loetleb kaustad, mille see asendaks, ja --yes asendab need:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Ülekirjutamisel asendatakse loetletud failid registri versiooniga, seega salvestage kohalikud muudatused esmalt ja vaadake tulemus üle käsuga git diff.
Desinstallimiseks eemaldage kaust nime järgi:
npx blockstudio remove tabs --yes
Removed tabs
remove kasutab kausta nime, mitte namespace/block. See ei eemalda sõltuvusi, seega jääb tab-item installituks ka pärast tabs eemaldamist.
Versioonimine git-viidetega
CLI-il pole versioonivälja ega versioonilippu. Allalaaditava määravad täielikult URL-id ning asukohas GitHub on versiooniks viide URL-is. Tarbija, kes viitab asukohale main, saab installimise ajal selle, mida main sisaldab.
Püsiva väljalaske avaldamiseks peab sildil olev registry.json samuti sildilt alla laadima. Enne sildi loomist määrake baseUrl selleks sildiks:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Seejärel salvestage muudatused, looge silt ja laadige need üles:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Pärast seda määrake baseUrl tagasi väärtusele main ja salvestage muudatused, et haru jätkaks praeguste failide pakkumist. Kui jätate esimese sammu vahele, saab sildile kinnitatud tarbija sildistatud plokkide loendi, kuid hangib failid asukohast main.
Tarbija kinnitab versiooni, kasutades oma registri URL-is silti:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Selles näites märgistati v1.0.0 enne kui tabs ja tab-item olemas olid, seega pakub kinnitatud register ainult kaht algset plokki:
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".
Sissekande SHA töötab ka registri URL-is, kuid sissekanne ei saa sisaldada iseenda SHA-d kohas baseUrl. Seega fikseerib SHA järgi kinnitamine plokkide loendi, kuid failid pärinevad endiselt selle viite alt, mille sissekande baseUrl nimetab. Väljalasete puhul eelistage seepärast silte.
Meelespea
- Kõik registrid hangitakse esmalt.
addlaadib kõik registrid asukohasblocks.jsonenne, kui midagi lahendama hakkab, nii et üks kättesaamatu register paneb käsu nurjuma isegi juhul, kui käsk on mõeldudacme/herojaoks. Eemaldage registrid, mida te enam ei kasuta. - Mitmetähenduslikud nimed vajavad nimeruumi. Kui kahes registris on
hero, küsib terminaliseanss, kumba kasutada;--yesvalib järjekorras esimese asukohasblocks.jsonning mitteinteraktiivne käivitus lõpeb veagaBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Privaathoidlad vajavad päiseid. Kasutage registrikirje objektivormi koos
urljaheaders-ga. Päiseväärtustes saab kasutada${VAR}kohatäitjaid, mille väärtused loetakse keskkonnast, ning CLI saadab päised nii registri päringuga kui ka iga faili allalaadimisel. Loa seadistamise kohta vaadake teavet lehelt GitHub hosting.
Järgmised sammud
- Registri ülevaade: mis register on ja kuidas CLI töötab
- registry.json: manifesti kõik väljad
- blocks.json: tarbija seadistus, autentimine ja seadistuse tuvastamine
- add: nimeruumi lahendamine, sõltuvused ja ülekirjutamine
- GitHub hosting: GitHub Pages ja privaathoidlad
- Kohandatud server: registri teenindamine teie enda taristus