Rejestrowanie
Tworzenie własnych bloków za pomocą Blockstudio jest bardzo proste. Wtyczka
wyszuka folder blockstudio w aktualnie aktywnym motywie. Zarejestrowane zostaną
wszystkie znajdujące się w nim podfoldery zawierające plik block.json z kluczem blockstudio.
block.json
{
"name": "blockstudio/native",
"title": "Native Block",
"category": "text",
"icon": "star-filled",
"description": "Native Blockstudio block.",
"blockstudio": true
}
Szablon
Na razie blok niestandardowy nie zostanie zarejestrowany, ponieważ brakuje mu
szablonu. Aby to naprawić, utwórz plik index.php w tym samym folderze co plik
block.json. Jego zawartość będzie automatycznie renderowana, gdy użyjesz bloku.
<h1>My first native block.</h1>
Logika warunkowa
Bloki można rejestrować warunkowo za pomocą klucza conditions. Obsługuje on
wszystkie zmienne globalne dostępne również dla atrybutów.
Poniższy przykład rejestruje blok tylko wtedy, gdy typ bieżącego wpisu to strona:
{
"blockstudio": {
"conditions": [
[
{
"type": "postType",
"operator": "==",
"value": "page"
}
]
]
}
}
Zależności wtyczek
Bloki mogą zależeć od aktywnych wtyczek WordPress za pomocą klucza pluginDependencies.
Jeśli jedna z wymienionych wtyczek jest nieaktywna, blok zostanie pominięty podczas
rejestracji.
Zależności używają identyfikatorów wtyczek WordPress:
{
"blockstudio": {
"pluginDependencies": [
"woocommerce",
"advanced-custom-fields"
]
}
}
Użyj postaci obiektu, aby wymagać określonej wersji wtyczki. Ograniczenia wersji
korzystają z tych samych operatorów co PHP version_compare(); wersja bez operatora jest
traktowana jako >=.
{
"blockstudio": {
"pluginDependencies": {
"woocommerce": {
"version": ">6"
}
}
}
}
Własna ikona
Własne ikony SVG bloków można zarejestrować w następujący sposób:
{
"blockstudio": {
"icon": "<svg></svg>"
}
}
WordPress nie obsługuje własnych ikon SVG we własnym kluczu block.json icon,
dozwolone są tu tylko identyfikatory Dashicons.
Standardowe bloki WordPress
Blockstudio automatycznie rejestruje też standardowe bloki WordPress znajdujące się w katalogach Blockstudio. Każdy plik block.json bez klucza blockstudio, ale z prawidłową właściwością name, jest rejestrowany za pomocą natywnego mechanizmu WordPress register_block_type().
Możesz więc umieszczać bloki utworzone za pomocą @wordpress/create-block bezpośrednio w folderze blockstudio/, gdzie zostaną automatycznie zarejestrowane wraz z blokami Blockstudio. Nie trzeba dodawać osobnego kodu rejestrującego wtyczkę.
blockstudio/
├── hero/
│ ├── block.json ← Blockstudio block (has "blockstudio" key)
│ └── index.twig
├── my-js-block/
│ ├── block.json ← Standard WP block (no "blockstudio" key)
│ ├── index.js ← Compiled editor script
│ ├── index.css
│ ├── style-index.css
│ └── render.php
Utwórz blok za pomocą npx wp-scripts build, a następnie umieść folder wynikowy w katalogu Blockstudio. Blok zostanie zarejestrowany automatycznie.
To samo dotyczy bloków PHP dostępnych od wersji WordPress 7.0:
block.json z obsługą autoRegister i właściwością render.php nie wymaga skryptu ani kompilacji i jest tu rejestrowany jak każdy inny standardowy blok. Core ogranicza tę ścieżkę do prostych bloków z atrybutami typu string, integer, boolean i enum; gdy tylko blok wymaga bloków wewnętrznych, tekstu formatowanego, multimediów lub niestandardowych elementów sterujących, należy utworzyć blok po stronie klienta albo dodać mu klucz blockstudio i używać PHP.
HTML
Blockstudio używa parsera elementów React do renderowania elementu ikony, dlatego w ciągu ikony można użyć HTML.
{
"blockstudio": {
"icon": "<div>:-)</div>"
}
}
Własne ścieżki
Domyślnie Blockstudio rekurencyjnie przeszukuje folder blockstudio w bieżącym motywie lub motywie potomnym w poszukiwaniu bloków. Możesz zmienić to zachowanie na dwa sposoby.
Filtr
// Custom path within your theme.
add_filter('blockstudio/path', function () {
return get_template_directory() . '/blocks';
});
// Custom path within a plugin.
add_filter('blockstudio/path', function () {
return WP_PLUGIN_DIR . '/my-custom-plugin/blocks';
});
W przypadku złożonych lub wirtualnych systemów plików użyj logicznego źródła wyszukiwania zamiast dodawać niezależne ścieżki nadrzędne i nakładkowe. Źródła logiczne obsługują przesłanianie plików dla poszczególnych ścieżek, dziedziczenie plików równorzędnych, usuwanie, tożsamość pamięci podręcznej i pochodzenie. Zobacz sekcję Logiczne źródła wyszukiwania.
Instancje
Jeśli powyższe opcje nie wystarczą, możesz utworzyć instancję klasy
Blockstudio\Build dla wybranych folderów:
add_action('init', function () {
Blockstudio\Build::init([
'dir' => get_template_directory() . '/client-blocks'
]);
});
Filtrowanie metadanych
Metadane można przefiltrować przed rejestracją bloku za pomocą filtra
blockstudio/blocks/meta:
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
if (str_starts_with($block['name'], 'marketing')) {
$meta['icon'] = 'megaphone';
}
return $meta;
}, 10, 2);
Powyższy przykład jest używany wewnętrznie, aby wszystkie elementy biblioteki Blockstudio miały tę samą ikonę.