Block API Version 3 e il Post Editor Iframed in WordPress 7.0: Guida alla Migrazione

WordPress 7.0 è in arrivo e porta una breaking change silenziosa che rischia di rompere i tuoi blocchi custom: il post editor diventa sempre iframed, indipendentemente dalla versione API dei blocchi registrati. Se hai sviluppato blocchi con Block API version 1 o 2, devi agire prima del rilascio.

Questo articolo spiega cosa cambia, perché cambia, e come migrare i tuoi blocchi a Block API version 3 senza rompere niente in produzione.

TL;DR

• In WordPress 7.0, il post editor sarà sempre eseguito dentro un iframe
• Blocchi con API version 1 o 2 che dipendono dal document globale o da CSS globali potrebbero smettere di funzionare
• La migrazione a Block API version 3 richiede di aggiungere "apiVersion": 3 al block.json e verificare le dipendenze da document e window
• Il Gutenberg plugin 22.6 già forza l’iframe anche per i temi classici — testa adesso

Cos’era il problema con il post editor non-iframed

Il Site Editor, il Template Editor e tutti gli editor basati su blocchi sono stati eseguiti dentro un iframe già da anni. Questo isola gli stili dei blocchi e del tema dall’interfaccia di WordPress, evitando conflitti CSS e rendendo l’esperienza di editing più fedele al frontend.

Il post editor era l’unica eccezione. Fino a WordPress 6.x, il post editor veniva eseguito in iframe solo se tutti i blocchi registrati nell’installazione usavano Block API version 3 o superiore. Bastava un singolo plugin con un blocco v1 o v2 per far ricadere l’intero editor in modalità non-iframed.

Il risultato: comportamenti inconsistenti tra post editor e site editor, difficoltà nel testare i blocchi, e una superficie di attacco per conflitti CSS difficili da debuggare.

Cosa cambia in WordPress 7.0

La logica cambia radicalmente. Invece di controllare tutti i blocchi registrati nell’installazione, WordPress 7.0 controlla solo i blocchi effettivamente inseriti nel post corrente.

Il funzionamento concreto è questo:

• Se tutti i blocchi inseriti nel post usano API version 3 o superiore → il post editor viene eseguito in iframe
• Se almeno un blocco inserito usa API version 1 o 2 → l’iframe viene rimosso per garantire la compatibilità

Questo è documentato nel PR #75187 del repository Gutenberg e spiegato nel dev note ufficiale su make.wordpress.org.

Nota importante: in WordPress 7.0 l’iframe non è ancora forzato in modo incondizionato. Il rollout è graduale. Ma dal Gutenberg plugin 22.6, l’iframe è già enforced anche per i temi classici, indipendentemente dalla versione API. Se hai il plugin Gutenberg attivo, stai già subendo questo comportamento.

Block API version 3: cosa introduce e perché è rilevante per l’iframe

Block API version 3 è stata introdotta in WordPress 6.3. La modifica principale rispetto alla version 2 è che i blocchi dichiarano esplicitamente di essere compatibili con l’editor iframed.

Ecco la differenza pratica tra le versioni:

Come capire se i tuoi blocchi sono a rischio

Il sintomo principale di un blocco non compatibile con l’editor iframed si manifesta in due modi:

1. Dipendenza dal document o window globale

Se il tuo blocco fa qualcosa del tipo:

// ⚠️ Problematico nell'editor iframed
document.querySelector('.my-custom-element');
window.myGlobalVariable;
document.body.classList.add('my-class');

Dentro un iframe, document e window si riferiscono al documento dell’iframe, non al documento padre. Questo rompe qualsiasi codice che assume di avere accesso al DOM del backend di WordPress.

La soluzione corretta è usare le API di React e i ref di WordPress:

import { useRef, useEffect } from '@wordpress/element';

const Edit = () => {
    const blockRef = useRef();

    useEffect(() => {
        if ( blockRef.current ) {
            // Accede al DOM del blocco in modo sicuro, dentro o fuori iframe
            const element = blockRef.current.querySelector('.my-custom-element');
        }
    }, []);

    return (
        <div { ...useBlockProps({ ref: blockRef }) }>
            { /* contenuto del blocco */ }
        </div>
    );
};

2. CSS globali che dipendono dall’ambiente del documento padre

Stili che vengono iniettati nel <head> del documento padre o che usano selettori basati sul body non funzionano dentro un iframe. Ogni iframe ha il suo documento separato.

Se il tuo blocco usa wp_enqueue_style() per aggiungere stili nell’editor, questi vengono caricati nel documento iframe in WordPress 6.3+, ma verificare che i selettori non assumano la presenza di classi sul body esterno è comunque necessario.

Come migrare un blocco a Block API version 3

La migrazione base si riduce a tre passaggi.

Passo 1: Aggiorna block.json

{
    "name": "mio-plugin/mio-blocco",
    "apiVersion": 3,
    "title": "Mio Blocco",
    "category": "common",
    "attributes": { ... },
    "supports": { ... }
}

Se non hai un block.json (blocchi registrati via PHP diretto), il parametro da aggiungere nell’array di register_block_type() è 'api_version' => 3.

Passo 2: Assicurati di usare useBlockProps()

Block API version 3 richiede useBlockProps() nell’edit e useBlockProps.save() nel save (già obbligatorio dalla v2). Se stai già usando v2, questo è già a posto.

import { useBlockProps } from '@wordpress/block-editor';

export default function Edit() {
    const blockProps = useBlockProps();
    return (
        <div { ...blockProps }>
            { /* contenuto */ }
        </div>
    );
}

import { useBlockProps } from '@wordpress/block-editor';

export default function Save() {
    const blockProps = useBlockProps.save();
    return (
        <div { ...blockProps }>
            { /* contenuto */ }
        </div>
    );
}

Passo 3: Testa nell’editor iframed

Il modo più rapido per testare senza installare nulla è WordPress Playground con Gutenberg nightly. Carica il tuo plugin e verifica che il blocco funzioni correttamente nel post editor.

Se non hai accesso a Playground, attiva il plugin Gutenberg (versione 22.6+) in un ambiente di sviluppo locale. Dal 22.6, l’iframe è già enforced anche per i temi classici.

Casi edge da gestire

Non tutti i problemi si risolvono con l’aggiornamento della versione API. Ecco i casi più comuni che incontrerai durante la migrazione.

Script di terze parti che manipolano il DOM

Se il tuo blocco inizializza una libreria JavaScript di terze parti nell’editor (slider, editor rich text custom, mappe), verifica che la libreria accetti un elemento DOM come target invece di operare su document direttamente. La maggior parte delle librerie moderne supporta questo pattern.

Blocchi con render_callback PHP

I blocchi dinamici (renderizzati lato server via PHP) non sono direttamente impattati dal cambiamento dell’iframe perché il loro output viene generato sul server. Il componente Edit lato JavaScript rimane soggetto alle stesse regole degli altri blocchi.

Plugin che registrano blocchi v1 legacy

Se gestisci siti con plugin di terze parti che usano ancora blocchi v1 o v2, il tuo blocco v3 perfettamente migrato potrebbe comunque non attivare l’iframe perché altri blocchi nel post usano versioni precedenti. La situazione migliorerà man mano che l’ecosistema si allinea.

Come verificare la versione API dei blocchi installati

Per avere una panoramica rapida di tutti i blocchi registrati e le loro versioni API, puoi usare WP-CLI:

# Lista tutti i blocchi registrati
wp block list --fields=name,title --format=table

# Per vedere i dettagli di un blocco specifico
wp block get mio-plugin/mio-blocco

In alternativa, dal pannello di amministrazione puoi usare il plugin Query Monitor che mostra i blocchi registrati e le loro proprietà.

Per verificare che un blocco specifico stia effettivamente causando la non-attivazione dell’iframe, apri il browser DevTools sul post editor e cerca nel pannello Network se la richiesta all’editor contiene riferimenti al parametro is_iframe.

Timeline da tenere a mente

• WordPress 6.3 (agosto 2023): introdotto Block API version 3
• WordPress 6.9 (novembre 2025): Block Visibility introdotto; preparazione per iframe completo annunciata
• Gutenberg 22.6 (febbraio 2026): iframe enforced per temi classici nel plugin Gutenberg
• WordPress 7.0 (primavera 2026): logica iframe cambia da “tutti i blocchi registrati” a “blocchi inseriti nel post” — rollout graduale, non enforcement incondizionato
• Versione futura: enforcement completo e incondizionato dell’iframe

Il messaggio del core team è chiaro: il rollout è graduale per raccogliere feedback, ma la direzione è definitiva. Prima aggiorni i tuoi blocchi, meno lavoro di emergenza farai quando l’enforcement diventerà obbligatorio.

Risorse ufficiali

• Iframed Editor Changes in WordPress 7.0 — make.wordpress.org
• Block API Versions — Block Editor Handbook
• Migration guide per compatibilità iframe — Block Editor Handbook
• What’s new for developers — February 2026 — WordPress Developer Blog

FAQ

Il mio blocco usa Block API version 2 ma non tocca mai document. Devo migrare?

Tecnicamente il blocco continuerà a funzionare anche in un editor iframed per la maggior parte dei casi. Ma dichiarare apiVersion: 3 segnala esplicitamente la compatibilità, permette al post editor di attivarsi in iframe quando tutti i blocchi nel post sono v3+, e riduce la superficie di problemi futuri. Conviene aggiornare.

Cosa succede ai blocchi con API version 1 o 2 quando l’iframe è attivo?

In WordPress 7.0, se un post contiene almeno un blocco v1 o v2, l’iframe viene rimosso per quel post specifico. I blocchi continuano a funzionare. Il problema si presenterà quando l’enforcement diventerà incondizionato nelle versioni future.

Come testo se il post editor è effettivamente iframed?

Apri il post editor, fai tasto destro sull’area di editing e verifica se appare l’opzione “Visualizza sorgente del frame” (Chrome/Firefox). Se l’editor è in un iframe, l’opzione è presente. Alternativamente, nel pannello Elements di DevTools cerca un elemento <iframe> che contiene il markup dell’editor.

Se gestisco siti per clienti con plugin di terze parti, devo aspettarmi problemi?

Dipende dai plugin installati. Plugin con blocchi sviluppati dopo WordPress 6.3 sono probabilmente già a v3. Plugin più vecchi o non mantenuti attivamente potrebbero ancora usare v1 o v2. Con WordPress 7.0, questo ritarderà semplicemente l’attivazione dell’iframe per quei post — non romperà niente. Quando l’enforcement sarà completo, quei plugin potrebbero mostrare comportamenti anomali nell’editor.

FAQ

Devo migrare i miei blocchi a Block API version 3 prima di WordPress 7.0?
Sì, è fortemente consigliato. In WordPress 7.0, la logica di attivazione dell’iframe cambia: invece di controllare tutti i blocchi registrati, controlla solo quelli inseriti nel post. Se i tuoi blocchi restano a version 2 o inferiore, il post editor non sarà iframed per quei post. Quando l’enforcement diventerà incondizionato nelle versioni future, i blocchi non aggiornati potrebbero mostrare comportamenti anomali.

Come verifico se i miei blocchi custom sono compatibili con l’editor iframed?
Il modo più rapido è usare WordPress Playground con Gutenberg nightly attivo. Carica il tuo plugin, apri il post editor e verifica che il blocco funzioni correttamente. Controlla in particolare che il codice JavaScript non usi document o window per accedere a elementi fuori dal blocco, e che i CSS non dipendano da selettori sul body esterno.

Cosa cambia tra Block API version 2 e version 3?
La differenza principale è la dichiarazione esplicita di compatibilità con l’editor iframed. La version 2 ha introdotto l’obbligo di useBlockProps() per il wrapper del blocco. La version 3 aggiunge il segnale che il blocco è testato e funzionante all’interno di un iframe, permettendo al post editor di attivarsi in modalità iframed quando tutti i blocchi presenti nel post dichiarano version 3 o superiore.

Il Gutenberg plugin 22.6 forza già l’iframe. Cosa significa in pratica?
Significa che se hai il plugin Gutenberg versione 22.6 o superiore attivo (anche con tema classico), il post editor è già eseguito in iframe indipendentemente dalla versione API dei blocchi. Questo è il canale di test per raccogliere feedback prima del rollout su WordPress core. Se hai blocchi che si comportano in modo strano nell’editor dopo l’aggiornamento di Gutenberg, la causa è probabile questa.