Rozszerzenia
Rozszerzenia pozwalają rozszerzać dowolny zarejestrowany blok w instalacji WordPress za pomocą prostego .json opartego na API, podobnego do konfiguracji block.json. Dotyczy to bloków podstawowych, zewnętrznych oraz utworzonych za pomocą Blockstudio.
Do dowolnego bloku można dodać wszystkie typy pól pól, a ich dane są zapisywane w atrybutach bloku. Rozszerzenia udostępniają pełny zestaw funkcji atrybutów, takich jak filtrowanie, wyłączanie, logika warunkowa i ustawianie dostępnych opcji.
Typy rozszerzeń
Rozszerzone wartości można wykorzystywać na różne sposoby:
- class: Dodaj klasę do bloku, korzystając z wartości atrybutu
- style: Dodaj do bloku style inline, korzystając z wartości atrybutu
- attributes: Ustaw bezpośrednio na bloku dowolną wartość atrybutu
- data attributes: Ustaw określone atrybuty danych za pomocą wartości rozszerzenia
Konfiguracja
Wyobraź sobie następującą sytuację: chcesz dodać pole klasy niestandardowej select do każdego bloku podstawowego. Wystarczy dodać ten plik .json w dowolnym miejscu folderu bloku, a zostanie automatycznie zarejestrowany jako rozszerzenie.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Doda to pole customColor do każdego bloku podstawowego, umożliwiając ustawienie koloru tekstu bloku.
Nazwa pliku
Ponieważ nie ma szablonu renderowania, rozszerzenie nie potrzebuje pasującego pliku index, a zatem nie musi nosić nazwy block.json. Dzięki temu wszystkie rozszerzenia można wygodnie przechowywać w jednym folderze. Kilka plików może rozszerzać te same bloki, na przykład dwa pliki z "name": "core/*"; każdy z nich rejestruje własne pola.
Schemat
Blockstudio udostępnia niestandardowy schemat JSON konfiguracji rozszerzeń:
Nazwa
Właściwość name obiektu konfiguracji określa, które bloki należy rozszerzyć. Dostępne są trzy opcje, zależnie od potrzeb:
- blockName: nazwa pojedynczego bloku, e.g.
core/paragraph - [blockNameA, blockNameB]: tablica nazw bloków, e.g.
["core/paragraph", "core/heading"] - core/*: symbol wieloznaczny rozszerzający wszystkie bloki danego typu
Każda nazwa zakończona gwiazdką jest symbolem wieloznacznym prefiksu, nie tylko core/*. Poniższe rozszerzenie dotyczy każdego bloku, którego nazwa zaczyna się od my-plugin/,
w tym bloków utworzonych za pomocą Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Wykluczanie bloków
Użyj tablicy exclude na najwyższym poziomie, aby pominąć bloki, które w przeciwnym razie pasowałyby do name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Wykluczenia używają tego samego dopasowania dokładnych nazw i prefiksów zakończonych na * co name.
Mają pierwszeństwo przed pojedynczymi nazwami, listami nazw i symbolami wieloznacznymi. Wykluczony
blok nie otrzymuje ani pól edytora rozszerzenia, ani atrybutów frontendu,
ani zasobów. Pozostałe pasujące rozszerzenia działają bez zmian. Pomiń exclude lub użyj
pustej tablicy, aby zachować dotychczasowe działanie.
Klucz Blockstudio
Podobnie jak przy korzystaniu z block.json w przypadku niestandardowych bloków, właściwość blockstudio musi być obecna w obiekcie konfiguracji, a extend musi mieć wartość true.
Pozycja
Domyślnie rozszerzenia są wyświetlane na własnej karcie w inspektorze bloku. Aby przenieść rozszerzenia w inne miejsce, można użyć właściwości group:
- settings: pozycja domyślna
- styles: karta stylów
- advanced: karta zaawansowana
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Priorytet
Właściwość priority pozwala określić kolejność renderowania rozszerzeń. Rozszerzenia o wyższym priorytecie będą renderowane później. Ustaw ją na najwyższym poziomie pliku, jak w przykładzie konfiguracji, albo wewnątrz extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Jeśli ustawiono obie wartości, pierwszeństwo ma blockstudio.extend.priority.
Atrybuty
Więcej informacji o działaniu atrybutów znajdziesz w sekcji atrybuty.
W przypadku atrybutów w rozszerzeniach należy znać tylko właściwość set. Służy ona do przypisania wartości atrybutu do jednego z typów rozszerzeń.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Pobieranie wartości
Do pobierania wartości atrybutu służy notacja kropkowa wewnątrz nawiasów klamrowych.
Można także pobierać wartości zagnieżdżone, gdy atrybuty nie zwracają pojedynczej wartości, na przykład po ustawieniu formatu zwracanego na both w typach pól z opcjami.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
Powyższy przykład ustawi atrybut style na color: #f00 lub color: #00f, a atrybut data-color na Red lub Blue, zależnie od wartości.
Obecnie w definicjach set można używać tylko wartości bieżącego atrybutu. Możliwość używania wartości z innych atrybutów może zostać dodana w przyszłości.
Tablice
W przypadku tablic właściwość set zostanie zastosowana do każdego elementu tablicy.
Każdy element dodaje własną klasę lub deklarację stylu. Każdy inny atrybut przechowuje pojedynczą wartość, więc każdy element ją nadpisuje i wygrywa ostatni. Ustaw join na true, aby zamiast tego zapisać wyniki wszystkich elementów, oddzielone spacjami i bez pustych ani powtórzonych wartości, dzięki czemu selektor taki jak [data-langs~="en"] pasuje do każdego wybranego elementu. join nie ma wpływu na class ani style, ani na pola zwracające pojedynczą wartość.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Wybranie obu opcji renderuje data-langs="en de". Bez join renderuje data-langs="de".
Pole Attributes
W przypadku pola attributes właściwość set nie jest potrzebna, ponieważ pole automatycznie przypisuje wartości do nazwy i wartości atrybutu.
Sprawdzanie pól rozszerzenia
bs_block_extension_fields('core/paragraph') zwraca definicje pól każdego rozszerzenia pasującego do bloku. Zobacz
Sprawdzanie bloków, aby poznać wartość zwracaną
i jej związek z bs_block_fields().