Przejdź do treści

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

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.

PHP
<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.

Zobacz wszystkie warunki

Poniższy przykład rejestruje blok tylko wtedy, gdy typ bieżącego wpisu to strona:

JSON
{
  "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:

JSON
{
  "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 >=.

JSON
{
  "blockstudio": {
    "pluginDependencies": {
      "woocommerce": {
        "version": ">6"
      }
    }
  }
}

Własna ikona

Własne ikony SVG bloków można zarejestrować w następujący sposób:

JSON
{
  "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ę.

Kod
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.

JSON
{
  "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

PHP
// 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:

PHP
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:

PHP
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ę.