Bloku reģistra publicēšana vietnē GitHub
Kad esat izveidojis dažus labus blokus, vēlaties tos izmantot arī nākamajā projektā. Manuāla mapju kopēšana starp motīviem darbojas, līdz kopijas sāk atšķirties un neviens vairs neatceras, kurā motīvā ir labotā versija. Iepakot katru bloku atsevišķā pakotnē ar savu būvēšanas procesu ir pārāk sarežģīti mapei, kurā ir block.json un veidne.
Bloku reģistrs ir starpposms. Tas ir registry.json fails un bloku mapju kopa, kas tiek apkalpota, izmantojot parastu HTTP. Lietotāji izpilda komandu CLI, bloka avota faili tiek kopēti viņu motīvā, un no tā brīža šī kopija pieder viņiem. Reģistra uzturēšanai pietiek ar GitHub repozitoriju, jo GitHub apkalpo katru publiskā repozitorija failu neapstrādātā URL formā.
Šajā ceļvedī tiek izveidots reģistrs ar nosaukumu acme un četriem blokiem, tas tiek publicēts no repozitorija acme/acme-blocks, no tā instalēti bloki tēmā un piesaistīts laidiens, izmantojot git tagu.
Pakotnes blockstudio versija vietnē npm ir 0.0.1. Šis laidiens ir vietturis: tā vienīgā komanda add izvada Adding block: <name> un beidz darbu, neko neielādējot. Šajā ceļvedī norādītās komandas un izvade iegūtas no reģistra CLI repozitorijā Blockstudio (packages/registry), kas ir CLI, ko apraksta Reģistra dokumentācija.
Kā darbojas šīs daļas
Jāzina divi faili:
registry.jsonpublicē bloku autors. Tajā ir uzskaitīti bloki, faili, no kuriem katrs bloks sastāv, unbaseUrl, no kura tos lejupielādēt.blocks.jsonatrodas lietotāja motīvā vai spraudnī. Tajā norādīti izmantojamie reģistri un direktorijs, kurā instalēt blokus.
Instalējot bloku, CLI ielādē katru reģistru no blocks.json, atrod vajadzīgo bloku, atrisina tā atkarības, lejupielādē katru norādīto failu no {baseUrl}/{block}/{file} un saglabā to mapē {directory}/{block}/{file}. Faili netiek pārveidoti, tāpēc diskā saglabātie faili ir tieši tādi paši kā repozitorijā.
1. darbība: repozitorija struktūra
Izveidojiet repozitoriju, kura saknē ir registry.json un mapē blocks/ — pa vienai mapei katram blokam:
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
Mapes nosaukums ir bloka nosaukums reģistrā, un tas kļūst par mapes nosaukumu lietotāja motīvā. Saglabājiet to identisku bloka nosaukuma otrajai daļai failā block.json (acme/hero atrodas mapē hero/), lai instalēto mapi būtu viegli atpazīt.
2. darbība: bloku izveide
Katrā mapē ir parasts Blockstudio bloks. Galvenajam blokam ir viens lauks:
{
"$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 izmanto to pašu struktūru un pievieno style.scss. tabs renderē <InnerBlocks allowedBlocks='["acme/tab-item"]' />, bet tab-item deklarē "parent": ["acme/tabs"], tāpēc bez tab-item tabs nav noderīgs. Reģistrā šī saistība tiek norādīta nākamajā darbībā.
Šie bloki nekādā veidā nav īpaši pielāgoti reģistram. CLI kopē mapes, tāpēc tāpat var publicēt bloku, kas izveidots ar @wordpress/create-block vai reģistrēts, izmantojot parastu PHP.
3. darbība: registry.json izveide
Failā registry.json ir uzskaitīti visi bloki un faili, kas CLI jālejupielādē:
{
"$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"]
}
]
}
To, vai šis fails darbosies, nosaka daži noteikumi:
filesir precīzs saraksts. CLI lejupielādē tieši šos ceļus un neko citu. Globēšana nenotiek, tāpēc jauns resurss tiek iekļauts tikai tad, kad to pievienojat šeit. Ceļos var būt apakšdirektorijas, kuras tiek izveidotas instalēšanas laikā.baseUrljābūt absolūtam URL. CLI to pārbauda kā URL un noraida relatīvas vērtības. Bloku faili vienmēr tiek izgūti nobaseUrl, nevis no vietas, kas norādīta attiecībā pret to, no kuras tika ielādētsregistry.json.dependenciesnosauc blokus tajā pašā reģistrā. Pievienojottabs, vispirms tiek instalētstab-item. Trūkstošas un cirkulāras atkarības aptur instalēšanu ar kļūdu.nameir obligāts, bet netiek parādīts. Komandās un izvadē tiek izmantota atslēga, ko patērētājs norāda reģistramblocks.json, un tai nav obligāti jāsakrīt.typeir informatīvs. Tas pieņemblockstudio,create-blockvaiwordpress, un nemaina to, ko dara CLI.
CLI pārbauda visu failu katrā izgūšanas reizē un norāda katru kļūdaino lauku, tāpēc drukas kļūda tiek pamanīta, pirms lejupielādēts kāds fails. Rinda $schema nodrošina tās pašas pārbaudes redaktorā.
4. darbība: publicējiet, izmantojot neapstrādātos URL
Veiciet repozitorija komitu un nosūtiet izmaiņas uz GitHub. Pēc tam ikviens fails publiskajā repozitorijā būs pieejams šeit:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> ir atzars, tags vai komita SHA. Šim reģistram svarīgi ir divi URL:
- Reģistra URL, ko konfigurē patērētāji:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrliekšregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Izmantojot šo baseUrl, hero index.php tiek izgūts no
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Neapstrādāto failu resursdators atgriež faila saturu, nevis GitHub HTML lapu, kas nepieciešama CLI. Nepareizs īpašnieks, repozitorijs vai atsauce pirmajā komandā izraisa 404:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
5. darbība: instalējiet blokus motīvā
Patērētāja motīva saknes direktorijā izveidojiet blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes izveido tukšu registries objektu. Pievienojiet reģistru zem nosaukumvietas, ko vēlaties ievadīt komandās:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Lai terminālī interaktīvi atbildētu uz tiem pašiem jautājumiem (par bloku direktoriju, reģistru nosaukumiem un URL), palaidiet init bez --yes.
Pārbaudiet, vai reģistru izdodas atrast:
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 meklē nosaukumos, virsrakstos un aprakstos, izmantojot reģistrjutību neņemošu apakšvirkni:
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.
Priekšskatiet instalēšanu ar --dry-run. Atkarība ir norādīta pirmā, jo tā tiek instalēta pirmā:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Pēc tam instalējiet:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Tagad abas mapes atrodas motīva direktorijā blockstudio — tieši tāpat kā repozitorijā:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Ja bloks ir pieejams tikai vienā konfigurētajā reģistrā, nosaukumvietu var izlaist un vienlaikus norādīt vairākus blokus:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio atrod jaunās mapes tāpat kā jebkuru citu motīva bloku.
Instalēto bloku atjaunināšana
Instalētie faili ir kopija. Netiek uzskaitīts, kuru versiju instalējāt, un CLI nekad pats neatjaunina bloku. Lai iegūtu jaunāku versiju, pievienojiet bloku vēlreiz. Ja izmantojat CI vai nav pieejams terminālis, komanda apstājas, ja mape jau pastāv:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Terminālī CLI pirms pārrakstīšanas uzdod jautājumu. --dry-run parāda mapes, kuras tiktu aizstātas, bet --yes tās aizstāj:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Pārrakstīšana aizstāj uzskaitītos failus ar reģistra versiju, tāpēc vispirms veiciet vietējo izmaiņu komitu un pēc tam pārskatiet rezultātu ar git diff.
Lai atinstalētu, noņemiet mapi pēc nosaukuma:
npx blockstudio remove tabs --yes
Removed tabs
remove pieņem mapes nosaukumu, nevis namespace/block. Tas nenoņem atkarības, tāpēc pēc tabs noņemšanas tab-item paliek instalēts.
Versiju pārvaldība ar git atsaucēm
CLI nav ne versijas lauka, ne versijas karodziņa. To, ko tas izgūst, pilnībā nosaka URL, un vietnē GitHub versija ir URL norādītā atsauce. Patērētājs, kas norāda uz main, instalēšanas brīdī saņem tajā esošo main saturu.
Lai publicētu nemainīgu laidienu, arī tagā esošajam registry.json ir jālejupielādē faili no taga. Pirms taga izveides iestatiet baseUrl uz taga vērtību:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Pēc tam veiciet komitu, izveidojiet tagu un nosūtiet izmaiņas:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Pēc tam iestatiet baseUrl atpakaļ uz main un veiciet komitu, lai atzars turpinātu nodrošināt jaunākos failus. Ja izlaidīsiet pirmo darbību, patērētājs, kas piesaistīts tagam, saņems tagā norādīto bloku sarakstu, bet lejupielādēs failus no main.
Patērētāji piesaista versiju, reģistra URL izmantojot tagu:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Šajā piemērā v1.0.0 tika atzīmēts ar tagu, pirms pastāvēja tabs un tab-item, tāpēc piesaistītajā reģistrā ir pieejami tikai divi sākotnējie bloki:
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".
Komita SHA var izmantot arī reģistra URL, taču komits nevar iekļaut savu SHA failā baseUrl. Tāpēc SHA piesaiste fiksē bloku sarakstu, bet faili joprojām tiek ņemti no tās atsauces, ko nosauc šī komita baseUrl; laidieniem ieteicams izmantot tagus.
Kas jāņem vērā
- Vispirms tiek izgūti visi reģistri.
addielādē visus reģistrus noblocks.json, pirms kaut ko atrod, tāpēc viena nepieejama reģistra dēļ komanda neizdodas pat aracme/hero. Noņemiet reģistrus, ko vairs neizmantojat. - Neskaidriem nosaukumiem vajadzīga nosaukumvieta. Ja divos reģistros ir
hero, termināļa sesijā tiek jautāts, kuru izmantot,--yesizvēlas pirmo pēcblocks.jsonsecības, bet neinteraktīvā palaišanā tiek izvadītsBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Privātiem repozitorijiem vajadzīgas galvenes. Reģistra ierakstam izmantojiet objekta formu ar
urlunheaders. Galveņu vērtībās var izmantot${VAR}vietturus, kuru vērtības tiek nolasītas no vides. CLI nosūta galvenes gan reģistra izgūšanas, gan katras faila lejupielādes laikā. Viesotāja norādījumus par tokena iestatīšanu skatiet GitHub reģistrā.
Nākamās darbības
- Reģistra pārskats: kas ir reģistrs un kā darbojas CLI
- registry.json: visi manifestā ietvertie lauki
- blocks.json: patērētāja konfigurācija, autentifikācija un konfigurācijas noteikšana
- pievienošana: nosaukumvietas noteikšana, atkarības un pārrakstīšanas darbība
- GitHub reģistra viesošana: GitHub Pages un privāti repozitoriji
- Pielāgots serveris: reģistra nodrošināšana no savas infrastruktūras