Schema del documento e blocchi

Nucleo 0.2+FreeLettura ~42 minAggiornato 31 ottobre 2026

Ogni pagina è un documento JSON con un albero di nodi: qui trovi la sua struttura, le regole di validazione e i blocchi disponibili.

In questa pagina

01Panoramica

Ogni pagina, layout, sezione riutilizzabile o popup è un documento JSON con un albero di nodi. Ogni nodo ha un type che rimanda a un blocco registrato. Un blocco è una cartella in nucleo/blocks/ con un manifest block.nucleo.json e un renderer PHP. Il manifest dichiara le proprietà (content, settings), i gruppi di stile, i figli e i genitori ammessi.

Al salvataggio il documento passa da due fasi:

Normalizzazione

Nucleo completa il documento, espande le sezioni e risolve i link interni.

Validazione

Prima si controlla lo schema JSON, poi le regole dei manifest e i controlli propri di alcuni blocchi.

Se c'è almeno un errore, il salvataggio fallisce con il codice invalid_document e l'elenco degli errori.

Compilazione, slot dinamici, CSS e sezioni riutilizzabili sono descritti nella pagina Compilatore e runtime.

Tutti i blocchi di questo capitolo sono Free.

I blocchi non hanno permessi propri. Valgono i permessi dell'ability o del comando che salva il documento, vedi Abilities di scrittura e Comandi WP-CLI.

I blocchi WooCommerce (woo/*) si registrano con l'azione nucleo/register_blocks e sono descritti nella pagina Integrazioni.

02Documento JSON

Chiavi di primo livello

Cosa fa: definisce la forma del documento. additionalProperties: false: ogni altra chiave è un errore.

Come si usa: esempio minimo:

{
  "schema": 1,
  "kind": "page",
  "root": { "id": "a1", "type": "nc/section", "children": [] }
}

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`schema`	intero	`>= 1`	`1`	Obbligatorio nello schema. Se manca, il normalizzatore lo imposta a `1` prima della validazione.
`kind`	stringa	`page`, `layout`, `section`, `popup`	—	Obbligatorio.
`root`	nodo	vedi Nodo	—	Obbligatorio. Radice dell'albero.
`meta`	oggetto	chiave `seo` definita; altre chiavi libere	—	Vedi `meta.seo`.
`params`	oggetto	nome `^[a-z][a-z0-9_]{0,31}$` → `{type, label?, required?}`	—	Parametri di una sezione riutilizzabile. `type`: `text`, `html`, `image`, `link`, `color`, `boolean`, `list`.
`blocks`	oggetto	tipo di blocco → intero `>= 1`	—	Versione di ogni blocco con cui il documento è stato scritto. La usa il migratore.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Lo schema descrive params come valido solo per kind section, ma il validatore non impone questo vincolo.
propertyNames non è applicato dal validatore interno (vedi Sottoinsieme JSON Schema). I nomi dei parametri li controlla l'espansione delle sezioni (invalid parameter name). I nomi in blocks non sono controllati.
Un parametro list accetta al massimo 30 stringhe.

Nodo

Cosa fa: descrive un blocco nell'albero. content, settings e style sono separati: content contiene i testi traducibili, settings il comportamento, style l'aspetto.

Come si usa: esempio di nodo:

{ "id": "a2", "type": "nc/heading",
  "content": { "text": "Consulenza fiscale" },
  "settings": { "level": 1 },
  "style": { "fontSize": { "base": "$text.3xl", "lg": "$text.5xl" } } }

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`id`	stringa	`^[a-z0-9]{1,12}$`	—	Obbligatorio. Unico nel documento.
`type`	stringa	`^[a-z][a-z0-9-]/[a-z][a-z0-9-]$`, blocco registrato	—	Obbligatorio.
`content`	oggetto	chiavi dichiarate in `content` del manifest	—
`settings`	oggetto	chiavi dichiarate in `settings` del manifest	default del manifest	Il normalizzatore aggiunge i default mancanti.
`style`	oggetto	chiavi di stile, `parts`, `custom`	—	Vedi Valori di stile.
`visibility`	oggetto	`breakpoints`, `when`	—	Vedi `visibility`.
`bind`	oggetto	`content.<nome>` o `settings.<nome>` → `{source, field, fallback?}`	—	Vedi `bind`.
`children`	array di nodi	secondo `children` del manifest	—
`ref`	stringa	`^(section):[0-9]+$`	—	Forma storica: riferimento per id a una sezione. Esclude `children`.
`guide`	oggetto	`{ "distinct": stringa 1–200 caratteri, non solo spazi }`	—	Nota per `nucleo guide`: il blocco somiglia a un altro di proposito e non conta tra le ripetizioni della regola R1.5.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

ref e children insieme sono un errore di schema.
Un id non valido produce un solo errore con la proposta corretta: minuscole e cifre, troncato a 12 caratteri (use "abc123").
Un id duplicato è segnalato sulla seconda occorrenza (duplicate id).

`meta.seo`

Cosa fa: definisce title e meta SEO della pagina quando non c'è un plugin SEO attivo.

Come si usa: "meta": { "seo": { "title": "...", "description": "...", "noindex": false } }. L'uso in pagina è descritto nella pagina Integrazioni.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`title`	stringa	max 70 caratteri	—
`description`	stringa	max 170 caratteri	—
`image`	stringa	`format: uri`	—	Il formato non è controllato (vedi limiti).
`noindex`	booleano	—	—
`breadcrumbs`	booleano	—	—	`false`: niente `BreadcrumbList` automatico sulla pagina.
`schema`	array di oggetti	max 10; ogni oggetto ha `@type` `^[A-Z][A-Za-z]{2,60}$`	—	Nodi schema.org della pagina. Il valore `"@business"` rimanda all'azienda del sito.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: seo non accetta altre chiavi oltre a quelle elencate. Il validatore ignora format.

Valori di stile

Cosa fa: ogni chiave di style è una proprietà CSS in camelCase con un valore semplice o un oggetto per breakpoint.

Come si usa: "padding": "$space.4" oppure "padding": { "base": "$space.4", "md": "$space.6" }. I riferimenti $gruppo.chiave sono token, vedi la pagina Design token.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`<chiave>`	stringa, numero, oppure oggetto	oggetto con almeno una chiave tra `base`, `md`, `lg`, `xl`	—	La chiave deve appartenere a un gruppo di `supports.style` del blocco.
`<chiave>Hover`, `<chiave>Current`	come sopra	—	—	Stati. Solo per `color`, `background`, `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `boxShadow`, `opacity`, `filter`, `fontWeight`, `textDecoration`.
`parts`	oggetto	nome della parte dichiarata dal blocco → chiavi di stile	—	Gruppi ammessi in una parte: `size`, `spacing`, `typography`, `color`, `border`, `effects`, `layout`, `motion`.
`custom`	oggetto	selettore che inizia con `&` → proprietà CSS → stringa o numero	—	CSS libero per ciò che le chiavi non coprono.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Un valore stringa non può contenere ;, {, }, <, >, \, /*, */ o caratteri di controllo. Non può contenere url(, expression(, @import, image-set(, image(, cross-fade(, element(, src( o javascript:. Parentesi e virgolette devono essere chiuse. Una stringa vuota non è ammessa.
Un token citato che non esiste nei token del sito produce unknown token.
Selettore di custom: ^&[a-zA-Z0-9_ .:>#()+~*,="'\[\]-]*$. Proprietà di custom: ^-{0,2}[a-z][a-z0-9-]{0,60}$.
Le chiavi con elenco chiuso (position, overflow*, textDecoration, textTransform, whiteSpace, fontStyle, alignSelf, justifySelf e altre) rifiutano gli altri valori. zIndex accetta un intero tra -9999 e 9999.
I valori di motion hanno una validazione dedicata.

`visibility`

Cosa fa: nasconde il nodo per breakpoint (CSS) o per condizione (slot dinamico).

Come si usa: "visibility": { "breakpoints": { "base": false, "lg": true }, "when": [{ "is": "logged_in" }] }. L'effetto a runtime è descritto nella pagina Compilatore e runtime.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`breakpoints`	oggetto	`base`, `md`, `lg`, `xl` → booleano	—
`when[].is`	stringa	`logged_in`, `logged_out`, `role:<slug>` (`[a-z0-9_-]+`), `filled`, `empty`	—	Obbligatorio.
`when[].source`	stringa	`post`, `nucleo`, `item`, `acf`, `metabox`, `jetengine`, `author`, `term`, `site`	—	Obbligatorio con `filled` ed `empty`.
`when[].field`	stringa	non vuota	—	Obbligatorio con `filled` ed `empty`.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: nelle schede di nc/query, nc/collection e nelle righe di nc/repeater sono ammessi solo filled ed empty (codice card_block_not_allowed).

`bind`

Cosa fa: collega una proprietà del nodo a un dato dinamico.

Come si usa: "bind": { "content.text": { "source": "post", "field": "title", "fallback": "—" } }. Sorgenti e risoluzione sono descritte nella pagina Dati dinamici.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
chiave	stringa	`content.<nome>` o `settings.<nome>` dichiarati dal blocco	—	Una chiave non dichiarata produce `bind key not declared in the block`.
`source`	stringa	`post`, `term`, `author`, `site`, `nucleo`, `acf`, `metabox`, `jetengine`, `woo`, `user`, `query`, `param`, `item`	—	Obbligatorio.
`field`	stringa	non vuota	—	Obbligatorio.
`fallback`	stringa	—	—

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Il validatore accetta ogni proprietà dichiarata dal blocco. Ignora supports.bind del manifest.
Dentro una sezione riutilizzabile, le chiavi style.<nome>, visible e repeat sono gestite dall'espansione e rimosse prima della validazione (vedi Compilatore e runtime).
Nelle schede le sorgenti user e query sono vietate (card_block_not_allowed).

03Validazione

Ordine dei controlli

Cosa fa: la validazione restituisce la lista di tutti gli errori. Non si ferma al primo.

Come si usa: la usano il salvataggio e nucleo/doc-validate. Per ogni nodo, in quest'ordine:

JSON Schema del documento.
Tipo registrato. Se manca, l'errore elenca in allowed tutti i tipi registrati.
id: regola e unicità.
Genitore ammesso (parents del manifest).
content e settings: chiavi dichiarate, tipo e vincoli di ogni proprietà, campi required, chiavi degli elementi con item.
style: gruppo supportato, valore ammesso, CSS sicuro, token esistente. Poi style.parts e style.custom.
bind: chiave dichiarata.
Controlli propri del blocco: nc/query, nc/collection, nc/repeater, nc/native-form, nc/embed.
nc/icon: nome dell'icona.
URL in settings.href e content.src.
visibility.when.
Figli ammessi (children del manifest), poi ricorsione sui figli.

Parametri: il documento normalizzato.

Permessi: quelli dell'ability o del comando chiamante.

Edizione: Free

Limiti noti:

I tipi di proprietà dei manifest che non sono tipi JSON (inline-rich-text, rich-text) si validano come string.
Gli errori con stesso path e stesso message compaiono una volta sola.
Senza token il controllo dei token si salta. Il validatore del sito passa sempre i token.
Gli errori sui nodi arrivati da una sezione puntano al nc/section-ref del documento.

Formato dell'errore

Cosa fa: ogni errore indica dove, cosa e come correggere.

Come si usa: ogni errore ha questa forma:

{ "path": "/root/children/0/settings/level", "message": "...", "got": 7,
  "allowed": [1, 2, 3, 4, 5, 6], "fix": "...", "code": "card_missing", "guide": "R3.3" }

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`path`	stringa	JSON Pointer	—	Sempre presente.
`message`	stringa	—	—	Sempre presente, tradotto.
`got`	qualsiasi	—	—	Assente se null.
`allowed`	lista	—	—	Assente se vuota.
`fix`	stringa	—	—	Proposta di correzione.
`code`	stringa	vedi Codici di errore	—	Assente per gli errori di schema.
`guide`	stringa	`R3.3`, `R4.3`	—	Regola di `nucleo guide` collegata al codice.

Permessi: —

Edizione: Free

Limiti noti: al salvataggio l'esito è invalid_document con messaggio Invalid document.. Se ci sono errori style_group_unsupported, il messaggio li riassume tutti in una frase con il posto dove spostare ogni chiave.

Codici di errore

Cosa fa: codici stabili per gli agenti. Gli altri errori hanno solo message.

Come si usa: leggi code nell'elenco errors dell'esito.

Parametri:

Codice	Blocco	Quando
`style_group_unsupported`	tutti	La chiave di stile appartiene a un gruppo che il blocco non ha. `fix` propone i figli che hanno il gruppo, oppure un `doc-patch` `wrap` in `nc/container`, oppure i blocchi che hanno il gruppo.
`card_missing`	`nc/query`	Più di un figlio.
`card_missing`	`nc/repeater`	Numero di figli diverso da 1.
`card_missing`	`nc/collection`	Numero di `nc/collection-card` diverso da 1, oppure scheda con più di un figlio.
`card_block_not_allowed`	schede di `nc/query`, `nc/collection`, `nc/repeater`	Blocco vietato nella scheda, sorgente `user` o `query`, condizione sul visitatore, `nc/repeater` annidato in una riga.
`field_missing`	`nc/repeater`	`settings.field` vuoto.
`card_term_source`	`nc/collection`	Scheda di una collezione `terms` che legge il post o sorgenti diverse da `term`.
`unknown_component`	`nc/collection`, `nc/native-form`	Sorgente o azione `component` non registrata.
`unknown_post_type`	`nc/collection`, `nc/native-form`	Tipo di contenuto non ammesso o non nel modello.
`unknown_taxonomy`	`nc/collection`	Tassonomia non pubblica, o non collegata al tipo di contenuto.
`unknown_term`	`nc/collection`	`settings.parent` non è un termine della tassonomia.
`unknown_field`	`nc/collection`, `nc/native-form`	Campo inesistente o di tipo non ammesso.
`terms_no_filters`	`nc/collection`	Collezione `terms` con filtri o ordinamenti.
`duplicate_key`	`nc/collection`	Chiave di filtro o ordinamento ripetuta, oppure `sort` o `page`.
`bad_ui`	`nc/collection`	`ui` non ammessa per il tipo di filtro.
`duplicate_field`	`nc/native-form`	Nome di campo ripetuto.
`bad_options`	`nc/native-form`	Campo `select`, `radio` o `checkboxes` senza opzioni.
`bad_step`	`nc/native-form`	`step` del campo fuori dai passi del modulo.
`otp_first`	`nc/native-form`	Azione `otp` non in prima posizione, o campo non di tipo `email`.
`otp_step`	`nc/native-form`	`step` dell'azione `otp` non coerente con i passi.
`unverified_recipient`	`nc/native-form`	Azione `email` con `to: "field:<nome>"` senza `otp` sullo stesso campo.
`bad_status`	`nc/native-form`	`create-post` con stato diverso da `draft` o `pending`.
`unsafe_url`	`nc/native-form`, `nc/embed`	`webhook` con URL non `https://`; `settings.url` di `nc/embed` non `https://`.
`invalid_url`	`nc/embed`	Indirizzo YouTube o Vimeo senza un id video valido.

Permessi: —

Edizione: Free

Limiti noti: solo questi codici rimandano a una regola di nucleo guide: card_missing e card_block_not_allowed (R3.3), e component_code (R4.3).

Controllo degli URL

Cosa fa: rifiuta URL pericolosi in settings.href e content.src di ogni nodo.

Come si usa: automatico. Il controllo accetta http, https, mailto, tel e i relativi che iniziano con / (non //), # o ?.

Parametri: nessuno.

Permessi: —

Edizione: Free

Limiti noti:

settings.href accetta anche un riferimento interno: home, page:<slug>, post:<slug>, <post-type>:<slug>, term:<tassonomia>/<slug>. La risoluzione è descritta nella pagina Compilatore e runtime.
Il controllo riguarda solo le due chiavi di primo livello. Non copre settings.parent.href di nc/breadcrumbs, content.poster di nc/video, settings.redirect di nc/native-form né settings.url di nc/embed, che il blocco controlla da sé. I renderer di nc/video e nc/button filtrano i propri valori.

Sottoinsieme JSON Schema

Cosa fa: il validatore interno, senza dipendenze, controlla il documento e le proprietà dei manifest.

Come si usa: interno.

Parametri: parole chiave applicate: type, enum, const, $ref (solo #/$defs/...), allOf, anyOf, oneOf, not, properties, patternProperties, additionalProperties, required, minProperties, items, minItems, maxItems, minLength, maxLength, pattern, minimum, maximum.

Permessi: —

Edizione: Free

Limiti noti:

Le altre parole chiave sono ignorate: tra queste format, propertyNames, uniqueItems.
Ignorate anche min e max, usate dal manifest di nc/slider. I limiti di perView, autoplay e speed li applica solo il renderer.
Un array vuoto vale sia come array sia come oggetto.

04Normalizzazione, versioni e migrazioni

Normalizzatore

Cosa fa: completa il documento prima di validazione e compilazione.

Come si usa: il normalizzatore esegue questi passi, in quest'ordine:

schema mancante diventa 1.
Migrazioni dei blocchi.
Default dei settings dal manifest, per ogni nodo con tipo registrato. I valori espliciti restano.
Nodo con ref: "section:N": diventa il root della sezione N. Gli id interni ricevono il prefisso g<N>, troncati a 12 caratteri. Il nodo tiene il proprio id. Il documento referenziato non segue altri ref.

Parametri: nessuno.

Permessi: —

Edizione: Free

Limiti noti:

I default si applicano solo a settings, non a content.
Un ref non risolto resta com'è.

Attenzione

Il salvataggio memorizza il documento grezzo, non quello normalizzato.

Versione dello schema

Cosa fa: schema è la versione del formato del documento.

Come si usa: scrivi "schema": 1.

Parametri: nessuno.

Permessi: —

Edizione: Free

Limiti noti: l'elenco delle migrazioni del documento è vuoto. Alla versione 0.2.0 non esistono migrazioni del documento.

Migrazioni dei blocchi

Cosa fa: porta ogni nodo alla versione corrente del suo blocco con operazioni dichiarate nel manifest.

Come si usa: nel manifest, migrations associa la versione di arrivo a una lista di operazioni:

"migrations": { "2": [ { "op": "rename", "from": "settings.size", "to": "settings.level" } ] }

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`op: rename`	`from`, `to`	percorso puntato `^[a-zA-Z_][a-zA-Z0-9_-](\.…)$`	—	Solo se `from` esiste e `to` no.
`op: remove`	`path`	percorso puntato	—
`op: set`	`path`, `value`	percorso puntato	—	Solo se `path` non esiste.

Permessi: —

Edizione: Free

Limiti noti:

Le migrazioni applicate sono quelle con versione maggiore di quella salvata in blocks e minore o uguale alla corrente, in ordine numerico.
Un documento senza la versione del blocco in blocks non migra: il sistema registra solo la versione corrente.
Tutti i 41 blocchi sono alla versione 1 e hanno migrations vuoto o assente.

Formato compatto

Cosa fa: riduce il documento per un agente.

Come si usa: lo usa nucleo/doc-get.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`nodeId`	stringa	id di un nodo	null	Restituisce solo quel sottoalbero. Id assente: errore `not_found`.
`depth`	intero	`>= 0`	null	I nodi a profondità `>= depth` perdono `children` e ricevono `childCount`. Negativo: errore `invalid_op`.

Permessi: quelli dell'ability.

Edizione: Free

Limiti noti: toglie content, settings, style, visibility, bind vuoti e i settings uguali al default. Non modifica i token.

Patch del documento

Cosa fa: descrive le operazioni di nucleo/doc-patch.

Come si usa: array di operazioni semantiche per id (insert, move, remove, set, duplicate, wrap) oppure JSON Patch RFC 6902 per path (add, replace, test, remove, move, copy).

Parametri: vedi il capitolo Abilities di scrittura.

Permessi: quelli dell'ability.

Edizione: Free

Limiti noti: baseRevision sta nel contenitore della patch, non nell'array.

05Manifest dei blocchi

Campi del manifest

Cosa fa: Nucleo legge il manifest block.nucleo.json di ogni cartella in nucleo/blocks/. Un manifest non valido blocca il caricamento con un errore che cita il file.

Come si usa: una cartella per blocco con block.nucleo.json, style.css ed eventuale view.js. I renderer dei blocchi nc/* sono inclusi nel plugin.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`name`	stringa	`^[a-z][a-z0-9-]/[a-z][a-z0-9-]$`	—	Obbligatorio. Unico: un duplicato è un errore.
`version`	intero	`>= 1`	—	Obbligatorio.
`title`	stringa	non vuota	—	Obbligatorio.
`category`	stringa	—	`general`
`description`, `aiHints`	stringa	—	`""`	`aiHints` sono le istruzioni per l'agente restituite da `nucleo/catalog-get`.
`content`, `settings`	oggetto	nome → `{type, translatable?, required?, default?, item?, …}`	`{}`	Sottoinsieme di JSON Schema. `item` descrive le chiavi di ogni elemento di un array.
`supports.style`	lista	gruppi di stile	—	Il registro aggiunge i gruppi di base. Vedi Gruppi di stile.
`supports.styleExclude`	lista	`size`, `spacing`, `typography`, `color`, `border`, `motion`	—	Gruppi di base che il blocco non riceve.
`supports.responsive`, `supports.visibility`, `supports.bind`	—	—	—	Informativi: `nucleo/catalog-get` li restituisce, il validatore non li legge.
`parts`	oggetto	nome `^[a-z][a-zA-Z0-9]{0,30}$` → selettore dentro il nodo	`{}`	Parti stilizzabili con `style.parts`.
`children`	booleano o lista di tipi	—	`false`	`true`: qualsiasi figlio. Lista: solo quei tipi.
`parents`	null o lista di tipi	—	`null`	`null`: qualsiasi genitore.
`assets.style`, `assets.script`	stringa o null	percorso relativo alla cartella	—
`assets.strategy`	stringa	`eager`, `visible`, `interaction`, `idle`	`eager`	Caricamento dello script, vedi la pagina Ottimizzatore e asset.
`semantics`	oggetto	`heading`, `image`, `link`, `landmark`, `text`, `embed`	`{}`	Lo usa il motore di qualità. `landmark` accetta `tagFrom` (campo con il tag) o `tag` (tag fisso), e `ifFrom` (campo che deve avere un valore).
`renderer`	stringa	classe che implementa `Nucleo\Blocks\Renderer`	`""`	Se la classe non esiste, Nucleo carica `Renderer.php` dalla cartella del blocco.
`deps`	lista	`^[a-z_]+(?::[A-Za-z0-9_.{}-]+)*$`	`[]`	Chiavi di invalidazione, per esempio `menu:{settings.menu}`.
`migrations`	oggetto	vedi Migrazioni dei blocchi	—

Permessi: —

Edizione: Free

Limiti noti: l'errore Renderer "<classe>" not found for block <tipo> compare solo alla prima compilazione del blocco, non al caricamento.

Gruppi di stile

Cosa fa: ogni chiave di stile appartiene a un gruppo. Un blocco accetta solo le chiavi dei suoi gruppi.

Come si usa: ogni blocco riceve i gruppi di base size, spacing, typography, color, border, motion, salvo supports.styleExclude. I gruppi dichiarati in supports.style si aggiungono. La lista di ogni blocco è nella sua sezione. L'uscita CSS è descritta nella pagina Compilatore e runtime.

Parametri:

Gruppo	Chiavi
`spacing`	`padding`, `margin`, `gap`
`size`	`width`, `maxWidth`, `minWidth`, `maxHeight`, `minHeight`, `height`, `aspectRatio`
`color`	`color`, `background`, `accentColor`
`typography`	`fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFamily`, `fontStyle`, `textAlign`, `textDecoration`, `textTransform`, `whiteSpace`
`layout`	`display`, `columns`, `direction`, `wrap`, `justify`, `align`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `alignSelf`, `justifySelf`
`border`	`border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `boxShadow`
`effects`	`opacity`, `objectFit`, `filter`, `transform`
`position`	`position`, `top`, `right`, `bottom`, `left`, `inset`, `zIndex`, `scrollMarginTop`, `overflow`, `overflowX`, `overflowY`
`motion`	`animation`, `animationDuration`, `animationDelay`, `transition`
`menu`	`itemColor`, `itemColorHover`, `itemColorActive`, `itemBackground`, `itemBackgroundHover`, `itemBackgroundActive`, `itemDecoration`, `itemDecorationHover`, `itemWeight`, `itemWeightActive`, `itemPadding`, `itemRadius`, `itemGap`, `submenuBackground`, `panelWidth`, `panelBackground`
`controls`	`controlBackground`, `controlColor`, `controlBorder`, `controlRadius`, `controlPadding`, `controlFocus`
`buttons`	`buttonBackground`, `buttonColor`, `buttonBorder`, `buttonRadius`, `buttonPadding`
`choices`	`controlBackgroundActive`, `controlColorActive`, `controlBorderActive`, `popoverBackground`
`results`	`resultsColumns`, `resultsGap`
`carousel`	`controlSize`, `dotColor`, `dotColorActive`, `controlsInset`
`link`	`linkColor`, `linkColorHover`, `linkDecoration`, `linkDecorationHover`
`fields`	`labelColor`, `labelSize`, `labelWeight`, `helpColor`, `legendColor`, `legendSize`, `legendWeight`, `legendLine`, `markColor`, `optionalColor`, `optionalSize`, `optionalWeight`, `numberSize`, `numberBorder`, `numberColor`, `numberFont`, `numberFontSize`, `numberWeight`, `controlMinHeight`, `controlBorderHover`, `placeholderColor`, `checkSize`, `checkAccent`, `navJustify`, `fieldGap`, `fieldMinHeight`

Permessi: —

Edizione: Free

Limiti noti: una chiave sconosciuta produce unknown style property. Una chiave nota di un gruppo che il blocco non ha produce style_group_unsupported.

Blocchi di terze parti

Cosa fa: un plugin registra blocchi propri.

Come si usa:

add_action('nucleo/register_blocks', function (Nucleo\Blocks\Registry $r) {
    $r->register(__DIR__ . '/blocks/hero');
});

Parametri: cartella con block.nucleo.json.

Permessi: —

Edizione: Free

Limiti noti: l'azione parte una volta, quando Nucleo costruisce il registro dei blocchi. Un nome già registrato è un errore.

06Blocchi di struttura

`nc/section`

Cosa fa: fascia a tutta larghezza con un contenitore interno div.nc-section__inner.

Come si usa: "type": "nc/section". Genitori: qualsiasi. Figli: qualsiasi.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.tag`	stringa	`section`, `header`, `footer`, `main`, `div`, `aside`, `nav`	`section`	Elemento HTML esterno.
`settings.anchor`	stringa	—	—	Diventa `id` solo se rispetta `^[a-z][a-z0-9-]{0,63}$`.

Stile: spacing, size, color, border, layout, position, motion, typography.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: un'ancora non conforme non produce errore: il renderer omette l'id. Il tag settings.tag determina la semantica landmark.

`nc/container`

Cosa fa: contenitore flex o grid per colonne e gruppi di blocchi. Con href e label diventa una scheda cliccabile.

Come si usa: "type": "nc/container". Genitori: qualsiasi. Figli: qualsiasi.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.layout`	stringa	`flex`, `grid`	`flex`	Classe `nc-container--flex` o `--grid`.
`settings.responsiveMode`	stringa	`media`, `container`	—	`container`: il nodo riceve `container-type:inline-size`.
`settings.anchor`	stringa	—	—	Come in `nc/section`.
`settings.href`	stringa	URL o riferimento interno	—	Con `label`, aggiunge un link `a.nc-container__link` che copre il contenitore.
`settings.label`	stringa	—	—	Nome accessibile (`aria-label`) del link.

Stile: spacing, size, color, border, effects, layout, position, motion, typography.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il link compare solo con entrambi href e label non vuoti. Uno schema javascript:, data: o vbscript: toglie il link.

`nc/spacer`

Cosa fa: spazio vuoto verticale. Stampa <div aria-hidden="true">.

Come si usa: "type": "nc/spacer" con style.height. Figli: nessuno.

Parametri: nessuno.

Stile: size, color, motion.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il manifest esclude color con styleExclude ma lo dichiara tra gli stili supportati. Il gruppo dichiarato vince: color resta ammesso.

`nc/divider`

Cosa fa: linea orizzontale <hr>.

Come si usa: "type": "nc/divider". Figli: nessuno.

Parametri: nessuno.

Stile: spacing, size, color, border, motion, typography.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: nessuno rilevato.

`nc/section-ref`

Cosa fa: inserisce una sezione riutilizzabile (nucleo_section) per slug, con i valori dei parametri.

Come si usa:

{ "id": "p1", "type": "nc/section-ref",
  "settings": { "section": "scheda-prodotto", "params": { "titolo": "Magnesio" } } }

Figli: nessuno. Espansione, dipendenze e ricompilazione sono descritte nella pagina Compilatore e runtime. nucleo/section-list elenca le sezioni.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.section`	stringa	`^[a-z0-9][a-z0-9_-]{0,199}$`	—	Obbligatorio. Slug, non id.
`settings.params`	oggetto	nome del parametro → valore del tipo dichiarato	—

Stile: nessun gruppo (tutti i gruppi di base sono esclusi).

Permessi: quelli del salvataggio del documento. Bozze e sezioni private entrano solo se chi salva ha edit_theme_options, oppure se non c'è un utente collegato (WP-Cron, WP-CLI).

Edizione: Free

Limiti noti:

Il renderer stampa una stringa vuota: il nodo viene sostituito prima della compilazione.
Massimo 4 livelli di sezioni annidate.
Errori dell'espansione: section slug missing, section loop, too many nested sections, section has no root, undeclared parameter, required parameter without value or default, use a value of type …, legacy ref not supported inside a reusable section.

07Blocchi di testo

`nc/heading`

Cosa fa: titolo da h1 a h6.

Come si usa: "type": "nc/heading". Figli: nessuno. Il binding supportato è content.text.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.text`	inline-rich-text	—	—	Obbligatorio, traducibile.
`settings.level`	intero	1–6	`2`

Stile: typography, color, spacing, border, size, motion.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il testo viene ripulito con i tag ammessi: strong, em, b, i, br, p, ul, ol, li, span[class], a[href,target,rel]. Gli altri tag perdono il markup e tengono il testo. script e style spariscono con il loro contenuto.

`nc/text`

Cosa fa: paragrafo con testo ricco limitato, in un <div>.

Come si usa: "type": "nc/text". Figli: nessuno. Il binding supportato è content.html.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.html`	inline-rich-text	tag ammessi per il testo ricco	—	Traducibile.

Stile: typography, color, spacing, border, size, motion. Parte: link (il link nel testo).

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: stessa pulizia di nc/heading.

`nc/list`

Cosa fa: elenco puntato <ul>, con un'icona facoltativa davanti a ogni voce.

Come si usa: "type": "nc/list". Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.items`	array di stringhe	testo ricco	—	Obbligatorio.
`settings.icon`	stringa	nome di icona	—	Stessa icona per ogni voce.

Stile: typography, color, spacing, motion, size, border. Parti: item (il li), icon (l'icona nel li).

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il validatore non controlla settings.icon. Un nome sconosciuto non stampa l'icona, senza errore. Le voci non stringa sono saltate.

08Blocchi media

`nc/image`

Cosa fa: immagine con srcset, sizes, priorità LCP o caricamento differito, e <picture> con formati moderni.

Come si usa: "type": "nc/image". Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.src`	stringa	URL ammesso	—	Obbligatorio.
`content.alt`	stringa	—	—	Ignorato con `decorative`.
`content.width`, `content.height`	intero	`> 0`	—	Scritti solo se positivi.
`content.srcset`, `content.sizes`	stringa	—	—	Senza `srcset`, per un'immagine della libreria media il compilatore usa lo `srcset` di WordPress con i formati intermedi dell'allegato, e scrive `width` e `height` del file se mancano. Senza `sizes`, dentro un antenato con `style.columns` numerico, `sizes` segue la larghezza della colonna per breakpoint, per esempio `(min-width: 768px) min(33.33vw, 1280px), min(100vw, 1280px)`. Fuori dalle colonne e con `width` noto: `(max-width: Wpx) 100vw, Wpx`.
`content.id`	stringa	cifre	—	Id dell'allegato. Altrimenti il renderer lo cerca dall'URL.
`content.sources`	array	`{type, srcset}`; `type`: `image/avif`, `image/webp`, `image/png`, `image/jpeg`	—	Sorgenti manuali di `<picture>`: vincono su quelle automatiche.
`settings.decorative`	booleano	—	`false`	`alt=""` e nessuna priorità LCP.
`settings.formats`	stringa	`auto`, `off`	`auto`	`off`: niente `<picture>`.

Stile: size, border, effects, spacing, position, motion, typography, color.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: la prima immagine non decorativa del documento riceve fetchpriority="high", le altre loading="lazy". Le sorgenti automatiche richiedono l'opzione del sito imageFormats.

`nc/icon`

Cosa fa: icona SVG inline. Un'icona del sito vince su un'icona interna con lo stesso nome.

Come si usa:

{ "id": "i1", "type": "nc/icon", "settings": { "name": "phone" } }

Figli: nessuno. Le icone del sito si aggiungono con nucleo-icons-set o con la CLI (nucleo icons import, nucleo icons add, vedi la pagina CLI locale).

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.label`	stringa	—	—	Con label: `role="img"` e `aria-label`. Senza: `aria-hidden="true"`.
`settings.name`	stringa	`^[a-z][a-z0-9-]{0,40}$`, icona interna o del sito	—

Stile: size, color, spacing, motion, typography, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Icone interne (25): check, arrow-right, phone, mail, map-pin, star, menu, close, plus, minus, clock, truck, wrench, shield, calendar, info, external-link, chevron-down, car, bus, tractor, search, gauge, layers, refresh.
Un nome sconosciuto produce unknown icon con l'elenco in allowed.
Le icone interne usano griglia 24×24, tratto currentColor.

`nc/logo`

Cosa fa: logo del sito (il logo personalizzato di WordPress) con larghezza e altezza esplicite, o il nome del sito. Collegato alla home.

Come si usa: "type": "nc/logo". Figli: nessuno.

Parametri: nessuno.

Stile: size, spacing, motion, typography, color, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il logo è scritto al salvataggio. La dipendenza site ricompila il documento quando cambia.

`nc/video`

Cosa fa: video YouTube o Vimeo con miniatura statica. L'iframe si carica al clic.

Come si usa: "type": "nc/video". Figli: nessuno. Script view.js, strategia interaction.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.provider`	stringa	`youtube`, `vimeo`	—	Obbligatorio.
`content.videoId`	stringa	YouTube `^[A-Za-z0-9_-]{6,20}$`; Vimeo solo cifre	—	Obbligatorio. Un id non conforme diventa vuoto.
`content.title`	stringa	—	—	Obbligatorio, traducibile. Nome del pulsante: `Play: <titolo>`.
`content.poster`	stringa	`https://…` o percorso che inizia con `/`	—	Senza poster: miniatura `i.ytimg.com` per YouTube, nessuna immagine per Vimeo.
`settings.consent`	stringa	`marketing`, `statistics`, `preferences`, `none`	`marketing`	Categoria del plugin di consenso.

Stile: size, border, motion, spacing, typography, color.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: con un plugin di consenso attivo e consent diverso da none, il blocco mostra The video loads after cookie consent.. La miniatura del provider aspetta il consenso. Un poster proprio si carica subito.

`nc/slider`

Cosa fa: carosello. Effetto slide (scroll-snap) o fade (una slide alla volta). Frecce, punti, autoplay con pulsante pausa.

Come si usa: "type": "nc/slider". Ogni figlio è una slide. Figli: qualsiasi. Script view.js, strategia visible.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.label`	stringa	—	`Gallery`	Nome accessibile del carosello.
`content.prevLabel`, `nextLabel`, `pauseLabel`, `playLabel`	stringa	—	testi tradotti	Nomi dei pulsanti.
`settings.perView`	intero	1–4	`1`	Ignorato con `fade`.
`settings.arrows`	booleano	—	`true`
`settings.effect`	stringa	`slide`, `fade`	`slide`
`settings.autoplay`	intero	0–30	`0`	Secondi tra le slide. Con valore `> 0` compare il pulsante pausa.
`settings.loop`	booleano	—	`true`
`settings.dots`	booleano	—	`false`
`settings.controlsPosition`	stringa	`below`, `bottom-left`, `bottom-right`, `bottom-center`	`below`	Fuori da `below` i controlli stanno sopra le slide.
`settings.speed`	intero	100–3000	`500`	Millisecondi, variabile `--nc-slider-speed`.
`settings.pauseOnHover`	booleano	—	`true`

Stile: spacing, border, motion, controls, carousel, size, typography, color.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Il manifest usa min e max, che il validatore ignora. Un valore fuori intervallo passa la validazione e il renderer lo riporta nell'intervallo.
I nomi predefiniti dei pulsanti usano la lingua di chi salva. Per un sito in un'altra lingua scrivili in content.

`nc/embed`

Cosa fa: video YouTube o Vimeo, mappa Google o un altro indirizzo https, con una miniatura statica. L'iframe si carica solo al clic.

Come si usa:

{ "id": "e1", "type": "nc/embed",
  "content": { "title": "Visita guidata" },
  "settings": { "url": "https://youtu.be/abcDEF12345", "aspectRatio": "4:3" } }

Figli: nessuno. Script view.js, strategia interaction.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.title`	stringa	—	—	Obbligatorio, traducibile. Nome del pulsante: `Load: <titolo>`.
`content.poster`	stringa	`https://…` o percorso che inizia con `/`	—	Senza poster: miniatura `i.ytimg.com` per YouTube, nessuna immagine per gli altri.
`settings.url`	stringa	`https://` verso YouTube, Vimeo, Google Maps o un altro sito	—	Obbligatorio.
`settings.aspectRatio`	stringa	`16:9`, `4:3`, `1:1`, `21:9`	`16:9`	Proporzione dell'area del video.
`settings.consent`	stringa	`marketing`, `statistics`, `preferences`, `none`	`marketing`	Categoria del plugin di consenso, come in `nc/video`.

Stile: size, spacing, typography, color, border, motion.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Il validatore segnala unsafe_url se settings.url non è https://, e invalid_url se l'indirizzo YouTube o Vimeo non ha un id valido. Con un indirizzo non valido il renderer non stampa nulla.
YouTube (youtube.com, m.youtube.com, youtube-nocookie.com, youtu.be) richiede un id di 6–20 caratteri. Vimeo (vimeo.com, player.vimeo.com) richiede un id numerico. Google Maps è riconosciuto a parte. Ogni altro https diventa un iframe generico.
Con un plugin di consenso attivo e consent diverso da none, la miniatura del provider aspetta il consenso e compare The content loads after cookie consent..

09Blocchi di azione e interattivi

`nc/button`

Cosa fa: link con aspetto di pulsante. Senza href è un <button type="button">.

Come si usa: "type": "nc/button". Figli: nessuno. Il binding supportato è content.text.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.text`	stringa	—	—	Obbligatorio, traducibile.
`settings.href`	stringa	URL o riferimento interno	—
`settings.variant`	stringa	`primary`, `secondary`, `link`	`primary`	Classe `nc-button--<variante>`.
`settings.newTab`	booleano	—	`false`	`target="_blank" rel="noopener"`.

Stile: typography, color, spacing, size, border, motion.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: un href con schema javascript:, data: o vbscript: trasforma il link in un <button>.

`nc/accordion`

Cosa fa: sezioni espandibili con details e summary. Facoltativo: JSON-LD FAQPage.

Come si usa: "type": "nc/accordion". Figli: nessuno. Nessuno script.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.items`	array	`{title: stringa, html: rich-text}`, entrambi obbligatori	—	Obbligatorio, traducibile.
`settings.openFirst`	booleano	—	`false`	Prima voce aperta.
`settings.faq`	booleano	—	`false`	Aggiunge `<script type="application/ld+json">` `FAQPage`.
`settings.icon`	stringa	`chevron`, `plus`	`chevron`	`plus`: classe `nc-accordion--plus`.

Stile: spacing, color, typography, border, motion, size. Parti: item, summary, panel.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il filtro nucleo/faq_schema con false toglie il JSON-LD. Le voci con domanda o risposta vuota non entrano nel JSON-LD.

`nc/tabs`

Cosa fa: schede ARIA (tablist, tab, tabpanel). Senza JavaScript tutti i pannelli restano visibili.

Come si usa: "type": "nc/tabs". Figli: nessuno. Script view.js, strategia idle.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.items`	array	`{title: stringa, html: rich-text}`, entrambi obbligatori	—	Obbligatorio, traducibile.

Stile: spacing, color, typography, border, motion, size. Parti: tab, panel.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: id generati <id>-tab-N e <id>-panel-N. Senza voci valide il blocco non stampa nulla.

10Blocchi di navigazione

`nc/menu`

Cosa fa: menu di WordPress con sottomenu annidati o a tendina, pannello offcanvas e pannelli mega.

Come si usa: "type": "nc/menu", "settings": { "menu": 12 }. Figli: solo nc/mega-panel. Script view.js, strategia idle. Dipendenza menu:{settings.menu}.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.toggleLabel`	stringa	—	`Menu` tradotto	Testo o `aria-label` del pulsante offcanvas.
`settings.menu`	intero	id di un menu	`0`
`settings.orientation`	stringa	`horizontal`, `vertical`	`horizontal`
`settings.mobile`	stringa	`none`, `offcanvas`	`none`
`settings.submenus`	stringa	`nested`, `dropdown`	`nested`	`dropdown` aggiunge un pulsante per sottomenu.
`settings.toggle`	stringa	`text`, `icon`	`text`	`icon`: icone `menu` e `close`.
`settings.breakpoint`	stringa	`md`, `lg`, `xl`	`md`	Soglia dell'offcanvas.
`settings.panelSide`	stringa	`left`, `right`	`left`

Stile: typography, color, spacing, layout, border, motion, menu, size. Parti: list, link, submenu.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Con menu <= 0, menu inesistente o senza voci il blocco non stampa nulla, senza errore.
aria-label del <nav> è il nome del menu.
Ogni link porta data-nc-mi (id voce), data-nc-mt (oggetto collegato) e data-nc-ma (antenati). La voce corrente la calcola il runtime (vedi la pagina Compilatore e runtime).

`nc/mega-panel`

Cosa fa: pannello a tutta larghezza collegato a una voce di nc/menu. Il manifest lo descrive visibile al passaggio del mouse o al focus da 768px.

Come si usa: figlio di nc/menu, con settings.item uguale all'id della voce. Figli: qualsiasi, anche un nc/section-ref.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.item`	intero	id della voce di menu	`0`

Stile: spacing, color, typography, border, position, motion, size.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: genitore ammesso solo nc/menu. Con più pannelli sulla stessa voce vale il primo. Un pannello con item che non corrisponde a nessuna voce non compare.

`nc/breadcrumbs`

Cosa fa: percorso di navigazione con JSON-LD BreadcrumbList. Con Yoast o Rank Math attivo usa l'output del plugin. È dinamico: si calcola a ogni richiesta.

Come si usa: "type": "nc/breadcrumbs". Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.homeLabel`	stringa	—	`Home`
`settings.archive`	booleano	—	`false`	Aggiunge l'archivio del tipo di contenuto.
`settings.parent`	oggetto	`{label, href}`	—	Voce al posto dell'archivio. Href vuoto o non risolto: voce senza link.
`settings.taxonomy`	stringa	slug di tassonomia	`""`	Primo termine del post con i termini genitori.

Stile: typography, color, spacing, motion, size, border. Parti: list, item, link, current.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: con un plugin SEO le impostazioni del blocco non si applicano. aria-label="Breadcrumb" non è tradotto. settings.parent.href non passa per il controllo URL del validatore.

`nc/search`

Cosa fa: modulo di ricerca del sito (GET su home_url('/'), campo s). Mostra la query corrente.

Come si usa: "type": "nc/search". Figli: nessuno. Dinamico.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.label`	stringa	—	`Search`	Etichetta del campo.
`content.buttonLabel`	stringa	—	`Search`	Testo del pulsante.
`content.placeholder`	stringa	—	—
`settings.hideLabel`	booleano	—	`false`	Classe `screen-reader-text` sull'etichetta.

Stile: typography, color, spacing, size, controls, buttons, motion, border. Parti: label, input, button.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il normalizzatore non aggiunge i default di content. Senza testo il runtime usa Search tradotto nella lingua del visitatore.

`nc/pagination`

Cosa fa: link alle pagine della query principale (paginate_links()). Dinamico.

Come si usa: "type": "nc/pagination" alla fine di un archivio. Figli: nessuno.

Parametri: nessuno.

Stile: typography, color, spacing, motion, size, border. Parti: link, current.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: con una sola pagina non stampa nulla. aria-label="Paginazione" è scritto in italiano nel codice e non è tradotto.

`nc/toc`

Cosa fa: indice della pagina in un <nav>. Lo script evidenzia la sezione corrente durante lo scorrimento.

Come si usa: figli nc/text o nc/button con link #ancora a nc/section o nc/container della pagina. Figli: qualsiasi. Script view.js, strategia visible.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.label`	stringa	—	—	`aria-label` del `<nav>`. Traducibile.

Stile: spacing, size, color, border, effects, layout, position, motion, typography. Parte: link. La voce corrente si stila con le chiavi …Current.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: il validatore non controlla il tipo dei figli né le ancore.

`nc/offcanvas`

Cosa fa: pulsante che apre un pannello laterale con i figli. Il pannello è una finestra di dialogo modale, nascosta finché non si preme il pulsante. Senza JavaScript resta nascosto.

Come si usa: "type": "nc/offcanvas", "settings": { "label": "Menu", "side": "right" }. Figli: qualsiasi, dentro il pannello. Script view.js, strategia idle.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.label`	stringa	—	—	Obbligatorio, traducibile. Testo del pulsante e nome del pannello. Vuoto: nessun output.
`settings.side`	stringa	`left`, `right`	`left`	Lato del pannello.
`settings.width`	stringa	lunghezza CSS semplice: `20rem`, `320px`, `80vw`, `50%`	`20rem`	Altro valore: viene usato `20rem`.

Stile: size, spacing, typography, color, border, motion.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: è un pannello per i figli, non il menu. Il menu ha il suo pannello con settings.mobile di nc/menu.

11Blocchi del post e dell'archivio

Questi blocchi sono dinamici: il compilatore scrive uno slot, e il runtime lo riempie a ogni richiesta. Dentro una scheda leggono il post dell'elemento, altrimenti l'oggetto della richiesta.

`nc/post-title`

Cosa fa: titolo del post corrente.

Come si usa: "type": "nc/post-title". Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.tag`	stringa	`h1`, `h2`, `p`	`h1`
`settings.link`	booleano	—	`false`	Il titolo diventa un link al post.

Stile: typography, color, spacing, link, motion, size, border. Parte: link.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: fuori da un post non stampa nulla.

`nc/post-content`

Cosa fa: contenuto del post richiesto, passato per il filtro the_content.

Come si usa: una volta nei layout single. Figli: nessuno.

Parametri: nessuno.

Stile: typography, color, spacing, motion, size, border. Parte: link.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: legge sempre l'oggetto della richiesta, non la scheda. Una guardia evita la ricorsione. Vietato nelle schede.

`nc/post-image`

Cosa fa: immagine in evidenza del post, con <picture> e formati moderni.

Come si usa: "type": "nc/post-image". Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.size`	stringa	dimensione registrata, `^[a-z0-9_-]+$`	`large`	Valore non conforme: `large`.
`settings.priority`	booleano	—	`false`	`fetchpriority="high"` e `loading="eager"`. Altrimenti `lazy`.
`settings.formats`	stringa	`auto`, `off`	`auto`

Stile: spacing, size, border, effects, motion, typography, color.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: senza immagine in evidenza non stampa nulla.

`nc/post-meta`

Cosa fa: data, autore, categorie e termini di tassonomie del post.

Come si usa:

{ "id": "m1", "type": "nc/post-meta", "settings": { "fields": ["date", "tax:genere"] } }

Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.fields`	array di stringhe	`^(date\	author\	categories\	tax:[a-z0-9_-]+)$`	`["date"]`	La data va in `<time datetime>`.
`settings.terms`	stringa	`text`, `chips`	`text`	`chips`: classe `nc-post-meta--chips`, termini senza virgole.

Stile: typography, color, spacing, motion, size, border. Parti: item, term, link.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: tax: mostra solo tassonomie visibili. Senza voci non stampa nulla.

`nc/archive-title`

Cosa fa: titolo dell'archivio senza prefisso ("Categoria:"). Con una ricerca: Results for: <query>.

Come si usa: "type": "nc/archive-title". Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.level`	intero	1, 2, 3	`1`

Stile: typography, color, spacing, motion, size, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: titolo vuoto: nessun output.

`nc/archive-description`

Cosa fa: descrizione dell'archivio, filtrata con wp_kses_post.

Come si usa: "type": "nc/archive-description". Figli: nessuno.

Parametri: nessuno.

Stile: typography, color, spacing, motion, size, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: descrizione vuota: nessun output.

12Blocchi di elenco e collezione

Le schede di nc/query, nc/collection e le righe di nc/repeater seguono queste regole:

Blocchi vietati: nc/query, nc/collection, nc/pagination, nc/form, nc/native-form, nc/search, nc/breadcrumbs, nc/archive-title, nc/archive-description, nc/post-content, nc/menu, nc/mega-panel e ogni woo/*.
Sorgenti di bind vietate: user, query.
Condizioni visibility.when ammesse: solo filled ed empty.

L'errore è sempre card_block_not_allowed. Bind e runtime delle schede sono descritti nella pagina Dati dinamici.

`nc/query`

Cosa fa: elenco di post disegnato al salvataggio. Con relatedTo diventa uno slot: post correlati al post corrente, calcolati a ogni richiesta e messi in cache.

Come si usa: senza figli usa una scheda fissa: immagine medium_large, titolo h2 con link, estratto. Con un figlio, il figlio è la scheda ripetuta per ogni post. Figli: al massimo 1. Dipendenza query:{settings.postType}.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.postType`	stringa	tipo di contenuto registrato	`post`	Tipo inesistente: elenco vuoto.
`settings.perPage`	intero	1–24	`6`
`settings.taxonomy`	stringa	slug di tassonomia	`""`	Filtro fisso, con `term`.
`settings.term`	stringa	slug di termine	`""`
`settings.relatedTo`	stringa	slug di tassonomia	`""`	Post dello stesso tipo con un termine in comune, escluso il corrente.
`settings.orderby`	stringa	`date`, `title`	`date`	`date` decrescente, `title` crescente.
`settings.empty`	stringa	—	`No content`	Testo senza risultati. Con `relatedTo`, `""` non stampa nulla.

Stile: spacing, layout, typography, color, position, motion, size, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Solo post pubblicati e senza password.
Cache di relatedTo: gruppo nucleo_related della cache a oggetti, con persistenza di 24 ore. Senza cache a oggetti persistente, il valore va nei meta _nucleo_related del post corrente.
Il default No content è in inglese e la traduzione del renderer non si applica.

`nc/repeater`

Cosa fa: ripete il figlio (la riga) per ogni riga di un campo ripetitore del post corrente. Dinamico.

Come si usa: un figlio con bind {"source": "item", "field": "<sottocampo>"}. La sorgente item offre anche index, da 1. Figli: esattamente 1.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.field`	stringa	chiave di un campo `repeater` del modello	`""`	Vuoto: errore `field_missing`.
`settings.tag`	stringa	`div`, `ul`, `ol`	`div`	Con `ul` e `ol` ogni riga sta in `li.nc-repeater__item`.
`settings.empty`	stringa	—	`""`	Testo senza righe. Vuoto: nessun output.

Stile: spacing, layout, typography, color, motion, size, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free per il blocco. Il campo repeater del modello contenuti è Pro.

Pro

Il blocco legge solo i campi repeater del modello dei contenuti di Nucleo.

Limiti noti: un nc/repeater dentro una riga è vietato (card_block_not_allowed). index non sostituisce un sottocampo con lo stesso nome.

`nc/collection`

Cosa fa: elenco filtrabile e ordinabile di post, termini o dati di un componente. Filtri e risultati si aggiornano senza ricaricare la pagina.

Come si usa: figli ammessi nc/collection-card (esattamente uno), nc/collection-count, nc/collection-reset, nc/collection-empty. Script view.js, strategia visible. Dipendenza query:{settings.postType}. Runtime, URL dei filtri e sorgenti component sono descritti nella pagina Dati dinamici.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.filtersLabel`, `applyLabel`, `moreLabel`, `sortLabel`, `closeLabel`, `resultsLabel`, `allLabel`, `upcomingLabel`, `pastLabel`, `monthLabel`, `fromLabel`, `toLabel`, `gridLabel`, `rowsLabel`	stringa	—	traduzioni del plugin	`resultsLabel`: `{count}` o `%d`; `singolare\	plurale`.
`settings.source`	stringa	`posts`, `component`, `terms`	`posts`
`settings.component`	stringa	sorgente dati registrata	`""`	Con `source: component`.
`settings.postType`	stringa	tipo pubblico del modello	`""`	Con `source: posts`.
`settings.taxonomy`	stringa	tassonomia pubblica, non `nav_menu` né `wp_*`	`""`	Con `source: terms`.
`settings.parent`	stringa	`""` (tutti), `"0"` (primo livello), slug di termine	`""`	Con `source: terms`.
`settings.hideEmpty`	booleano	—	`true`	Con `source: terms`.
`settings.cardSize`	stringa	`auto`, `small`	`auto`	`small`: colonna minima 9rem invece di 16rem.
`settings.perPage`	intero	1–48	`12`
`settings.orderby`	stringa	post: `date`, `title`, `menu_order`, `field:<chiave>`; termini: `name`, `slug`, `count`, `field:<chiave>`	post `date`, termini `name`	`field:` richiede un campo `number`, `date`, `text` o `select`.
`settings.order`	stringa	`asc`, `desc`	post `desc`, termini `asc`
`settings.prefix`	stringa	—	`f`	Prefisso dei parametri URL.
`settings.filters`	array	max 12 elementi	`[]`	Vedi sotto.
`settings.sorts`	array	max 8; `{key, label, orderby, order}` tutti obbligatori	`[]`
`settings.views`	array	`grid`, `rows`	`["grid"]`
`settings.paging`	stringa	`pages`, `more`, `none`	`pages`
`settings.counts`	booleano	—	`true`
`settings.mobileFilters`	stringa	`drawer`, `inline`	`drawer`

Elemento di settings.filters (key, label, type, ui obbligatori):

`type`	Chiavi	`ui` ammesse
`taxonomy`	`taxonomy` collegata al tipo di contenuto, `multiple?`	`pills`, `select`, `checkboxes`, `dropdown`
`field`	`field` di tipo `select` o `boolean`	`pills`, `select`, `checkboxes`, `dropdown`
`field`	`field` di tipo `number` o `date`	`range`
`date`	`field?` di tipo `date`, `presets?` (`upcoming`, `past`, `month`)	`pills`, `select`, `range`
`search`	—	`text`
`param`	`param` dichiarato dalla sorgente `component`. Con `range` servono `<param>_min` e `<param>_max`	—

Stile: spacing, layout, typography, color, position, motion, controls, buttons, choices, border, results, size. resultsColumns: da 1 a 12 colonne, anche per breakpoint.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Codici di validazione: unknown_component, unknown_post_type, unknown_taxonomy, unknown_term, unknown_field, terms_no_filters, duplicate_key, bad_ui, card_missing, card_term_source, card_block_not_allowed.
Chiavi di filtro e ordinamento riservate: sort, page.
Con source: terms la scheda non può contenere nc/post-title, nc/post-image, nc/post-meta, nc/repeater né sorgenti post, nucleo, item, author, acf, metabox, jetengine.

`nc/collection-card`

Cosa fa: scheda di nc/collection. Il suo unico figlio si ripete per ogni elemento.

Come si usa: figlio di nc/collection, con un solo figlio (per esempio nc/container). Figli: qualsiasi, nei limiti delle regole delle schede.

Parametri: nessuno.

Stile: gruppi di base. Il renderer non stampa nulla: lo stile del nodo non ha effetto visibile.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: genitore ammesso solo nc/collection. Più di un figlio: card_missing.

`nc/collection-count`

Cosa fa: numero dei risultati di nc/collection.

Come si usa: figlio facoltativo di nc/collection. Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.text`	stringa	`{count}` o `%d`; due forme `singolare\	plurale`	—	Senza segnaposto il numero va davanti. Una barra verticale preceduta da backslash è letterale; `%%` scrive `%`. Senza testo vale `resultsLabel` della collezione.
`content.one`	stringa	—	—	Testo per un solo risultato.

Stile: typography, color, spacing, size, border, motion. La collezione applica le classi del nodo.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: genitore ammesso solo nc/collection.

`nc/collection-empty`

Cosa fa: contenuto mostrato da nc/collection senza risultati.

Come si usa: figlio facoltativo di nc/collection, per esempio con un nc/text. Figli: qualsiasi.

Parametri: nessuno.

Stile: gruppi di base. La collezione stampa solo i figli: lo stile del nodo non ha effetto visibile.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: senza questo blocco la collezione non mostra nulla quando non ci sono risultati.

`nc/collection-reset`

Cosa fa: link che azzera i filtri di nc/collection.

Come si usa: figlio facoltativo di nc/collection. Figli: nessuno.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.text`	stringa	—	—	Testo del link. Traducibile.

Stile: typography, color, spacing, border, size, motion. La collezione applica le classi del nodo.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: genitore ammesso solo nc/collection.

13Blocchi di codice

Questi due blocchi stampano codice che non passa dai controlli di stile e di accessibilità. Richiedono unfiltered_html.

`nc/html`

Cosa fa: stampa il codice HTML così com'è, dentro un div con le classi del blocco. WordPress non lo filtra.

Come si usa: "type": "nc/html", "content": { "html": "<p>Testo</p>" }. Figli: nessuno. Usalo solo se nessun altro blocco va bene: per il testo ricco preferisci nc/text.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.html`	stringa	—	—	Obbligatorio. Stampato senza pulizia.

Stile: size, spacing, typography, color, border, motion.

Permessi: chi salva il documento deve avere unfiltered_html, altrimenti il contenuto non si conserva.

Edizione: Free

Limiti noti: il codice non viene controllato né per lo stile né per l'accessibilità.

`nc/shortcode`

Cosa fa: stampa l'output di uno shortcode di WordPress, eseguito a ogni richiesta.

Come si usa: "type": "nc/shortcode", "content": { "shortcode": "[gallery ids=\"1,2\"]" }. Figli: nessuno. Preferisci un blocco nativo quando esiste.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.shortcode`	stringa	inizia con `[` e finisce con `]`	—	Obbligatorio.

Stile: size, spacing, typography, color, border, motion.

Permessi: chi salva il documento deve avere unfiltered_html, altrimenti il contenuto non si conserva.

Edizione: Free

Limiti noti: il validatore controlla solo la forma […]. Lo shortcode non viene verificato.

14Blocchi di modulo

`nc/form`

Cosa fa: inserisce un modulo di un plugin esterno con il suo shortcode, a ogni richiesta.

Come si usa:

{ "id": "f1", "type": "nc/form", "settings": { "plugin": "cf7", "id": "123" } }

Figli: nessuno. Dipendenza form:{settings.plugin}.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`settings.plugin`	stringa	`cf7`, `gravity`, `wpforms`, `fluent`	—	Obbligatorio. Shortcode: `contact-form-7`, `gravityform … ajax="true"`, `wpforms`, `fluentform`.
`settings.id`	stringa	—	—	Obbligatorio. Id del modulo nel plugin.

Stile: spacing, typography, motion, size, color, border.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Attenzione

Il blocco non verifica che il plugin sia attivo. Con id vuoto non stampa nulla.

`nc/native-form`

Cosa fa: modulo nativo con campi, passi e azioni: verifica del codice via email, salvataggio, email, webhook, creazione di un post, azione di un componente.

Come si usa: "type": "nc/native-form". Figli: nessuno. Script view.js, strategia interaction. Invio, captcha, OTP e azioni a runtime sono descritti nella pagina Dati dinamici.

Parametri:

Nome	Tipo	Valori ammessi	Default	Note
`content.submitLabel`, `successMessage`, `errorMessage`, `codeLabel`, `nextLabel`, `backLabel`, `sentMessage`, `sendCodeLabel`, `verifyLabel`, `otpFailedMessage`, `expiredMessage`, `requiredMark`, `optionalMark`, `captchaMessage`	stringa	—	—	Traducibili.
`settings.fields`	array	max 40	`[]`	Vedi sotto.
`settings.steps`	array	`{title}` obbligatorio	`[]`
`settings.actions`	array	vedi sotto	`[]`
`settings.redirect`	stringa	`home`, `page:<slug>`, URL	—	Vuoto: resta il messaggio di esito.
`settings.captcha`	booleano	—	`true`	`false` toglie il captcha del sito da questo modulo.
`settings.groupNumbering`	stringa	`none`, `letters`, `numbers`, `letters-box`, `numbers-box`	`none`	Numera le legend dei gruppi.

Elemento di settings.fields (name e type obbligatori):

Chiave	Tipo	Valori ammessi	Default
`name`	stringa	unico nel modulo	—
`type`	stringa	`text`, `email`, `tel`, `url`, `textarea`, `number`, `date`, `select`, `radio`, `checkboxes`, `checkbox`, `consent`, `hidden`, `context`	—
`label`, `help`, `placeholder`, `group`	stringa	—	—
`required`	booleano	—	—
`step`	intero	`>= 0`, sotto il numero dei passi	`0`
`maxLength`	intero	`>= 1`	—
`min`, `max`	numero o stringa	—	—
`decimals`	intero	`>= 0`	—
`options`	array	`{value, label?}`; obbligatorio per `select`, `radio`, `checkboxes`	—
`value`	stringa o numero	—	—
`from`	stringa	`post.id`, `post.title`, `post.url`	—
`width`	stringa	`full`, `half`	`full`

Elemento di settings.actions (type obbligatorio):

`type`	Chiavi	Regole
`otp`	`field`, `subject?`, `body?`, `ttl` (5–30, default 15), `step?`	Prima azione. `field` di tipo `email`. `step` sotto l'ultimo passo e non prima del passo del campo.
`save`	—	—
`email`	`to`, `replyTo?`, `subject?`, `body?`	`to: "field:<nome>"` richiede un `otp` sullo stesso campo.
`webhook`	`url`	Solo `https://`.
`create-post`	`postType`, `status`, `title?`, `fields?`	`postType` del modello. `status` `draft` o `pending`.
`component`	`name`, `input?`	Azione registrata da un plugin.

Stile: size, spacing, typography, color, border, motion, controls, buttons, fields. Parti: field, label, legend, number, legendLine, mark, optional, help, control, placeholder, check, nav, button, message.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti:

Codici di validazione: duplicate_field, bad_options, bad_step, otp_first, otp_step, unverified_recipient, unknown_field, unknown_post_type, bad_status, unsafe_url, unknown_component.
I segnaposto {field:<nome>} in subject, body, title, fields e input devono citare un campo del modulo (unknown_field).

Questa pagina ti è stata utile?