Pāriet uz saturu

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.json publicē bloku autors. Tajā ir uzskaitīti bloki, faili, no kuriem katrs bloks sastāv, un baseUrl, no kura tos lejupielādēt.
  • blocks.json atrodas 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:

Kods
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:

JSON
{
  "$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"
      }
    ]
  }
}
PHP
<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ē:

JSON
{
  "$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:

  • files ir 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ā.
  • baseUrl jā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 no baseUrl, nevis no vietas, kas norādīta attiecībā pret to, no kuras tika ielādēts registry.json.
  • dependencies nosauc blokus tajā pašā reģistrā. Pievienojot tabs, vispirms tiek instalēts tab-item. Trūkstošas un cirkulāras atkarības aptur instalēšanu ar kļūdu.
  • name ir obligāts, bet netiek parādīts. Komandās un izvadē tiek izmantota atslēga, ko patērētājs norāda reģistram blocks.json, un tai nav obligāti jāsakrīt.
  • type ir informatīvs. Tas pieņem blockstudio, create-block vai wordpress, 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:

Kods
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
  • baseUrl iekš 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:

Kods
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:

Apvalks
npx blockstudio init --yes
Kods
Created .../acme-theme/blocks.json

init --yes izveido tukšu registries objektu. Pievienojiet reģistru zem nosaukumvietas, ko vēlaties ievadīt komandās:

JSON
{
  "$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:

Apvalks
npx blockstudio list
Kods
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:

Apvalks
npx blockstudio search tab
Kods
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ā:

Apvalks
npx blockstudio add acme/tabs --dry-run
Kods
Would install:
  tab-item (2 files)
  tabs (3 files)

Pēc tam instalējiet:

Apvalks
npx blockstudio add acme/tabs
Kods
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ā:

Kods
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:

Apvalks
npx blockstudio add hero card
Kods
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:

Apvalks
npx blockstudio add tab-item
Kods
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:

Apvalks
npx blockstudio add acme/tab-item --dry-run
Kods
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:

Apvalks
npx blockstudio remove tabs --yes
Kods
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:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

Pēc tam veiciet komitu, izveidojiet tagu un nosūtiet izmaiņas:

Apvalks
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:

JSON
{
  "$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:

Apvalks
npx blockstudio list
Kods
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Apvalks
npx blockstudio add acme/tabs
Kods
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. add ielādē visus reģistrus no blocks.json, pirms kaut ko atrod, tāpēc viena nepieejama reģistra dēļ komanda neizdodas pat ar acme/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, --yes izvēlas pirmo pēc blocks.json secības, bet neinteraktīvā palaišanā tiek izvadīts Block "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 url un headers. 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