Document

Un Document racchiude un PDF. Si ottiene tramite imposio.open(), imposio.newDocument(), imposio.activeDocument(), o tramite operazioni che producono un nuovo documento (generateImposition(), splitPages(), copyPages()).

Tutti gli indici di pagina sono base 0. Gli intervalli sono stringhe: "all", "1-5", "odd", "even", "2,4,7" (vuoto = tutte). Le lunghezze sono nell'unità corrente, salvo che siano fornite come stringa con suffisso.

Informazioni

Metodo	Restituisce	Descrizione
isValid()	bool	Se il documento è stato caricato correttamente.
pageCount()	int	Numero di pagine.
filePath()	string	Percorso sorgente (vuoto per nuovi documenti).
title()	string	Il titolo impostato da script.
setTitle(title)	—	Imposta il titolo della scheda usato da show() / save().

Box e dimensioni delle pagine

Ognuna restituisce un oggetto nell'unità corrente (coordinate PDF, Y verso l'alto). pageSize restituisce {w, h}; i getter di box restituiscono {x, y, w, h}.

Metodo	Restituisce
pageSize(pageIndex)	{w, h}
mediaBox(pageIndex)	{x, y, w, h}
cropBox(pageIndex)	{x, y, w, h}
trimBox(pageIndex)	{x, y, w, h}
bleedBox(pageIndex)	{x, y, w, h}

Ispezione delle pagine (sola lettura)

Metodo	Restituisce
pageObjects(pageIndex)	Oggetti del content stream (ricorsivo nei Form XObject): [{ indexPath:[…], type:"text\|path\|image\|shading\|form\|unknown", bbox:{x,y,w,h} }]
annotations(pageIndex)	[{ subtype:int, type:"Link\|Text\|Widget\|…", summary, bbox:{x,y,w,h} }]
resources(pageIndex)	[{ kind:"font\|image\|form", name, primary, secondary, warning:bool }]
structTree(pageIndex)	Struttura tagged PDF (vuota se non taggata): [{ type, title, altText, actualText, children:[…] }]

Operazioni sulle pagine

Modificano il documento in-place (salvo diversa indicazione).

resizePages(range, width, height, opts?)

Ridimensiona le pagine. Le box trim/bleed/crop e il contenuto di abbondanza vengono preservati.

Chiave opts	Valori	Predefinito
placement	"fit", "fill", "stretch", "keep"	"fit"

deletePages(range)

Elimina le pagine nell'intervallo range.

rotatePages(range, degrees, opts?)

Ruota le pagine. degrees è assoluto (0/90/180/270); con opts.increment = true viene aggiunto alla rotazione corrente.

duplicatePages(range, opts?)

Duplica le pagine. opts.mode: "after" (predefinito — una copia dopo ognuna), "block", "append".

reversePages(range?, opts?)

Inverte l'ordine delle pagine. opts.mode: "inplace" (predefinito) o "compact".

movePages(range, destIndex)

Sposta le pagine di range prima dell'indice destIndex (base 0, nello spazio delle pagine originali).

setPageBoxes(range, boxes)

Imposta le box come rientranze dalla MediaBox (unità corrente). boxes: { bleed, trim, crop }.

addBlankPage(at, width, height)

Inserisce una pagina bianca (dimensioni nell'unità corrente) all'indice at (-1 = fine).

addPagesFromFile(path, opts?)

Inserisce pagine da un PDF o un'immagine (PNG/JPEG/BMP/GIF/TIFF/WebP → una pagina).

Chiave opts	Descrizione
range	Pagine della sorgente (solo PDF).
at	Indice di inserimento (-1 = fine).

replacePages(targetRange, source, opts?)

Elimina targetRange e inserisce al suo posto le pagine di source (PDF o immagine). opts.range seleziona le pagine sorgente (predefinito tutte; ignorato per le immagini).

splitPages(cols, rows, opts?) → Document

Suddivide ogni pagina in una griglia cols × rows. Restituisce un nuovo Document.

Chiave opts	Valori
area	"media", "trim", "bleed", "crop"
range	pagine da suddividere

rasterizePages(range?, dpiOrOpts?)

Sostituisce le pagine con la loro versione rasterizzata (renderizzata, appiattita su bianco — senza trasparenza). In-place. Il secondo argomento è un numero di DPI (legacy) o un oggetto:

Chiave opts	Valori	Predefinito
dpi	number	300
cmyk	bool	false (RGB)
intent	"perceptual", "relative", "saturation", "absolute" (o 0–3)	—
iccProfile	percorso .icc	GRACoL incorporato

generateBleed(range?, opts?)

Costruisce una cornice di abbondanza attorno alle pagine dal bordo stesso della grafica (GUI Genera abbondanza). La pagina cresce di size su ogni bordo; la box di rifilo viene impostata sulla pagina originale e la box di abbondanza sul nuovo bordo, così l'imposizione rifila correttamente. Viene rasterizzata solo la cornice aggiunta — la pagina resta vettoriale. Le pagine che hanno già l'abbondanza vengono saltate. Restituisce il numero di pagine modificate.

Chiave opts	Valori	Default
size	lunghezza — larghezza dell'abbondanza	—
source	lunghezza — larghezza della striscia sorgente (più stretta di size = stirata)	—
method	"mirror", "extend", "replicate", "solid"	—
dpi	DPI raster della cornice	300
blur	ammorbidire la cornice	false
force	elaborare anche le pagine che hanno già l'abbondanza	false

copyPages(range?, opts?) → Documento

Copia le pagine in un nuovo documento (come GUI Copy → New). Restituisce il nuovo Documento o null. opts.bakeLayer: false esclude il livello di modifica Imposio dalla copia (grafica PDF pulita).

Modifiche al contenuto della pagina

Modificare o rimuovere oggetti del content stream della pagina (la grafica stessa, non il livello di modifica). indexPath proviene da pageObjects() — ad es. [3], o [3, 2] per un figlio dentro un Form XObject. Tutte le modifiche preservano il layout: il resto della pagina resta identico byte per byte (niente allineamenti di testo saltati).

Metodo	Descrizione
setPageObjectText(page, indexPath, newText, opts?)	Cambia il testo di un oggetto testo. opts { x, y, w, h } lo sposta/ridimensiona nello stesso passo.
setPageObjectBounds(page, indexPath, x, y, w, h)	Sposta/ridimensiona un oggetto (unità corrente, Y verso l'alto).
setPageObjectOpacity(page, indexPath, opacity)	Opacità non distruttiva 0–1 (0 = nascosto).
duplicateObject(page, indexPath, opts?)	Duplicato vettoriale come forma mobile del livello di modifica; opts { dx, dy } offset. Restituisce l'ID della nuova forma.

smartDeleteObjects(pageIndex, indexPaths, opts?)

Elimina gli oggetti corrispondenti agli oggetti modello su molte pagine (GUI Smart Delete) — ad es. una filigrana o un'intestazione ripetuta ovunque. pageIndex + indexPaths (un indexPath o un array) individuano gli oggetti modello. Restituisce il numero di oggetti eliminati, -1 in caso di errore.

Chiave opts	Valori	Default
mode	"identical" (stesso oggetto) o "position" (qualunque cosa si trovi lì)	"identical"
range	pagine da elaborare	"all"
tolerance	tolleranza di corrispondenza (unità corrente)	0,5 pt
verify	ri-renderizzare ogni pagina modificata e saltarla se è cambiato qualcos'altro	true

Campi modulo

Leggere e compilare i campi PDF interattivi (AcroForm). I valori vengono scritti nel modulo e restano modificabili; usa flattenForms per fissarli in modo permanente nel contenuto della pagina.

formFields()

Restituisce i campi interattivi del documento. Ogni voce:

Chiave	Descrizione
name	Nome completo del campo — la chiave per setFormField.
label	Etichetta leggibile (/TU, ripiego su name).
type	"text", "checkbox", "radio", "choice", "pushbutton", "signature".
value	Valore corrente (valore testo/choice; nome dello stato attivo per i pulsanti).
checked	true/false per caselle di controllo e pulsanti di opzione.
choices	Opzioni per i campi choice (e nomi di stato attivo per i pulsanti di opzione).
readOnly	Bloccato dall'autore del modulo.
multiline	Il campo di testo consente le interruzioni di riga.

setFormField(name, value)

Imposta il valore di un campo. value è una stringa per i campi testo e choice, un booleano (o "on"/"off") per le caselle di controllo e il nome dello stato attivo per i pulsanti di opzione. Il contrassegno di sola lettura viene ignorato — il valore viene sovrascritto. Restituisce true se applicato.

setFormFields(values)

Imposta più campi in una volta da un oggetto { name: value, … } (un passaggio per origine; i nomi sconosciuti vengono ignorati).

var d = imposio.open("invoice-template.pdf");
d.setFormFields({
  customer: "ACME Ltd",
  agree:    true,        // checkbox
  color:    "/green",    // radio on-state
  city:     "Kosice"     // choice
});
d.save("invoice-filled.pdf");

flattenForms(range?)

Fissa i valori dei campi modulo (e le annotazioni) nel contenuto della pagina perché sopravvivano a ridimensionamento, suddivisione e imposizione. Sul posto; range predefinito "all".

Dati variabili

mergeData(table, opts)

Unisce i record di dati al documento (GUI Dati variabili → Genera): per ogni record le pagine di origine vengono copiate e gli elementi mappati espansi — i modelli di testo/testo in cornice sostituiscono il testo, i modelli immagine si espandono in un percorso di file, i modelli casella decidono la spunta (1/yes/true spunta, vuoto/0/no toglie). Segnaposto: {colonna}, {i:03}, {=espressione}, {{ = letterale.

table è l'oggetto di imposio.loadData (o { columns: […], rows: [[…]] } costruito nello script); null = merge con soli contatori.

Chiave opts	Descrizione
mapping	Obbligatorio. [{ page: 0, shape: id, template: "{nome}" }]. Le mappature immagine accettano anche fit: "fit"\|"fill"\|"stretch"\|"keep" e align: "top-left"…"center"…"bottom-right" (o 0–8).
mode	"new" (default), "append", "fill".
sourcePages	Intervallo 1-based; default = le pagine usate in mapping.
records	"all", "1-100", …
targets	Solo "fill": pagine che ricevono gli elementi (default = pagine dopo il blocco sorgente).
replace	Solo "fill": true sostituisce gli elementi delle pagine di destinazione, false aggiunge sopra.
counters	[{ name: "i", start: 0, step: 1, max: 100 }] — max facoltativo; con max il merge funziona anche senza tabella.
imageBaseDir	Cartella base per i percorsi immagine relativi.
hidden	[{ page: 0, shape: id }] — Visibilità: voci escluse dall'output.
pdfContent	false esclude il contenuto PDF sottostante delle pagine di origine (elementi su pagine vuote; new/append). Default true.

Restituisce un nuovo Documento per "new", il numero di record uniti per "append"/"fill". Lancia un'eccezione in caso di errore (il documento resta invariato).

var data = imposio.loadData("guests.csv");
var doc  = imposio.activeDocument();
var out  = doc.mergeData(data, {
  mapping: [{ page: 0, shape: 3, template: "{firstname} {lastname}" }],
  counters: [{ name: "i", start: 1 }],
});
out.save("badges.pdf");

Esportazione, salvataggio e rendering

exportImage(path, opts?)

Renderizza le pagine in file immagine. path è una cartella o un file (dedotto).

Chiave opts	Valori	Predefinito
format	"tiff", "png", "jpeg", "webp"	—
dpi	number	—
quality	number (JPEG/WebP)	—
box	"media", "trim", "bleed", "crop"	—
range	pagine	tutte
pattern	pattern di nome, es. "{p}" ({p} = n° pagina PDF, {n} = contatore output)	—
multipageTiff	bool — un TIFF per l'intero lavoro	—

save(path, opts?)

Salva in PDF. Restituisce un bool. opts.autoIndex = true aggiunge _1, _2, … se il file di destinazione esiste già (predefinito false = sovrascrive).

renderPng(pageIndex, dpi, outPath, opts?)

Renderizza una singola pagina in PNG. opts.background: "#rrggbb" o "none"/"transparent" (predefinito bianco).

Metadati e sicurezza

Le modifiche vengono scritte nel PDF al save() (modello dirty); entrambe sono aggiornamenti parziali.

metadata() / setMetadata(m)

metadata() restituisce { title, author, subject, keywords, creator, producer, created, modified } (created/modified in sola lettura). setMetadata({ title?, author?, subject?, keywords?, creator?, producer? }).

security() / setSecurity(s)

security() restituisce { encrypt, algorithm, userPassword, ownerPassword, allowPrint, allowHighResPrint, allowCopy, allowModify, allowAnnotate, allowForms, allowExtract, allowAssembly, wasEncrypted }.

setSecurity({ encrypt?, userPassword?, ownerPassword?, algorithm?, allow…? }) — encrypt: false rimuove la sicurezza al salvataggio. algorithm: "rc4-128", "aes-128", "aes-256".

Visualizzazione

show(title?)

Apre questo documento come nuova scheda nell'app (GUI Run). No-op in modalità headless/CLI.