Projektujesz bloki na WordPress i ACF – przygotuj się na zmiany z block.json

Jeśli tworzysz bloki na WordPressie z pomocą ACF i dalej rejestrujesz je przez acf_register_block_type() w plikach PHP, czas się zatrzymać i spojrzeć, co nadchodzi. Bo to, co do tej pory działało świetnie, powoli będzie musiało ustąpić miejsca nowemu podejściu – block.json i API w wersji 3.

Zmiana to nie tylko kosmetyka. To przesunięcie w kierunku pełnej kompatybilności z edytorem blokowym (Gutenbergiem) i nowymi funkcjami, które WordPress będzie mocno wspierał w nadchodzących wersjach. Już teraz ACF 6.6 wprowadza pełne wsparcie dla rejestrowania bloków przez block.json, a to tylko początek większego ruchu.

Czas przesiąść się na block.json w WordPress?

Jeśli korzystasz z bloków ACF w wersji 2 (czyli zarejestrowanych klasycznie przez PHP) to pewnie zadajesz sobie pytanie – czy one przestaną działać? Możliwe że nie od razu. Ale nie liczyłbym na to, że WordPress będzie je wspierał wiecznie. Oficjalne komunikaty mówią jasno – w WordPressie 7.0 (planowanym na 2026) V3 (czyli iframe blocks) mogą stać się obowiązkowe. Bez przejścia na nowy standard możesz zostać z funkcją, która formalnie „działa”, ale bez dostępu do nowych możliwości, takich jak edycja treści bezpośrednio w bloku czy odświeżony interfejs boczny.

Stara wersja rejestrowania bloku (V2), którą być może jeszcze wykorzystujesz wygląda przykładowo:

function mojblok_register_block() {
  if( function_exists('acf_register_block_type') ) {
    acf_register_block_type([
      'name'              => 'mojblok',
      'title'             => __('Mój Blok'),
      'description'       => __('Treści ostylowane'),
      'category'          => 'formatting',
      'icon'              => 'admin-home',
      'keywords'          => ['moj', 'blok'],
      'render_template'   => get_template_directory() . '/template-parts/blocks/mojblok/render.php',
      'enqueue_style'     => get_template_directory_uri() . '/template-parts/blocks/mojblok/view.css',
      'enqueue_script'    => get_template_directory_uri() . '/template-parts/blocks/mojblok/view.js',
      'enqueue_assets'    => function() {
        wp_enqueue_style('mojblok-editor', get_template_directory_uri() . '/template-parts/blocks/mojblok/editor.css');
        wp_enqueue_script('mojblok-editor', get_template_directory_uri() . '/template-parts/blocks/mojblok/editor.js', ['wp-blocks', 'wp-element'], '1.0', true);
      },
      'supports'          => [
        'anchor' => true,
        'jsx' => true
      ],
      'mode'              => 'preview',
    ]);
  }
}
add_action('acf/init', 'mojblok_register_block');

V2 nie znikną z dnia na dzień, ale będą wypychane z ekosystemu. Coraz więcej funkcji nie będzie z nimi kompatybilna. W praktyce – zostaniesz z technologią, której nikt już nie rozwija, a każda aktualizacja WP może coś niespodziewanie popsuć. Lepiej więc zawczasu zaplanować migrację na V3, kiedy masz nad tym kontrolę.

Jak wygląda block.json i dlaczego to lepsze?

Przejście na block.json to nie tylko wymóg – ale też wygoda. Definiujesz wszystko w jednym miejscu, bez konieczności przepisywania tego w kodzie PHP. WordPress od razu rozpoznaje blok, integruje go z interfejsem Gutenberga i daje dostęp do pełnych możliwości edytora.

Przykład prostego pliku block.json dla ACF V3 może wyglądać tak:

template-parts/blocks/mojblok/block.json

{
  "name": "acf/mojblok", 
  "title": "Mój Blok", 
  "description": "Treści ostylowane", 
  "apiVersion": 3,
  "category": "formatting",
  "icon": "admin-home",
  "keywords": ["moj", "blok"], 
  "supports": { "anchor": true, "jsx": true },
  "style": "file:./view.css", 
  "editorStyle": "mojblok-editor", 
  "viewScript": "mojblok-view", 
  "editorScript": "mojblok-editor",
  "acf": {
    "blockVersion": 3,
    "renderTemplate": "render.php" 
  }
}

Nie musisz rejestrować bloku przez PHP. Wystarczy, że WordPress znajdzie ten plik we właściwej lokalizacji i już może go użyć. Cała konfiguracja, w tym odwołanie do szablonu renderującego (render.php) i stylów, znajduje się właśnie tutaj.

Oczywiście style CSS i skrypty JS rejestrujesz jak zwykle:

function mojblok_register_assets() {
  wp_register_style('mojblok-editor', get_template_directory_uri() . '/template-parts/blocks/mojblok/editor.css', [], '1.0');
  wp_register_script('mojblok-editor', get_template_directory_uri() . '/template-parts/blocks/mojblok/editor.js', ['wp-blocks', 'wp-element'], '1.0', true);
  wp_register_script('mojblok-view', get_template_directory_uri() . '/template-parts/blocks/mojblok/view.js', [], '1.0', true);
}
add_action('init', 'mojblok_register_assets');

A bloki możesz sobie rejestrować choćby w ten sposób:

add_action('init', function () {
  $base = get_theme_file_path('template-parts/blocks');
  foreach (glob($base . '/*/block.json') as $json) {
    register_block_type(dirname($json));
  }
});

Zauważ też, jeśli chcesz aby style CSS bloków ładowały się w zależności od tego czy są użyte na stronie czy nie – zarejestruj wpierw styl za pomocą PHP

  if ( file_exists("$bdir/template-parts/blocks/mojblok/view.css") ) {
      wp_register_style('mojblok', get_stylesheet_directory_uri().'/template-parts/blocks/mojblok/view.css', [], filemtime(get_stylesheet_directory().'/template-parts/blocks/mojblok/view.css'));
  } 

odwołaj się do niego w block.json:

"style": "mojblok",

i pamiętaj o dorzuceniu do functions.php:

add_filter( 'should_load_separate_core_block_assets', '__return_true' );

Wprowadzenie iframe w API bloków V3 to nie tylko kwestia nowych funkcji – to też duży krok w stronę większego bezpieczeństwa i stabilności edytora. Dzięki iframe blok działa w izolowanym środowisku, więc style i skrypty nie mieszają się z resztą interfejsu WordPressa. To ogranicza konflikty i chroni edytor przed nieprzewidywalnym zachowaniem kodu w bloku. Przy V2 wszystko działało w jednej przestrzeni – co przy bardziej złożonych projektach prowadziło do problemów ze stylami, JS-em i trudnym debugowaniem. Przejście na V3 rozwiązuje te bolączki, a WordPress wyraźnie zmierza właśnie w tym kierunku.

Także jeśli tworzysz strony dla klientów, to nie jest dobry moment na zostawanie przy „starym” podejściu. Klientów nie interesuje, czy coś działa „po staremu”, tylko czy strona się nie rozsypie po aktualizacji. A ty – jako deweloper – musisz być o krok przed tym, co WordPress dopiero planuje wprowadzić.

Zacznij migrować bloki. Przepisz chociaż jeden, zobacz jak działa block.json. To naprawdę nie boli, a zaoszczędzisz sobie bólu głowy za rok czy dwa.

źródło: https://www.advancedcustomfields.com/blog/acf-6-6-released/