Preskočiť na obsah

Publikovanie registra blokov na GitHub

Keď vytvoríte niekoľko dobrých blokov, budete ich chcieť použiť aj v ďalšom projekte. Ručné kopírovanie priečinkov medzi témami funguje dovtedy, kým sa kópie nezačnú rozchádzať a nikto si nepamätá, ktorá téma obsahuje opravenú verziu. Zabaliť každý blok do balíka s vlastnou zostavou je priveľa práce pre priečinok, ktorý obsahuje block.json a šablónu.

Medzi tým je register blokov. Ide o súbor registry.json a súbor priečinkov blokov, ktoré sa sprístupňujú cez obyčajné HTTP. Používatelia spustia príkaz CLI, zdrojový kód bloku sa skopíruje do ich témy a od tej chvíle túto kópiu spravujú sami. Na jeho hostovanie stačí repozitár GitHub, pretože GitHub sprístupňuje každý súbor vo verejnom repozitári na surovej adrese URL.

Táto príručka vytvorí register s názvom acme so štyrmi blokmi, publikuje ho z repozitára acme/acme-blocks, nainštaluje z neho bloky do témy a pripne vydanie prostredníctvom značky git.

Balík blockstudio na npm má verziu 0.0.1. Toto vydanie je zástupné: jeho jediný príkaz add vypíše Adding block: <name> a skončí bez načítania čohokoľvek. Príkazy a výstupy v tejto príručke pochádzajú z registra CLI v repozitári Blockstudio (packages/registry), čo je CLI, ktorý opisuje Dokumentácia registra.

Ako do seba jednotlivé časti zapadajú

Treba poznať dva súbory:

  • registry.json publikuje autor bloku. Uvádza bloky, súbory, z ktorých sa každý blok skladá, a baseUrl na ich stiahnutie.
  • blocks.json sa nachádza v téme alebo doplnku používateľa. Uvádza registre, ktoré treba použiť, a priečinok, do ktorého sa bloky inštalujú.

Pri inštalácii bloku CLI načíta každý register z blocks.json, vyhľadá blok, vyrieši jeho závislosti, stiahne každý uvedený súbor z {baseUrl}/{block}/{file} a zapíše ho do {directory}/{block}/{file}. Nič nemení, takže súbory na disku sú presne také ako v repozitári.

Krok 1: Usporiadanie repozitára

Vytvorte repozitár, ktorého koreň obsahuje registry.json a ktorý má v priečinku blocks/ samostatný priečinok pre každý blok:

Kód
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

Názov priečinka je názvom bloku v registri a stane sa názvom priečinka v téme používateľa. Nechajte ho rovnaký ako druhú časť názvu bloku v block.json (acme/hero sa nachádza v hero/), aby sa nainštalovaný priečinok dal ľahko rozpoznať.

Krok 2: Zápis blokov

Každý priečinok obsahuje obyčajný blok Blockstudio. Úvodný blok má jedno pole:

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 sa riadi rovnakým vzorom a pridáva style.scss. tabs vykresľuje <InnerBlocks allowedBlocks='["acme/tab-item"]' /> a tab-item deklaruje "parent": ["acme/tabs"], takže tabs nie je užitočné bez tab-item. Register tento vzťah vyjadruje v ďalšom kroku.

Na týchto blokoch nie je nič špecifické pre register. CLI kopíruje priečinky, takže rovnakým spôsobom možno publikovať blok vytvorený pomocou @wordpress/create-block alebo zaregistrovaný pomocou obyčajného PHP.

Krok 3: Zápis registry.json

registry.json uvádza každý blok a každý súbor, ktorý má CLI stiahnuť:

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"]
    }
  ]
}

O funkčnosti tohto súboru rozhoduje niekoľko pravidiel:

  • files je explicitný zoznam. CLI sťahuje presne tieto cesty a nič iné. Nepoužívajú sa zástupné znaky, takže nový súbor sa zahrnie až po jeho pridaní sem. Cesty môžu obsahovať podadresáre, ktoré sa pri inštalácii vytvoria.
  • baseUrl musí byť absolútna URL. CLI ju overí ako URL a relatívne hodnoty odmietne. Súbory blokov sa vždy načítavajú z baseUrl, nikdy z umiestnenia vzhľadom na miesto, odkiaľ sa načítalo registry.json.
  • dependencies pomenúvajú bloky v tom istom registri. Pridaním tabs sa najprv nainštaluje tab-item. Chýbajúce a kruhové závislosti inštaláciu zastavia chybou.
  • name je povinný, ale nezobrazuje sa. Príkazy a výstup používajú kľúč, ktorý používateľ zadá registru v blocks.json; nemusí sa zhodovať.
  • type slúži iba na informáciu. Prijíma blockstudio, create-block alebo wordpress a nemení správanie CLI.

CLI pri každom načítaní overí celý súbor a nahlási každé pole s chybou, takže preklep sa odhalí ešte pred stiahnutím súborov. Riadok $schema poskytuje tie isté kontroly v editore.

Krok 4: Publikovanie cez nespracované adresy URL

Potvrďte zmeny a odošlite úložisko do GitHub. Každý súbor vo verejnom úložisku bude dostupný na adrese:

Kód
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> je vetva, značka alebo SHA potvrdenia. Pre tento register sú dôležité dve adresy URL:

  • Adresa URL registra URL, ktorú nastavia používatelia: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl v registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

S týmto baseUrl sa index.php v hero načíta z https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Surový hostiteľ vracia obsah súboru namiesto stránky GitHub HTML, ktorú CLI potrebuje. Nesprávny vlastník, úložisko alebo referencia sa prejaví ako 404 pri prvom príkaze:

Kód
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

Krok 5: Inštalácia blokov do témy

V koreňovom priečinku témy, ktorá bloky používa, vytvorte blocks.json:

Shell
npx blockstudio init --yes
Kód
Created .../acme-theme/blocks.json

init --yes vytvorí prázdny objekt registries. Pridajte register pod menným priestorom, ktorý chcete zadávať v príkazoch:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

Spustite init bez --yes v termináli a na tie isté otázky (umiestnenie priečinka s blokmi, názvy registrov a adresy URL) odpovedzte interaktívne.

Skontrolujte, či sa register správne načíta:

Shell
npx blockstudio list
Kód
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 vyhľadáva podreťazec bez rozlišovania veľkých a malých písmen v názvoch, titulkoch a opisoch:

Shell
npx blockstudio search tab
Kód
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

Náhľad inštalácie zobrazíte pomocou --dry-run. Závislosť je uvedená ako prvá, pretože sa inštaluje ako prvá:

Shell
npx blockstudio add acme/tabs --dry-run
Kód
Would install:
  tab-item (2 files)
  tabs (3 files)

Potom vykonajte samotnú inštaláciu:

Shell
npx blockstudio add acme/tabs
Kód
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Oba priečinky sa teraz nachádzajú v priečinku blockstudio témy, presne tak, ako sú uložené v úložisku:

Kód
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Menný priestor môžete vynechať, ak má blok iba jeden nakonfigurovaný register, a môžete zadať viacero blokov naraz:

Shell
npx blockstudio add hero card
Kód
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio nájde nové priečinky rovnako ako každý iný blok v téme.

Aktualizácia nainštalovaných blokov

Nainštalované súbory sú kópiou. Nesleduje sa, ktorú verziu ste nainštalovali, a CLI nikdy neaktualizuje blok samostatne. Ak chcete získať novšiu verziu, pridajte blok znova. Ak nie je k dispozícii terminál alebo sa príkaz spúšťa v CI, existujúci priečinok vykonanie príkazu zastaví:

Shell
npx blockstudio add tab-item
Kód
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

V termináli sa CLI najprv opýta, či chcete súbory prepísať. --dry-run vypíše priečinky, ktoré by nahradil, a --yes ich nahradí:

Shell
npx blockstudio add acme/tab-item --dry-run
Kód
Would overwrite tab-item
Would install:
  tab-item (2 files)

Prepísaním sa uvedené súbory nahradia verziou z registra. Preto najprv potvrďte miestne zmeny a výsledok skontrolujte pomocou git diff.

Ak chcete blok odinštalovať, odstráňte priečinok podľa názvu:

Shell
npx blockstudio remove tabs --yes
Kód
Removed tabs

remove preberá názov priečinka, nie namespace/block. Závislosti neodstraňuje, takže tab-item zostane nainštalovaný aj po odstránení tabs.

Správa verzií pomocou referencií git

CLI nemá pole verzie ani príznak verzie. O tom, čo načíta, rozhodujú výlučne adresy URL; na GitHub je referencia v URL verziou. Používateľ, ktorý nastaví main, získa pri inštalácii obsah, ktorý tam práve v tom čase uchováva main.

Ak chcete zverejniť vydanie, ktoré zostane nemenné, aj registry.json v značke musí načítavať súbory zo značky. Pred vytvorením značky nastavte baseUrl na jej hodnotu:

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

Potom potvrďte zmeny, vytvorte značku a odošlite ju:

Shell
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Potom nastavte baseUrl späť na main a potvrďte zmeny, aby vetva naďalej poskytovala aktuálne súbory. Ak preskočíte prvý krok, používateľ, ktorý si nastavil značku, získa zoznam blokov zo značky, ale súbory stiahne z main.

Používatelia si nastavia konkrétnu verziu použitím značky v URL registra:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

V tomto príklade bola značka v1.0.0 vytvorená skôr, než vznikli tabs a tab-item, takže register s touto pevne nastavenou verziou ponúka iba dva pôvodné bloky:

Shell
npx blockstudio list
Kód
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Kód
Block "tabs" not found in registry "acme".

V adrese URL registra funguje aj SHA potvrdenia URL, no potvrdenie nemôže obsahovať svoje vlastné SHA v baseUrl. Nastavenie verzie pomocou SHA preto zafixuje zoznam blokov, zatiaľ čo súbory sa naďalej načítavajú z referencie, ktorú uvádza baseUrl daného potvrdenia. Preto pri vydaniach uprednostnite značky.

Na čo pamätať

  • Najprv sa načítajú všetky registre. add načíta všetky registre v blocks.json ešte predtým, ako čokoľvek vyrieši, takže ak je niektorý register nedostupný, príkaz zlyhá aj pre acme/hero. Odstráňte registre, ktoré už nepoužívate.
  • Nejednoznačné názvy vyžadujú menný priestor. Ak majú dva registre položku hero, terminálová relácia sa opýta, ktorú použiť, --yes vyberie prvú v poradí blocks.json a neinteraktívne spustenie skončí s kódom Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Súkromné repozitáre vyžadujú hlavičky. Použite objektovú podobu položky registra s url a headers. Hodnoty hlavičiek podporujú zástupné symboly ${VAR}, ktoré sa načítavajú z prostredia, a CLI odosiela hlavičky pri načítaní registra aj pri každom sťahovaní súboru. Nastavenie tokenu nájdete v dokumentácii hostingu GitHub.

Ďalšie kroky