Publikowanie rejestru bloków w GitHub
Gdy masz już kilka dobrych bloków, chcesz użyć ich również w następnym projekcie. Ręczne kopiowanie folderów między motywami sprawdza się do czasu, gdy kopie się rozchodzą i nikt nie pamięta, w którym motywie znajduje się poprawiona wersja. Opakowanie każdego bloku w pakiet z własnym procesem budowania to sporo zachodu jak na folder zawierający block.json i szablon.
Rejestr bloków stanowi rozwiązanie pośrednie. To plik registry.json i zestaw folderów bloków udostępnianych przez zwykłe HTTP. Użytkownicy uruchamiają polecenie CLI, źródła bloków są kopiowane do ich motywu i od tej pory to oni zarządzają kopiami. Do hostowania rejestru wystarczy repozytorium GitHub, ponieważ GitHub udostępnia każdy plik z publicznego repozytorium pod surowym adresem URL.
W tym przewodniku utworzymy rejestr o nazwie acme zawierający cztery bloki, opublikujemy go z repozytorium acme/acme-blocks, zainstalujemy z niego bloki w motywie i przypniemy wydanie za pomocą tagu git.
Pakiet blockstudio w npm jest w wersji 0.0.1. To wydanie zastępcze: jedyne polecenie, add, wyświetla Adding block: <name> i kończy działanie bez pobierania czegokolwiek. Polecenia i wyniki w tym przewodniku pochodzą z rejestru CLI w repozytorium Blockstudio (packages/registry), które jest CLI opisywanym w Dokumentacji rejestru.
Jak współdziałają poszczególne elementy
Warto znać dwa pliki:
registry.jsonjest publikowany przez autora bloku. Zawiera listę bloków, plików, z których składa się każdy z nich, orazbaseUrl, z którego można je pobrać.blocks.jsonznajduje się w motywie lub wtyczce użytkownika. Określa, których rejestrów używać i do którego katalogu instalować bloki.
Podczas instalowania bloku CLI pobiera każdy rejestr wymieniony w blocks.json, wyszukuje blok, rozwiązuje jego zależności, pobiera każdy wymieniony plik z {baseUrl}/{block}/{file} i zapisuje go w {directory}/{block}/{file}. Niczego nie przekształca, dlatego pliki na dysku są dokładnie takie same jak w repozytorium.
Krok 1: uporządkuj repozytorium
Utwórz repozytorium z plikiem registry.json w katalogu głównym i osobnym folderem dla każdego bloku w 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
Nazwa folderu jest nazwą bloku w rejestrze i staje się nazwą folderu w motywie użytkownika. Powinna być identyczna jak druga część nazwy bloku w block.json (acme/hero znajduje się w hero/), aby łatwo rozpoznać zainstalowany folder.
Krok 2: napisz bloki
Każdy folder zawiera zwykły blok Blockstudio. Blok sekcji głównej ma jedno pole:
{
"$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 ma taką samą strukturę i dodaje style.scss. tabs renderuje <InnerBlocks allowedBlocks='["acme/tab-item"]' />, a tab-item deklaruje "parent": ["acme/tabs"], dlatego tabs nie jest przydatne bez tab-item. W następnym kroku opiszemy tę zależność w rejestrze.
Bloki te nie mają nic specyficznego dla rejestru. CLI kopiuje foldery, więc bloki utworzone za pomocą @wordpress/create-block lub zarejestrowane zwykłym PHP można opublikować w ten sam sposób.
Krok 3: napisz registry.json
registry.json zawiera listę każdego bloku i każdego pliku, który CLI ma pobrać:
{
"$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 tym, czy ten plik zadziała, decyduje kilka zasad:
filesto jawna lista. CLI pobiera dokładnie te ścieżki i nic więcej. Nie używa wzorców glob, więc nowy zasób zostanie dołączony dopiero po dodaniu go tutaj. Ścieżki mogą zawierać podkatalogi, które są tworzone podczas instalacji.baseUrlmusi być bezwzględnym URL. CLI sprawdza, czy jest to URL, i odrzuca wartości względne. Pliki bloków są zawsze pobierane zbaseUrl, nigdy ze ścieżki względnej względem miejsca, z którego wczytanoregistry.json.dependencieswskazuje bloki z tego samego rejestru. Dodanietabsinstaluje najpierwtab-item. Brakujące i cykliczne zależności przerywają instalację z błędem.namejest wymagane, ale nie jest wyświetlane. Polecenia i dane wyjściowe używają klucza, który użytkownik przekazuje rejestrowi wblocks.json; nie musi on być taki sam.typema charakter informacyjny. Przyjmujeblockstudio,create-blocklubwordpressi nie zmienia działania CLI.
CLI sprawdza cały plik przy każdym pobraniu i zgłasza każde pole z błędem,
więc literówka zostaje wykryta, zanim zostanie pobrany jakikolwiek plik. Wiersz $schema
zapewnia te same kontrole w edytorze.
Krok 4: Publikowanie przez surowe adresy URL
Zatwierdź zmiany w repozytorium i wypchnij je do GitHub. Każdy plik w publicznym repozytorium będzie wtedy dostępny pod adresem:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> to gałąź, tag lub SHA zatwierdzenia. W tym rejestrze istotne są dwa
adresy URL:
- Rejestr URL, który konfigurują użytkownicy:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrlwregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Dzięki temu baseUrl pobierana jest index.php hero z https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Surowy host zwraca zawartość pliku zamiast strony GitHub HTML, której potrzebuje CLI. Nieprawidłowy właściciel, repozytorium lub ref ujawnia się jako 404 przy pierwszym poleceniu:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Krok 5: Instalowanie bloków w motywie
W katalogu głównym używanego motywu utwórz blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes zapisuje pusty obiekt registries. Dodaj rejestr pod przestrzenią nazw,
której chcesz używać w poleceniach:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Uruchom w terminalu init bez --yes, aby zamiast tego odpowiedzieć na te same pytania
interaktywnie (katalog bloku, nazwy rejestrów i adresy URL).
Sprawdź, czy rejestr jest rozpoznawany:
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 wyszukuje fragment tekstu bez uwzględniania wielkości liter w nazwach, tytułach i
opisach:
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.
Wyświetl podgląd instalacji za pomocą --dry-run. Zależność jest wymieniona jako pierwsza,
ponieważ to ona jest instalowana najpierw:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Teraz zainstaluj na stałe:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Oba foldery znajdują się teraz w katalogu blockstudio motywu, dokładnie tak
jak w repozytorium:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Możesz pominąć przestrzeń nazw, gdy tylko jeden skonfigurowany rejestr zawiera dany blok, i przekazać kilka bloków naraz:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio wykrywa nowe foldery tak samo jak każdy inny blok w motywie.
Aktualizowanie zainstalowanych bloków
Zainstalowane pliki są kopią. Nie jest zapisywana informacja o zainstalowanej wersji, a CLI nigdy samodzielnie nie aktualizuje bloku. Aby pobrać nowszą wersję, dodaj blok ponownie. Bez terminala lub w CI istniejący folder zatrzymuje polecenie:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
W terminalu CLI najpierw pyta o zgodę na nadpisanie. --dry-run wyświetla
foldery, które zostałyby zastąpione, a --yes je zastępuje:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Nadpisanie zastępuje wymienione pliki wersją z rejestru, więc najpierw zatwierdź
lokalne zmiany, a następnie sprawdź wynik za pomocą git diff.
Aby odinstalować, usuń folder, podając jego nazwę:
npx blockstudio remove tabs --yes
Removed tabs
remove przyjmuje nazwę folderu, a nie namespace/block. Nie usuwa
zależności, więc tab-item pozostaje zainstalowany po usunięciu tabs.
Wersjonowanie za pomocą refów git
CLI nie ma pola wersji ani flagi wersji. O tym, co zostanie pobrane,
decydują wyłącznie adresy URL, a w GitHub ref w URL jest wersją. Użytkownik,
który wskaże main, otrzyma to, co main zawiera w chwili instalacji.
Aby opublikować niezmienne wydanie, registry.json pod tagiem również musi
pobierać pliki z tego tagu. Przed utworzeniem tagu ustaw baseUrl na ten tag:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Następnie zatwierdź zmiany, utwórz tag i wypchnij je:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Następnie ustaw baseUrl z powrotem na main i zatwierdź zmiany, aby gałąź nadal
udostępniała aktualne pliki. Jeśli pominiesz pierwszy krok, użytkownik przypięty do tagu
otrzyma listę bloków z tego tagu, ale pliki pobierze z main.
Użytkownicy przypinają wersję, używając tagu w rejestrze URL:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
W tym przykładzie v1.0.0 został oznaczony tagiem przed utworzeniem tabs i tab-item, więc
przypięty rejestr udostępnia tylko dwa pierwotne 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".
SHA zatwierdzenia działa również w rejestrze URL, ale zatwierdzenie nie może zawierać własnego
SHA w baseUrl. Przypięcie po SHA ustala więc listę bloków, ale pliki nadal pochodzą z refu
wskazanego przez baseUrl tego zatwierdzenia. Dlatego do wydań lepiej używać tagów.
Warto pamiętać
- Najpierw pobierany jest każdy rejestr.
addwczytuje wszystkie rejestry wblocks.json, zanim cokolwiek wyszuka, więc niedostępność jednego z nich powoduje niepowodzenie polecenia, nawet dlaacme/hero. Usuń rejestry, których już nie używasz. - Niejednoznaczne nazwy wymagają przestrzeni nazw. Jeśli oba rejestry zawierają
hero, w terminalu pojawi się pytanie, którego użyć;--yeswybiera pierwszą pozycję w kolejnościblocks.json, a nieinteraktywne uruchomienie kończy się kodemBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Prywatne repozytoria wymagają nagłówków. Użyj obiektowej postaci wpisu rejestru
z
urliheaders. Wartości nagłówków obsługują znaczniki${VAR}, których wartości są pobierane ze środowiska, a CLI wysyła nagłówki przy pobieraniu rejestru i każdego pliku. Informacje o konfiguracji tokenu znajdziesz na stronie hostinguGitHub.
Następne kroki
- Przegląd rejestru: czym jest rejestr i jak działa CLI
- registry.json: wszystkie pola manifestu
- blocks.json: konfiguracja użytkownika, uwierzytelnianie i wykrywanie konfiguracji
- add: rozpoznawanie przestrzeni nazw, zależności i działanie nadpisywania
- GitHub hosting: GitHub Pages i prywatne repozytoria
- Własny serwer: udostępnianie rejestru z własnej infrastruktury