Към съдържанието

Публикуване на регистър с блокове в GitHub

След като изградите няколко добри блока, ще искате да ги използвате и в следващия проект. Ръчното копиране на папки между теми работи, докато копията не се разминаят и никой вече не помни в коя тема е поправената версия. Опаковането на всеки блок в пакет със собствена компилация изисква твърде много церемонии за папка, в която има block.json и шаблон.

Регистърът с блокове е междинно решение. Това е файл registry.json и набор от папки с блокове, обслужвани чрез обикновен HTTP. Потребителите изпълняват команда CLI, изходният код на блока се копира в темата им и оттам нататък те притежават това копие. За хостване е достатъчно хранилище GitHub, защото GitHub обслужва всеки файл в публично хранилище чрез необработен URL.

Това ръководство създава регистър с име acme с четири блока, публикува го от хранилището acme/acme-blocks, инсталира блокове от него в тема и фиксира издание чрез git етикет.

Пакетът blockstudio в npm е във версия 0.0.1. Това издание е заместител: единствената му команда, add, извежда Adding block: <name> и приключва, без да изтегля нищо. Командите и изходът в това ръководство са от регистъра CLI в хранилището Blockstudio (packages/registry), което е CLI, описан в документацията за регистъра.

Как взаимодействат компонентите

Има два файла, които трябва да знаете:

  • registry.json се публикува от автора на блоковете. В него са изброени блоковете, файловете на всеки блок и baseUrl за изтеглянето им.
  • blocks.json се намира в темата или приставката на потребителя. В него са посочени регистрите за използване и директорията, в която се инсталират блоковете.

При инсталиране на блок CLI изтегля всеки регистър от blocks.json, намира блока, разрешава зависимостите му, изтегля всеки посочен файл от {baseUrl}/{block}/{file} и го записва в {directory}/{block}/{file}. Нищо не се трансформира, затова файловете на диска са точно копия на файловете в хранилището.

Стъпка 1: Подредете хранилището

Създайте хранилище с файл registry.json в корена и по една папка за всеки блок в 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

Името на папката е името на блока в регистъра и става име на папката в темата на потребителя. Направете го идентично на втората част от името на блока в block.json (acme/hero се намира в hero/), за да е лесно да разпознаете инсталираната папка.

Стъпка 2: Напишете блоковете

Всяка папка е обикновен блок Blockstudio. Блокът за водещата секция има едно поле:

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 следва същия модел и добавя style.scss. tabs изобразява <InnerBlocks allowedBlocks='["acme/tab-item"]' />, а tab-item декларира "parent": ["acme/tabs"], затова tabs не е полезен без tab-item. Регистърът описва тази връзка в следващата стъпка.

Нищо в тези блокове не зависи от регистъра. CLI копира папки, затова блок, изграден с @wordpress/create-block или регистриран с обикновен PHP, може да се публикува по същия начин.

Стъпка 3: Напишете registry.json

registry.json изброява всеки блок и всеки файл, който CLI трябва да изтегли:

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

Няколко правила определят дали този файл ще работи:

  • files е изричен списък. CLI изтегля точно тези пътища и нищо друго. Няма търсене по шаблон, така че нов ресурс се включва в пакета само след като го добавите тук. Пътищата може да съдържат поддиректории, които се създават при инсталиране.
  • baseUrl трябва да е абсолютен URL. CLI го валидира като URL и отхвърля относителни стойности. Файловете на блоковете винаги се извличат от baseUrl, а не от местоположение спрямо това откъде е зареден registry.json.
  • dependencies посочва блокове в същия регистър. Добавянето на tabs първо инсталира tab-item. Липсващите и цикличните зависимости прекратяват инсталирането с грешка.
  • name е задължително, но не се показва. Командите и изходът използват ключа, който потребителят задава на регистъра в blocks.json; той не е задължително да съвпада.
  • type е само информативно. Приема blockstudio, create-block или wordpress и не променя поведението на CLI.

CLI валидира целия файл при всяко извличане и посочва всяко поле с грешка, така че печатна грешка се открива преди изтеглянето на какъвто и да е файл. Редът $schema извършва същите проверки в редактора ви.

Стъпка 4: Публикуване чрез необработени URL адреси

Изпратете с commit и push хранилището в GitHub. След това всеки файл в публичното хранилище е достъпен на адрес:

Код
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> е клон, етикет или SHA на commit. За този регистър са важни два URL адреса:

  • Регистърът URL, който потребителите конфигурират: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl в registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

С този baseUrl index.php на hero се извлича от https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Хостът за необработени файлове връща съдържанието на файла, а не страницата GitHub HTML, от която се нуждае CLI. Грешен собственик, хранилище или ref се проявява като 404 още при първата команда:

Код
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

Стъпка 5: Инсталиране на блокове в тема

В основната директория на темата, в която ще се използват блоковете, създайте blocks.json:

Обвивка
npx blockstudio init --yes
Код
Created .../acme-theme/blocks.json

init --yes записва празен обект registries. Добавете регистъра под пространството от имена, което искате да въвеждате в командите:

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

Изпълнете init без --yes в терминал, за да отговорите интерактивно на същите въпроси (директория на блоковете, имена и URL адреси на регистрите).

Проверете дали регистърът може да бъде намерен:

Обвивка
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 търси подниз без разлика между главни и малки букви в имената, заглавията и описанията:

Обвивка
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.

Прегледайте инсталирането с --dry-run. Зависимостта е посочена първа, защото се инсталира първа:

Обвивка
npx blockstudio add acme/tabs --dry-run
Код
Would install:
  tab-item (2 files)
  tabs (3 files)

След това инсталирайте:

Обвивка
npx blockstudio add acme/tabs
Код
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Сега двете папки са в директорията blockstudio на темата, точно както са в хранилището:

Код
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Може да пропуснете пространството от имена, когато само един конфигуриран регистър съдържа блока, и да подадете няколко блока наведнъж:

Обвивка
npx blockstudio add hero card
Код
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio открива новите папки като всеки друг блок в темата.

Актуализиране на инсталирани блокове

Инсталираните файлове са копие. Не се следи коя версия сте инсталирали и CLI никога не актуализира блок самостоятелно. За да изтеглите по-нова версия, добавете блока отново. Без терминал или в CI, ако папката вече съществува, командата се прекратява:

Обвивка
npx blockstudio add tab-item
Код
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

В терминал CLI вместо това пита дали искате да презапишете. --dry-run показва кои папки ще бъдат заменени, а --yes ги заменя:

Обвивка
npx blockstudio add acme/tab-item --dry-run
Код
Would overwrite tab-item
Would install:
  tab-item (2 files)

При презаписване посочените файлове се заменят с версията от регистъра. Затова първо направете commit на локалните промени и прегледайте резултата с git diff.

За да деинсталирате, премахнете папката по име:

Обвивка
npx blockstudio remove tabs --yes
Код
Removed tabs

remove приема името на папката, а не namespace/block. Не премахва зависимостите, така че tab-item остава инсталиран след премахването на tabs.

Версии с git refs

CLI няма поле за версия и флаг за версия. Какво ще извлече зависи изцяло от URL адресите, а в GitHub ref-ът в URL е версията. Потребител, който посочи main, получава съдържанието на main към момента на инсталиране.

За да публикувате фиксирана версия, registry.json в етикета също трябва да изтегля от етикета. Преди да създадете етикета, задайте baseUrl към него:

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

След това направете commit, създайте етикета и изпратете промените с push:

Обвивка
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

След това задайте baseUrl обратно към main и направете commit, така че клонът да продължи да предоставя актуалните файлове. Ако пропуснете първата стъпка, потребител с фиксиран етикет получава списъка с блокове от етикета, но изтегля файловете от main.

Потребителите фиксират версия, като използват етикета в URL на регистъра:

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

В този пример v1.0.0 е създаден като етикет преди да съществуват tabs и tab-item, затова фиксираният регистър предлага само двата първоначални блока:

Обвивка
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".

SHA на commit също работи в URL на регистъра, но commit не може да съдържа собствения си SHA в baseUrl. Следователно фиксирането по SHA закрепва списъка с блокове, докато файловете продължават да се извличат от ref-а, посочен в baseUrl на този commit. Затова за версиите предпочитайте етикети.

Важни подробности

  • Първо се извлича всеки регистър. add зарежда всички регистри в blocks.json, преди да разреши каквото и да е, така че недостъпен регистър проваля командата дори за acme/hero. Премахвайте регистрите, които вече не използвате.
  • При двусмислени имена е нужно пространство от имена. Ако два регистъра съдържат hero, в терминална сесия се пита кой да се използва, --yes избира първия според реда в blocks.json, а неинтерактивно изпълнение завършва с Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • За частни хранилища са нужни заглавки. Използвайте обектната форма на запис в регистъра с url и headers. Стойностите на заглавките поддържат заместители ${VAR}, чиито стойности се вземат от средата, а CLI изпраща заглавките при извличането на регистъра и изтеглянето на всеки файл. Вижте хостинга на GitHub за настройката на токена.

Следващи стъпки

  • Преглед на регистъра: какво представлява регистърът и как работи CLI
  • registry.json: всяко поле в манифеста
  • blocks.json: конфигурация на потребителя, удостоверяване и откриване на конфигурацията
  • add: разрешаване на пространства от имена, зависимости и поведение при презаписване
  • хостинг на GitHub: GitHub Pages и частни хранилища
  • Потребителски сървър: предоставяне на регистър от собствената ви инфраструктура