Публикуване на регистър с блокове в 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. Блокът за водещата секция има едно поле:
{
"$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 следва същия модел и добавя 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 трябва да изтегли:
{
"$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. Добавете регистъра под пространството от имена, което искате да въвеждате в командите:
{
"$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 към него:
"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 на регистъра:
{
"$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 и частни хранилища
- Потребителски сървър: предоставяне на регистър от собствената ви инфраструктура