# Configurazione: riquadri

> Stili con nome per i riquadri :::callout: cornice, sfondo, fascia, titolo, icona e marcatore, enunciati numerati, tipografia dentro il riquadro e riquadri divisi tra più pagine

- Versione HTML: https://postext.dev/it/docs/configuration-callouts
- Ultimo aggiornamento: 2026-10-16
- Tempo di lettura: 27 min
- Altre lingue: [en](https://postext.dev/en/docs/configuration-callouts.md), [es](https://postext.dev/es/docs/configuration-callouts.md), [ca](https://postext.dev/ca/docs/configuration-callouts.md), [de](https://postext.dev/de/docs/configuration-callouts.md), [fr](https://postext.dev/fr/docs/configuration-callouts.md), [pt](https://postext.dev/pt/docs/configuration-callouts.md), [zh](https://postext.dev/zh/docs/configuration-callouts.md), [ja](https://postext.dev/ja/docs/configuration-callouts.md), [ar](https://postext.dev/ar/docs/configuration-callouts.md)

## In breve

Questa pagina riguarda i riquadri che separano dal testo una nota, un suggerimento, un’avvertenza o un elenco di obiettivi. Dai a ogni tipo di riquadro un nome e un aspetto: lo sfondo, il bordo, una fascia colorata, un titolo e un’icona. Un riquadro può avere un numero, come un teorema o un esempio in un libro di testo. Scegli i font dentro il riquadro. Quando un riquadro lungo continua nella pagina seguente, scegli che cosa segna l’interruzione.

## Stili dei riquadri

La proprietà `calloutStyles` dichiara gli stili di riquadro con nome che un documento applica con un contenitore `:::callout{type="…"}`: note, suggerimenti, avvertenze, obiettivi di apprendimento, qualsiasi contenuto separato dal testo corrente in un riquadro colorato o bordato. Per impostazione predefinita è incluso uno stile neutro, `note` (sfondo grigio chiaro, nessun bordo, nessuna fascia, nessuna icona, nessun titolo), così `:::callout` funziona senza alcuna configurazione; dichiarare `calloutStyles` sostituisce questo elenco predefinito.

```ts
const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};
```

```md
:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::

:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::
```

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `id` | `string` | — | Identificatore selezionato da `:::callout{type="…"}`. Un recinto con un `type` sconosciuto o assente usa il primo stile configurato (la Sandbox segnala i tipi sconosciuti). |
| `name` | `string` | `id` | Nome leggibile (solo nell’interfaccia dell’editor). |
| `title` | `string` | `''` | Testo predefinito del titolo; vuoto significa nessun titolo. L’attributo `title` del recinto lo sostituisce caso per caso. |
| `span` | `'column' \| 'page' \| 'side'` | `'column'` | Estensione orizzontale: la colonna, l’intera larghezza del contenuto, o la colonna laterale riservata agli elementi flottanti di un’impaginazione a colonna e mezza (`layout.sideColumnRole: 'floats'`); in quest’ultimo caso il riquadro esce dal flusso e si impila in quella colonna accanto al testo che interrompe. Si può sostituire caso per caso con l’attributo `span`. Nelle impaginazioni a più colonne un riquadro `'page'` diventa un *blocco a tutta larghezza*: divide la pagina in fasce di colonne e sta in una propria colonna a tutta larghezza (vedi più avanti la sezione sul contenitore). Un riquadro laterale che la colonna laterale della sua pagina non può contenere prende la colonna laterale della pagina successiva; dove il capitolo (o il documento) finisce prima, ogni riquadro ancora in attesa si compone nella colonna laterale di una pagina dopo il testo, nell’ordine dei suoi recinti, e la build lo segnala (`afterText`; fino a postext 1.24 i riquadri dopo la prima pagina del genere venivano scartati). |
| `columns` | `number` | `1` | Quante colonne adiacenti occupa un riquadro flottante (`placement` `'auto'`, `'top'` o `'bottom'`, con `span: 'column'`), come fa `placement.columns` per una figura: il riquadro di un articolo su tre delle cinque colonne di un giornale. Tante colonne quante ne ha la pagina, o di più, ne fanno un riquadro a tutta larghezza. Un riquadro composto nel flusso (`'here'`) resta nella sua colonna. Si può sostituire caso per caso con l’attributo `columns`. Da postext 1.18. |
| `placement` | `'here' \| 'auto' \| 'top' \| 'bottom' \| 'fixed'` | `'here'` | Dove va il riquadro. `'here'` lo compone in linea nel flusso; `'top'` / `'bottom'` lo **fanno flottare** come una risorsa (`'auto'` prende la prima fascia libera, di testa o di piede): esce dal flusso nel punto in cui compare e prende la prima fascia libera in quel punto o dopo (il piede della pagina corrente, o la testa / il piede della pagina successiva che il flusso apre), e il testo che lo segue riempie la pagina attorno a esso; `'fixed'` lo ancora a coordinate della pagina tramite `fixed` qui sotto, fuori dal flusso delle colonne. Vedi la sezione sul contenitore per i dettagli. Si può sostituire caso per caso con l’attributo `placement`. |
| `sideAtColumnEnd` | `'before' \| 'after'` | `'before'` | Dove sta un riquadro laterale (`span: 'side'`) quando il testo dopo il suo recinto non prosegue nella stessa colonna: la colonna non ha più spazio per esso, oppure le regole di interruzione lo mandano avanti (un paragrafo che le regole su vedove e orfane spostano intero, un titolo tenuto con il suo testo). `'before'` lo tiene al suo recinto, in quella pagina, accanto al testo che lo precede, risalendo dal piede della colonna quando non ci sta sotto il recinto: il posto per una glossa scritta dopo il passo che spiega. `'after'` lo allinea alla prima riga del testo dopo il recinto, nella colonna laterale della pagina in cui quel testo prosegue: il posto per un numero di riga o un titolo marginale scritto prima della sua riga. Quando il testo prosegue nella stessa colonna, entrambi compongono il riquadro al suo recinto. Un riquadro che nel suo capitolo non è seguito da nulla resta comunque con il testo che lo precede, e i riquadri laterali con recinti consecutivi mantengono il loro ordine. Fino a postext 1.4 ogni riquadro laterale si comportava come `'before'`, che resta il valore predefinito: uno stile per le glosse tiene i suoi riquadri nella pagina del passo che spiegano. |
| `fixed` | `{ anchor?, offset? }` | `{ anchor: { to: 'container', edge: 'bottom-left' } }` | Posizione di un riquadro `'fixed'`: un `ElementAnchor` (`to`: `'container'` = l’area del contenuto della pagina, specchiata sulle pagine pari; `'page'` = il formato rifilato; `'bleed'` = l’area con l’abbondanza; `edge`: uno dei nove bordi del contenitore) più un `offset` facoltativo (dimensioni `x` / `y`). |
| `floatBarrier` | `boolean` | `false` | Fa del riquadro una barriera per gli elementi flottanti: ogni figura o tabella richiamata prima di esso viene collocata prima di esso (negli spazi liberi della pagina, altrimenti in pagine aperte prima del riquadro), così nessun elemento flottante scavalca il riquadro di chiusura di un capitolo (tipicamente un riepilogo dei «punti chiave»). Le aperture di capitolo, `:::part` e la fine del documento sono sempre barriere. |
| Un riquadro `span: 'page'` su una pagina a più colonne taglia la fascia sotto il testo che segue; una figura a tutta larghezza richiamata prima di esso prende per prima quel taglio: il testo viene livellato, la figura si colloca proprio dove esso è finito, e il riquadro prosegue sotto di essa (o alla pagina successiva quando non ci sta più). Una figura troppo alta per seguire il testo livellato apre invece la pagina successiva, con il riquadro dopo di essa, e la fascia che ha lasciato termina comunque livellata. Un riquadro divisibile (`keepTogether: false`) si apre sotto il testo e la figura con tutti gli elementi che ci stanno, e il resto prosegue nella pagina successiva. |  |  |  |
| `width` | `'fill' \| 'auto'` | `'fill'` | `'fill'` occupa la larghezza disponibile; `'auto'` si adatta al titolo (uso come etichetta) e ignora i figli. |
| `backgroundEnabled` / `background` | `boolean` / `ColorValue` | `true` / `#f4f4f4` | Riempimento del riquadro. |
| `border` | `{ enabled, color, width }` | `false`, `#cccccc`, `0.5pt` | Contorno del riquadro, tracciato all’interno del bordo del riquadro come il bordo di un elemento riquadro (vedi [Elementi riquadro](https://postext.dev/it/docs/configuration-headers-footers.md#elementi-riquadro)). |
| `borderRadius` | `Dimension` | `0` | Raggio degli angoli dello sfondo / del bordo (limitato a metà della larghezza e dell’altezza del riquadro). La fascia lo segue: su un riquadro arrotondato la fascia è ritagliata dalla cornice arrotondata, come CSS ritaglia un `border-left` con `border-radius`. La linguetta `label` mantiene gli angoli vivi. |
| `padding` | `{ top, right, bottom, left }` | `0.75em` ciascuno | Distanza tra il bordo del riquadro e il suo contenuto. I valori in `em` sono relativi al corpo del testo del riquadro. |
| `stripe` | `{ enabled, side, width, color }` | `false`, `'left'`, `1.5em`, colore principale | Fascia piena lungo un bordo. Una fascia `'left'` / `'right'` restringe il contenuto; una fascia `'top'` lo spinge in basso. `'left'` e `'right'` sono lati del flusso del testo (in un libro da destra a sinistra `'left'` è la destra del foglio); `'start'` e `'end'` seguono la direzione propria del riquadro, quindi un `:::callout{dir=ltr}` in un libro arabo mette a sinistra una fascia `'start'`. Su un riquadro con `borderRadius` i suoi angoli esterni si arrotondano come quelli della cornice (fino a postext 1.4 restavano vivi e sporgevano oltre l’arrotondamento). |
| `icon` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, width, color, align, position, cornerSide }` | `'none'`, font dei titoli, `400`, `1.5em`, colore principale, `'top'`, `'inline'`, `'right'` | Un glifo di testo (`kind: 'glyph'`) o una risorsa bitmap / SVG (`kind: 'resource'` + `resourceId`) accanto al contenuto. Con una fascia laterale l’icona si centra sulla fascia; altrimenti riserva una propria colonna (`size` + `titleStyle.gap`). `align: 'center'` la centra verticalmente sul contenuto. Un’immagine di risorsa si adatta al quadrato mantenendo le proporzioni, oppure a un riquadro `width` × `size` quando è impostato `width` (una larga striscia di icone); un’icona più alta del contenuto fa crescere il riquadro per contenerla (e, con `align: 'center'`, centra il contenuto su di essa). `position: 'corner'` appende l’icona a un angolo superiore come un’etichetta, per metà oltre il bordo, senza togliere spazio al contenuto; un’icona larga (`width`) si centra sull’angolo in base alla larghezza a cui è disegnata, e sull’angolo sinistro il titolo inizia oltre la sua metà interna (fino a postext 1.4 si collocava in base all’altezza, quindi una striscia larga sporgeva dal riquadro e sopra il titolo); `cornerSide` sceglie l’angolo: `'right'` / `'left'`, oppure `'outer'` / `'inner'`, che seguono la parità della pagina dei margini speculari (esterno = destra su un recto, sinistra su un verso). |
| `marker` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, color, align, gap, rule }` | `'none'`, font dei titoli, `400`, `1.5em`, colore principale, `'center'`, `0.5em`, filetto disattivato (`0.5pt`, colore principale, lunghezza `0`) | Una seconda icona disegnata *fuori* dal riquadro, in una colonna alla sua sinistra, con un `rule` verticale facoltativo tra essa e il riquadro: la mano «tocca qui» accanto a un’etichetta di autovalutazione. La cornice diventa `[marker][rule][gap][box]` e alta quanto il più alto dei tre; `align` li centra l’uno sull’altro o li allinea in alto. `rule.length` è un minimo: il filetto copre sempre almeno l’altezza del riquadro. |
| `titleStyle` | `{ fontFamily, fontSize, fontWeight, italic, color, textTransform, gap, letterSpacing, indent, lineHeight }` | font dei titoli, corpo del testo corrente, `700`, `false`, colore principale, `'none'`, `0.5em`, `0`, `0`, `1.2em` | Tipografia del titolo. `gap` è lo spazio tra il titolo e il primo figlio (e lo spazio della colonna dell’icona). `lineHeight` è l’interlinea delle righe del titolo, con `em` riferito alla dimensione propria del titolo; la linea di base sta a 0,8 di essa dall’alto di ogni riga, come nel testo corrente, quindi un titolo sull’interlinea del testo corrente (`lineHeight: 12pt` su una griglia di 12 pt) mantiene un riquadro di un numero intero di righe e il suo titolo sulla griglia, mentre l’1,2 em predefinito aggiunge una frazione di riga a ogni riquadro. `textTransform: 'uppercase'` conserva la lunghezza. `letterSpacing` applica la spaziatura tra lettere al titolo (`letterSpacing` del canvas / `Tc` del PDF); `indent` lo sposta a destra del bordo interno del riquadro. Un’etichetta d’angolo appesa sul lato del titolo (l’angolo sinistro) riserva prima il proprio spazio (la metà interna dell’etichetta più `gap`), così il titolo la evita su qualunque pagina capiti; `indent` aggiunge soltanto oltre quello. |
| `body` | `{ fontFamily, fontSize, lineHeight, color, boldColor, italicColor, fontWeight, boldFontWeight, italic, smallCaps, textAlign, hyphenation, paragraphSpacing, firstLineIndent, tabStops, tabInterval }` | eredita da `bodyText`; `italic` / `smallCaps` `false` | Tipografia dei paragrafi e degli elementi di elenco dentro il riquadro. Ogni campo non impostato eredita dal testo corrente; `italicColor` imposta il colore dei tratti in corsivo (una citazione in evidenza in corsivo nel colore del riquadro). `fontWeight` / `boldFontWeight` impostano i pesi dei tratti normali e in grassetto; `italic` compone il riquadro in corsivo, con i tratti `*…*` che passano in tondo; `smallCaps` lo compone in maiuscoletto; `tabStops` e `tabInterval` sostituiscono quelli del testo corrente dentro il riquadro (vedi [Stop di tabulazione](https://postext.dev/it/docs/configuration-text.md#punti-di-tabulazione)). Vedi [Tipografia dentro un riquadro](https://postext.dev/it/docs/configuration-callouts.md#tipografia-dentro-un-riquadro) per che cos’altro prende il testo del riquadro. |
| `lists` | `{ bulletChar, color, indent, gap, itemSpacing, bulletFontSize, bulletFontWeight }` | eredita da `unorderedLists` | Tipografia degli elenchi dentro il riquadro (`color`, `indent`, `gap` e `itemSpacing` si applicano anche agli elenchi ordinati). `bulletFontSize` / `bulletFontWeight` compongono il glifo del punto elenco nel carattere del testo del riquadro con quella dimensione e quel peso (un punto elenco pesante e colorato). |
| `label` | `{ fontFamily, fontSize, fontWeight, color, background, position, height, paddingX, offset, inset, icon, rule }` | non impostato (nessuna linguetta) | Una linguetta sul bordo superiore del riquadro che stampa l’attributo `label` del recinto: il numero di un riquadro numerato («BOX 1-1»). Aderisce all’angolo `position` (`'top-right'` / `'top-left'`), rientrata di `inset`, sporge di `offset` sopra la sommità del riquadro (quello spazio fa parte del blocco, in aggiunta a `marginTop`, così la linguetta lo conserva anche in testa a una colonna), è alta `height` con `paddingX` su ogni lato del testo, e può portare accanto una risorsa `icon` (`{ resourceId, width, gap }`, sul lato opposto all’angolo) e un `rule` (`{ enabled, color, width }`) lungo il bordo superiore dall’angolo opposto fino a essa. Valori predefiniti: font dei titoli, corpo del testo corrente, `700`, bianco sul colore principale, alta `1.4em`, spaziatura interna `0.6em`. La linguetta è una forma a sé appoggiata sulla cornice, quindi mantiene gli angoli vivi qualunque sia il `borderRadius` del riquadro. |
| `columnGap` | `Dimension` | `1.5em` | Spazio tra le colonne di un gruppo `:::columns` dentro il riquadro (vedi più avanti la sezione sul contenitore). |
| `marginTop` / `marginBottom` | `Dimension` | `0.75em` / `0.75em` | Spazio sopra il riquadro (si fonde con il margine del blocco precedente) e spazio minimo sotto di esso (lo spazio esatto con `snapToGrid: false`). Un riquadro flottante (`placement: 'top'`, `'bottom'` o `'auto'`) mantiene lo spazio degli elementi flottanti, una riga di testo, tra la sua fascia e il testo; un `marginBottom` più ampio imposta lo spazio sotto un riquadro in una fascia di testa, e un `marginTop` più ampio lo spazio sopra un riquadro in una fascia di piede, arrotondato alla griglia insieme alla fascia. Fino a postext 1.4 un riquadro flottante ignorava i suoi margini. |
| `snapToGrid` | `boolean` | `true` | Con `true` il flusso dopo il riquadro torna ad agganciarsi alla griglia della linea di base, quindi lo spazio sotto di esso è `marginBottom` arrotondato a righe intere della griglia. Con `false` il riquadro mantiene il suo `marginBottom` esatto, che si fonde con il margine superiore del blocco successivo (due riquadri consecutivi di uno stile del genere stanno esattamente a `max(marginBottom, marginTop)` di distanza), e il testo che lo segue può stare fuori griglia fino al punto di aggancio successivo (un titolo, la fine di un elenco), come dopo un titolo con `headings.snapToGrid: false`. Pensato per documenti fatti di riquadri impilati (schede di esercizi, moduli). Si applica ai riquadri nel flusso; i riquadri a tutta larghezza in un’impaginazione a più colonne, i riquadri flottanti, fissi e laterali mantengono la griglia, perché le fasce di colonne e le zone degli elementi flottanti sono impaginate su di essa. Le leve del bilanciamento delle colonne non cambiano: un riquadro che chiude una colonna viene comunque spinto fino all’ultimo slot della griglia della colonna. |
| `keepTogether` | `boolean` | `true` | Con `true` il riquadro resta intero: un riquadro che non sta nello spazio rimanente passa intero alla colonna o alla pagina successiva. Solo un riquadro più alto di una colonna vuota e completa (un’intera pagina per un riquadro `span: 'page'`) non può restare intero: si divide secondo le regole di `false` descritte sotto invece di eccedere, a partire dal punto in cui compare, e una continuazione che sta in una colonna passa poi avanti intera; un riquadro flottante (`placement: 'top' \| 'bottom' \| 'auto'`) così alto non flotta ma resta nel flusso dove compare. Con `false` qualsiasi riquadro può dividersi tra i suoi blocchi figli o tra le righe di un paragrafo o di un elemento di elenco: il taglio più profondo che ci sta chiude la colonna corrente (o, per un riquadro `span: 'page'`, la pagina, a filo del fondo delle colonne) e il resto prosegue in cima alla successiva in un riquadro proprio (stessa cornice e stessa fascia, nessuna icona, e nessun titolo a meno che `repeatTitle` non lo ripeta), dividendosi di nuovo se è ancora troppo alto. Il testo di ogni frammento conserva, vuota, la colonna che un’icona in linea occupa nella parte iniziale, così il riquadro ha una sola giustezza su ogni pagina. Un taglio dentro un elemento di elenco lascia il suo punto elenco con la parte iniziale. La cornice di ogni frammento condivide `contentIndex` / `containerId` del recinto e registra `callout.part` / `callout.continued`. Usalo su un lungo riquadro di chiusura con i «punti chiave» insieme a `headings.balancing.beforeSpan`, o su uno stile di nota i cui riquadri non devono mai spingere una figura fuori dalla pagina. Un riquadro annidato (un `:::callout` dentro un altro) è un figlio del suo genitore: un taglio può cadere prima o dopo di esso, e al suo interno solo quando il suo stile consente la divisione (`keepTogether: false`, o più alto di una colonna intera), secondo il suo `splitMinLines`. |
| `splitMinLines` | `number` | `2` | Numero minimo di righe di testo che un frammento di un riquadro diviso (`keepTogether: false`, o un riquadro da tenere unito più alto di una colonna intera) conserva su ciascun lato del taglio. Protegge solo il testo: un lato che contiene almeno una figura, una tabella, una formula in evidenza o un riquadro annidato è accettabile qualunque sia il suo numero di righe, quindi un riquadro di immagini può lasciarne una sola su una pagina. Un taglio dentro un paragrafo o un elemento di elenco conta comunque tutte le righe di ciascun lato (una figura o una formula lì come una riga), e lascia anche almeno `layout.boxChildSplitMinLines` righe di quel paragrafo o elemento su ciascun lato (due per impostazione predefinita; questo minimo quando è inferiore, quindi 1 consente una riga). Con i valori predefiniti un elemento di due o tre righe non si divide mai e uno di quattro si divide solo due e due. Con il valore predefinito nessun riquadro si divide lasciando una riga di testo isolata al piede di una colonna o in testa alla successiva; quando nessun taglio soddisfa il minimo il riquadro passa avanti intero. (Prima di postext 1.5 un taglio dentro un paragrafo controllava solo le righe dell’intero lato, quindi un elemento di due righe poteva dividersi una e una quando altre righe del riquadro raggiungevano il minimo.) |
| `repeatTitle` | `boolean` | `false` | Ripete il titolo in testa a ogni continuazione di un riquadro diviso, seguito da `continuedSuffix` («Punti chiave (segue)»). La ripetizione prende lo stile del titolo. Un riquadro senza titolo non ripete nulla. Vedi [Segni su un riquadro diviso](https://postext.dev/it/docs/configuration-callouts.md#segni-su-un-riquadro-diviso). |
| `continuedSuffix` | `string` | `'(cont.)'` | Testo dopo il titolo ripetuto, nella lingua del documento (`locale`, altrimenti la lingua di sillabazione), come quello di una tabella divisa, e unito al titolo come lo è quello di una tabella. |
| `continuesMarkerEnabled` | `boolean` | `false` | Colloca `continuesMarker` sotto l’ultima riga di ogni parte di un riquadro diviso che prosegue, all’interno del riquadro. |
| `continuesMarker` | `string` | `'Continued'` / `'Continúa'` | Testo di quel segno (il «(MORE)» di una sceneggiatura), nel carattere e nel corpo del testo del riquadro, secondo la lingua del documento. |
| `continuesMarkerAlign` | `'left' \| 'center' \| 'right'` | `'right'` | Dove sta il segno nella larghezza interna del riquadro. |
| `continuesMarkerItalic` | `boolean` | `true` | Compone il segno in corsivo. |
| `numbering` | `{ label, counter, numberingTemplate, resetOn, counterFormat, placement, bold, italic, suffix }` | non impostato | Conta i riquadri di questo stile come enunciati numerati: teoremi, lemmi, definizioni. Vedi [Enunciati numerati e dimostrazioni](https://postext.dev/it/docs/configuration-callouts.md#enunciati-numerati-e-dimostrazioni). |
| `endMark` | `string` | `''` | Un segno allineato a destra alla fine dell’ultima riga del riquadro, come una dimostrazione termina con `'∎'` o `'□'`: sull’ultima riga quando ci sta dopo uno spazio, altrimenti su una riga propria. Un riquadro che termina con una formula in evidenza senza numero lo prende come etichetta della formula. Con le formule attive, i quadrati (∎ □ ■ ▪ ◻ ▫) si disegnano dai glifi propri di TeX, quindi un carattere che non li ha (i file latini di Fontsource) li stampa comunque; con le formule disattivate si compongono nel carattere del testo del riquadro. |

### Il contenitore `:::callout`

Una riga `:::callout{type="<id>"}` apre il riquadro e una riga `:::` da sola lo chiude. Il recinto accetta cinque attributi, `type` (l’id dello stile), `title` (sostituisce il titolo dello stile), `span`, `placement` e `columns` (sostituiscono i valori dello stile), e il contenuto tra le due righe si impagina dentro il riquadro: un titolo facoltativo, poi i paragrafi, gli elenchi, le citazioni in blocco, le formule o le risorse incorporate, ciascuno composto con la tipografia `body` / `lists` dello stile (i titoli mantengono i loro stili consueti). I margini tra i figli si fondono come nel testo corrente; l’interno esce dalla griglia della linea di base, e il flusso vi si riaggancia dopo il riquadro con almeno `marginBottom` sotto (vince la griglia; il margine è un minimo, la stessa convenzione seguita dalle risorse). Uno stile con `snapToGrid: false` mantiene invece il `marginBottom` esatto, e il testo dopo il riquadro resta fuori griglia fino al titolo successivo o alla fine di un elenco. Un titolo subito prima di un riquadro resta unito a esso.

Limiti di questa versione:

- Un riquadro resta intero a meno che il suo stile non imposti `keepTogether: false`. Quando non sta nello spazio rimanente della colonna passa intero alla colonna o alla pagina successiva, anche uscendo da una colonna vuota che fasce di elementi flottanti o un limite di fascia hanno accorciato, purché una colonna intera possa contenerlo. Un riquadro più alto di una colonna intera si divide invece, come uno divisibile; solo uno che nessun taglio può dividere (una figura o una tabella più alta della colonna, o uno `splitMinLines` che nessun taglio soddisfa) viene collocato comunque ed eccede; l’impaginazione registra allora un avviso `calloutOverflow` (`VDTDocument.warnings`), che la Sandbox elenca. Un gruppo `:::columns` si taglia come il riquadro che lo contiene, tra le sue sottocolonne (da postext 1.25); resta intero, e può eccedere allo stesso modo, solo con `layout.flowColumns: false` o dentro un riquadro annidato. Un riquadro divisibile lascia indietro la parte che ci sta (figli interi, o le righe di un paragrafo fino a `splitMinLines` su ciascun lato; una figura, una tabella o una formula in evidenza da sola basta per un lato) e prosegue in un riquadro senza icona nella colonna o pagina successiva, senza il titolo a meno che lo stile non lo ripeta, e facoltativamente con un segno sotto la parte che lascia (vedi [Segni su un riquadro diviso](https://postext.dev/it/docs/configuration-callouts.md#segni-su-un-riquadro-diviso)).
- Gli elementi flottanti cedono il passo a un riquadro indivisibile. Quando il blocco subito dopo il richiamo di una figura è un riquadro `keepTogether`, uno slot che non lascerebbe al riquadro alcuna colonna della fascia corrente in cui finire (la colonna del richiamo o una vuota dopo di essa, che lo conteneva prima dell’elemento flottante) non viene preso: la figura passa al suo slot successivo, di solito la pagina successiva, e il riquadro resta nel flusso, come lo comporrebbe un compositore, invece di spingere il riquadro fuori dalla pagina lasciando la colonna con la sola figura.
- `span: 'page'` in un’impaginazione a più colonne fa del riquadro un **blocco a tutta larghezza**: si impagina all’intera larghezza del contenuto e divide la pagina in fasce di colonne; le colonne di testo sopra di esso si chiudono alla linea di taglio, il riquadro prende una propria colonna a tutta larghezza, e sotto di esso si apre una nuova fascia di colonne di testo, così il flusso prosegue sotto il riquadro in ogni colonna. Dove le colonne sono *livellate* (in cima a una pagina, subito sotto un titolo di apertura `span: 'page'`, subito sotto un altro blocco a tutta larghezza, o subito sotto una fascia di elementi flottanti in testa) il riquadro taglia semplicemente lì. Quando arriva a metà pagina, con le colonne disuguali, si compone come farebbe un compositore: il testo sopra di esso viene tagliato alla stessa altezza in tutte le colonne (il motore ripete il posizionamento con le colonne della fascia accorciate allo stesso numero di righe della griglia, così il testo trabocca naturalmente da una colonna all’altra e tutte le regole su orfane, vedove e tieni con il successivo continuano ad applicarsi), il riquadro occupa tutta la larghezza della pagina, e le colonne riprendono sotto di esso. Il taglio richiede un paio di passaggi di posizionamento in più; quando la linea di taglio non lascerebbe spazio per il riquadro più il minimo di righe di testo per le vedove sotto di esso, o nessuna disposizione funziona dopo alcuni tentativi, il riquadro passa in cima alla pagina successiva. Il testo sopra rispetta il taglio: un paragrafo che non può iniziare nelle poche righe che una colonna sotto una figura conserva sopra di esso passa alla colonna successiva (la figura resta allora sola nella sua colonna), e quando un blocco supererebbe comunque il taglio, il taglio si prende una riga più in basso invece che dove termina quel blocco. Anche un riquadro diviso che apre la fascia viene tagliato lì, così il suo resto non supera mai il taglio. Con `headings.balancing.beforeSpan` (il valore predefinito) la fascia che lascia viene tagliata livellata dietro di esso, come la fascia di chiusura di un capitolo, e, quando lo stile consente la divisione (`keepTogether: false`), la parte del riquadro che sta sotto le colonne livellate chiude la pagina e il resto apre la successiva; con `beforeSpan: false` la pagina che lascia viene semplicemente bilanciata come al solito, senza forzare un’interruzione di pagina. Un titolo subito prima di un blocco a tutta larghezza non viaggia con esso. Nelle impaginazioni a una colonna `span: 'page'` è semplicemente in linea.
- `placement: 'fixed'` toglie il riquadro dal flusso: viene impaginato (`width: 'auto'` si adatta al titolo; `'fill'` prende la larghezza della colonna di testo sotto il punto di ancoraggio) e fissato alla pagina in cui compare nel flusso, nella posizione descritta da `fixed.anchor` / `fixed.offset` (per impostazione predefinita l’angolo inferiore sinistro dell’area del contenuto). Le colonne di testo che copre cedono quella zona (tagliate dal basso, o dall’alto quando la colonna è ancora vuota), esattamente come una fascia di elementi flottanti; quando la zona contiene già testo, un elemento flottante o un blocco a tutta larghezza, il riquadro passa alla pagina successiva. Un riquadro fisso che chiude il capitolo (il blocco successivo è un’apertura di capitolo, un `:::part`, un riquadro barriera o la fine del documento) livella prima le colonne sopra di esso (`headings.balancing.trailing`), così una breve pagina di chiusura termina livellata con l’etichetta sottostante. La cornice e i figli vivono in `page.floats` e si disegnano fuori dal ritaglio delle colonne in ogni backend.
- `placement: 'top' | 'bottom'` **fa flottare** il riquadro come una risorsa: esce dal flusso nel punto in cui compare e prende la prima fascia libera dopo quel punto (il piede della pagina corrente, con `'bottom'`, o la testa / il piede della pagina successiva che il flusso apre) alla larghezza della colonna (`span: 'column'`) o all’intera larghezza del contenuto (`span: 'page'`); il testo che lo segue riempie la pagina che ha lasciato. La sua cornice e i suoi figli vanno in `page.floats`, come per un riquadro fisso. Un riquadro flottante in testa a una pagina nuova si colloca prima delle figure in attesa di quella pagina, e una figura citata in una pagina precedente che ci sta poi sotto di esso prende il resto di quella pagina anche quando resterebbero meno di tre righe di testo (una pagina da galleria: riquadro più figura, senza testo in mezzo). Un riquadro `span: 'side'` non flotta mai: si impila accanto al testo qualunque sia il suo posizionamento. Con `columns` superiore a 1 (nello stile o come attributo del recinto, da postext 1.18) un riquadro `span: 'column'` occupa altrettante colonne adiacenti: la testa di una serie di colonne vuote che iniziano alla stessa altezza, o il piede della colonna corrente e di quelle vuote che la seguono, come in `:::callout{placement="top" columns="2"}`.
- `width: 'auto'` si adatta solo al titolo; i figli vengono ignorati.
- Un `:::callout` annidato dentro un altro riquadro è un riquadro a sé: si impagina con il proprio stile (sfondo, bordo, raggio, spaziatura interna, fascia, titolo, icona, segno, linguetta, tipografia) all’intera larghezza interna del genitore e si impila come uno dei suoi figli, con `marginTop` / `marginBottom` che si fondono con quelli dei vicini. I suoi `span` e `placement` (del recinto o dello stile) vengono ignorati, perché un riquadro annidato scorre sempre dentro il genitore, e così `floatBarrier` e `snapToGrid`. I riquadri si annidano a qualsiasi profondità e possono stare dentro un gruppo `:::columns` (ciascuno intero, in una colonna). Quando il genitore si divide, il taglio cade prima o dopo un riquadro annidato, o al suo interno quando lo stile annidato consente la divisione; ogni frammento ridisegna le cornici che attraversa, e un riquadro annidato che continua dal frammento precedente perde il titolo e l’icona, come una continuazione di primo livello.
- Un gruppo `:::columns{count=N}` … `:::` tra i figli impagina quei figli in `N` colonne di uguale larghezza, a distanza `columnGap`, dentro il riquadro: la sequenza si taglia ai confini di blocco o di riga che livellano meglio le colonne (un paragrafo o un elemento di elenco tagliato a metà prosegue in testa alla colonna successiva senza il suo punto elenco), ogni colonna inizia alla sommità del gruppo e il gruppo è alto quanto la sua colonna più alta; i figli successivi tornano all’intera larghezza. Un riquadro che si divide (`keepTogether: false`, o più alto di una colonna) taglia anche dentro un gruppo, tra le sue colonne: un gruppo a serpentina riempie a turno le sue colonne e prosegue nel frammento successivo, uno parallelo (`breaks`) prosegue flusso per flusso (da postext 1.25; vedi [Formato del documento › `:::columns`](https://postext.dev/it/docs/document-format-directives.md#columns)). Un `gap` sul recinto sostituisce `columnGap` per quel gruppo, e `rule` traccia un filetto lungo ogni intercolonna. Usalo per un riepilogo dei punti chiave su due colonne, o per affiancare le tabelle di un riquadro largo.
- Il sesto attributo del recinto, `label`, si stampa sulla linguetta dello stile (vedi `label` sopra): `:::callout{type="box" label="BOX 1-1" title="The octet rule"}`; senza uno stile `label` l’attributo viene ignorato.

Nel VDT il riquadro è un blocco cornice `type: 'callout'` la cui decorazione (sfondo, fascia, icona, titolo) vive in `designOverlay`, seguito dai suoi blocchi figli nella stessa colonna; la cornice e ogni figlio portano il `containerId` del recinto. Un riquadro annidato è una cornice `type: 'callout'` a sé tra i figli, seguita dai suoi blocchi; questi mantengono il `containerId` del recinto di primo livello (il posizionamento e il bilanciamento continuano a vedere un’unica unità) e aggiungono `calloutPath`, gli id dei contenitori dei recinti annidati che li circondano, dal più esterno (l’id proprio di una cornice annidata è l’ultima voce). Il PDF con tag dà a ogni riquadro annidato un `Div` dentro quello del genitore. Le immagini delle icone si risolvono come le immagini delle risorse: il registro delle immagini del canvas, l’opzione HTML `resourceImageUrl` e il provider PDF `resourceBytes`.

```ts
const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings

const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped
```

### Enunciati numerati e dimostrazioni

Uno stile con `numbering` conta i suoi riquadri, come `amsthm` di LaTeX conta gli ambienti teorema (da postext 1.19). Ogni riquadro stampa la sua etichetta e il suo numero («**Theorem 2.**» in apertura del suo primo paragrafo) e il `title` del recinto segue il numero tra parentesi: `:::callout{type="theorem" title="Bradley–Terry"}` si apre con «**Theorem 2** (Bradley–Terry)**.**». Un riquadro aperto con un identificatore (`{#thm:main}`) è una destinazione dei rimandi, che stampano «Theorem 2» (`:ref{id="thm:main"}`), e `\ref{thm:main}` o `style=number` stampa 2.

| Campo | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `label` | `string` | — | La parola prima del numero: `'Theorem'`, `'Lemma'`, `'Definición'`. |
| `counter` | `string \| false` | l’`id` dello stile | Il contatore che i riquadri fanno avanzare. Gli stili che indicano uno stesso contatore lo condividono, come fa `\newtheorem{lemma}[theorem]`: Theorem 1, Lemma 2, Theorem 3. `'equation'` conta insieme alle equazioni etichettate. `false` stampa l’etichetta senza numero (il «*Proof.*» di una dimostrazione). |
| `numberingTemplate` / `resetOn` / `counterFormat` | `string` / `ResourceCounterReset` / `ResourceCounterFormat` | `'{n}'` / `'never'` / `'decimal'` | Come quello di un tipo di risorsa: `'{h1}.{n}'` con `resetOn: 'h1'` numera Theorem 2.1, 2.2… per capitolo; `'{h1}.{h2}.{n}'` con `'h2'` per sezione. Un contatore condiviso da più stili conta su ciò che stampano i loro modelli. Un token prende uno stile dopo i due punti, come quello di un tipo di risorsa: `'{h1:A}.{n}'` stampa *Theorem A.1* in un’appendice indicata da una lettera. |
| `placement` | `'runIn' \| 'title'` | `'runIn'` | `'runIn'` apre il primo paragrafo del riquadro con l’etichetta (un riquadro che si apre con un elenco, una formula o un altro riquadro riceve un paragrafo apposito); `'title'` fa dell’etichetta il titolo del riquadro, nel suo `titleStyle`: «Theorem 2 (Bradley–Terry)». |
| `bold` / `italic` | `boolean` | `true` / `false` | Il carattere dell’etichetta in linea e del suo suffisso, qualunque sia il testo del riquadro: un testo in corsivo (`body.italic`) mantiene in tondo un’etichetta in tondo. Il titolo tra parentesi si compone in tondo e nel peso normale. |
| `suffix` | `string` | `'.'` | Collocato dopo l’etichetta in linea e il suo titolo. |

Una dimostrazione è uno stile con un’etichetta non numerata e un segno finale:

```ts
calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]
```

In un libro impaginato capitolo per capitolo i contatori proseguono dal capitolo precedente (`LayoutContinuation.statementCounters`, che `continuationAfter` compila), e la struttura del libro assegna all’ancora di ogni riquadro numerato la sua etichetta (`OutlineEntry.numberLabel`), così un rimando da un altro capitolo la stampa.

### Tipografia dentro un riquadro

Un riquadro compone il suo contenuto con la propria tipografia `body` e `lists`; tutto il resto mantiene gli stili del documento:

- **I paragrafi** prendono il `body` del riquadro: carattere, dimensione, interlinea, colore, colori dell’enfasi, pesi, `italic`, `smallCaps`, allineamento, sillabazione, rientro e spaziatura tra paragrafi. Un campo non impostato eredita da `bodyText`. Un colore dell’enfasi ereditato mantiene il suo collegamento alla tavolozza, quindi grassetto, corsivo ed etichette `:ref` in un riquadro cambiano con `colorPalette` come fanno fuori da esso. (Fino a postext 1.4 il grassetto in un riquadro restava `#295AA3` qualunque fosse il colore principale.)
- **Gli elenchi puntati** prendono il `lists` del riquadro (carattere del punto elenco, colore, dimensione e peso del glifo, rientro, spazio, spaziatura tra gli elementi) al posto di `unorderedLists`, e il loro testo è il testo del riquadro. Un `lists.bulletChar` o `lists.color` diverso da quello del documento (`unorderedLists`) sostituisce il punto elenco o il colore di ogni livello; uno che lo ripete, o che resta non impostato, lascia a ogni livello il proprio (`unorderedLists.levels`), così i trattini annidati sopravvivono nel riquadro.
- **Gli elenchi ordinati** prendono `lists.indent`, `gap` e `itemSpacing`, e `lists.color` ogni volta che lo stile lo imposta, anche quando è il colore del punto elenco del documento; uno stile che lo lascia non impostato mantiene i numeri in `orderedLists.color`. (Fino a postext 1.4 il colore arrivava ai numeri solo quando era diverso da `unorderedLists.color`, quindi impostarlo proprio su quel colore non faceva nulla.) Il numero stesso (il suo carattere, la sua dimensione e il suo separatore) viene dall’`orderedLists` globale, perché `lists` ha solo campi per i punti elenco: definisci lì lo stile dei numeri di un riquadro.
- **I `:::paragraphs` dentro un riquadro** usano il loro stile di paragrafo, anche nei riquadri annidati. I campi che lo stile lascia non impostati ereditano dal `bodyText` del documento, non dal `body` del riquadro (né dal suo corsivo o dal suo maiuscoletto).
- **I gruppi `:::columns`** non hanno uno stile proprio: ogni colonna condivide la tipografia del testo e degli elenchi del riquadro, e `columnGap` imposta lo spazio tra di esse.
- **Le citazioni in blocco** prendono il carattere, la dimensione e i pesi del testo del riquadro (corsivo e grigio, come nel testo corrente), e il suo maiuscoletto. **I titoli** mantengono gli stili dei titoli; **le formule in evidenza** le impostazioni delle formule.
- **Le figure e le tabelle** mantengono gli stili delle didascalie e delle tabelle del documento, alla larghezza interna del riquadro; i loro pesi normale e grassetto seguono i pesi del `body` del riquadro.
- **I chip** mantengono il loro stile di chip; una dimensione in `em` si legge rispetto al corpo del testo del riquadro.
- **`:::space`** si misura in righe del testo del riquadro (vedi [`:::space`](https://postext.dev/it/docs/document-format-directives.md#space) per i casi in cui viene scartato).
- **Un riquadro annidato** prende per intero il proprio stile; i suoi `span`, `placement`, `floatBarrier` e `snapToGrid` vengono ignorati.

### Segni su un riquadro diviso

Quando un riquadro si divide tra colonne o pagine (`keepTogether: false`, o un riquadro più alto di una colonna), ogni parte dopo la prima si apre senza il titolo e l’icona, e per impostazione predefinita nulla dice al lettore che il riquadro prosegue. Due opzioni aggiungono i segni che usano un libro o una sceneggiatura:

- **`repeatTitle: true`** ripete il titolo in testa a ogni continuazione, seguito da `continuedSuffix`, per impostazione predefinita «Key points (cont.)». La ripetizione prende lo stile del titolo, quindi con `textTransform: 'uppercase'` dà il «HAMLET (CONT'D)» di una sceneggiatura. L’icona e la linguetta restano sulla prima parte.
- **`continuesMarkerEnabled: true`** colloca `continuesMarker` («Continued», o «Continúa» in un documento spagnolo) sotto l’ultima riga di ogni parte che prosegue, dentro il riquadro, nel carattere e nel corpo del testo del riquadro: in corsivo a meno che `continuesMarkerItalic` non sia `false`, allineato a destra a meno che `continuesMarkerAlign` non indichi `'left'` o `'center'`. Il segno occupa spazio nella parte che chiude, e il taglio viene scelto in modo che ci stia.

```ts
calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],
```

```md
:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::
```

La parte che chiude la pagina termina con «(MORE)», e la pagina successiva si apre con «HAMLET (CONT'D)». Entrambi sono elementi di servizio dell’impaginazione: in un PDF accessibile sono artefatti e nell’HTML sono nascosti alle tecnologie assistive, così il titolo si legge una sola volta. Nel VDT sono blocchi di testo `designOverlay` contrassegnati `artifact: true`.