Pierwsze kroki
Ten przewodnik pomoże Ci skonfigurować Blockstudio i utworzyć pierwszy niestandardowy blok.
Instalacja
Za pomocą Composer (zalecane)
composer require blockstudio/blockstudio
Blockstudio można zainstalować jako wtyczkę za pośrednictwem composer/installers lub dołączyć bezpośrednio do motywu. Wszystkie sposoby instalacji opisano w dokumentacji Composer.
Instalacje Composer otrzymują aktualizacje przez Composer. Wbudowany mechanizm aktualizacji GitHub jest automatycznie wyłączony.
Instalacja ręczna
Pobierz najnowsze wydanie z GitHub
Prześlij plik zip do katalogu wtyczek WordPress i aktywuj wtyczkę. Instalacje ręczne otrzymują automatyczne powiadomienia o aktualizacjach w panelu WordPress za pośrednictwem wbudowanego mechanizmu aktualizacji GitHub.
Obie metody instalacji dołączają prywatne kopie bibliotek Markdown, YAML i aktualizatora wraz z ich zależnościami. Nie korzystają z wersji dostarczanych przez inne wtyczki lub motywy ani ich nie zastępują. Jeśli Twoja aplikacja korzysta bezpośrednio z jednej z tych bibliotek, zainstaluj własną zależność Composer; dołączone kopie Blockstudio są wewnętrzne, a nie stanowią publicznego interfejsu PHP API.
Uwierzytelnione sprawdzanie aktualizacji
Instalacje ręczne domyślnie sprawdzają GitHub anonimowo. Kilka witryn korzystających z tego samego wychodzącego IP może wyczerpać anonimowy limit API GitHub i otrzymywać odpowiedzi HTTP 403 podczas sprawdzania aktualizacji. W 7.7.4 skonfiguruj osobisty token dostępu GitHub w wp-config.php, zanim załaduje się WordPress:
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');
Token wymaga dostępu wyłącznie do publicznych informacji o repozytorium. Nie przyznawaj uprawnień do zapisu. Przechowuj go w konfiguracji po stronie serwera, poza kontrolą wersji, a także poza blockstudio.json, atrybutami bloków i kodem frontendu. Aktualizator przekazuje go do dołączonego klienta GitHub w celu uwierzytelnionego sprawdzania i pobierania wydań. Żądania dotyczące niezwiązanych repozytoriów i innych hostów pobierania nie otrzymują tego tokenu.
W przypadku sekretów zarządzanych przez środowisko wtyczka MU może dostarczyć token lub zastąpić jego wartość:
<?php
add_filter('blockstudio/updater/token', function ($token) {
return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});
Filtr jest uruchamiany, gdy Blockstudio inicjuje swój aktualizator, przed załadowaniem motywu. Zarejestruj go we wtyczce MU zamiast w functions.php. Zwrócenie pustego ciągu wyłącza uwierzytelnianie, nawet jeśli stała jest zdefiniowana. Puste wartości lub wartości inne niż ciągi znaków powodują anonimowe sprawdzanie. Tokeny są opcjonalne; bez tokenu dotychczasowe działanie aktualizacji pozostaje bez zmian. Instalacje Composer nadal używają Composer do aktualizacji i nie inicjują tego aktualizatora.
Tworzenie pierwszego bloku
1. Utwórz katalog bloku
Utwórz nowy katalog w motywie:
my-theme/
blockstudio/
my-first-block/
block.json
index.php
2. Zdefiniuj schemat bloku
Utwórz block.json z konfiguracją bloku:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/my-first-block",
"title": "My First Block",
"category": "common",
"icon": "star-filled",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{
"id": "content",
"type": "textarea",
"label": "Content"
}
]
}
}
3. Utwórz szablon
Utwórz index.php do renderowania:
<div class="my-first-block">
<h2><?php echo $a['heading']; ?></h2>
<p><?php echo $a['content']; ?></p>
</div>
Korzystanie z szablonów Twig
Blockstudio obsługuje szablony Twig od razu po instalacji. Wystarczy użyć index.twig:
<div class="my-first-block">
<h2>{{ a.heading }}</h2>
<p>{{ a.content }}</p>
</div>
Dodawanie stylów
Utwórz plik style.css w tym samym folderze:
.my-first-block {
padding: 2rem;
background: #f5f5f5;
}
Blockstudio automatycznie doda ten arkusz stylów do kolejki, gdy blok będzie używany.
Tłumaczenia
Elementy sterujące edytora i przegląd administracyjny Blockstudio wczytują tłumaczenia JavaScript dla domeny tekstowej blockstudio za pośrednictwem WordPress. Zainstaluj odpowiedni pakiet językowy lub wygeneruj pliki tłumaczeń skryptów JSON za pomocą narzędzia tłumaczeniowego w wp-content/languages/plugins/. Ciągi bez dostępnego tłumaczenia pozostają po angielsku. Tłumaczy to własny interfejs Blockstudio, a nie treść ani etykiety pól zdefiniowane w blokach.
Następne kroki
Blok jest już gotowy do użycia w edytorze WordPress. Zapoznaj się z dalszą częścią dokumentacji, aby dowiedzieć się więcej o:
- Typy pól – wszystkich dostępnych typach pól
- Komponenty – InnerBlocks, RichText i nie tylko
- TailwindIntegracja – korzystaniu z Tailwind CSS
- Hooki – rozszerzaniu funkcjonalności za pomocą filtrów i akcji
Przejdź od pojedynczego bloku do pełnej biblioteki: tokeny projektu, wzorzec sekcji, pola powtarzalne, obrazy i komponowanie stron.