Document

Un Document envuelve un PDF. Se obtiene mediante imposio.open(), imposio.newDocument(), imposio.activeDocument(), o mediante operaciones que producen un nuevo documento (generateImposition(), splitPages(), copyPages()).

Todos los índices de página son base 0. Los rangos son cadenas: "all", "1-5", "odd", "even", "2,4,7" (vacío = todos). Las longitudes están en la unidad actual, salvo que se proporcionen como cadena con sufijo.

Información

Método	Devuelve	Descripción
isValid()	bool	Si el documento se cargó correctamente.
pageCount()	int	Número de páginas.
filePath()	string	Ruta de origen (vacía para nuevos documentos).
title()	string	El título establecido por script.
setTitle(title)	—	Establece el título de pestaña usado por show() / save().

Bounding boxes y tamaños de página

Cada uno devuelve un objeto en la unidad actual (coordenadas PDF, Y arriba). pageSize devuelve {w, h}; los getters de bounding box devuelven {x, y, w, h}.

Método	Devuelve
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}

Inspección de página (solo lectura)

Método	Devuelve
pageObjects(pageIndex)	Objetos del content stream (recursivo en Form XObjects): [{ 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)	Estructura tagged PDF (vacía si no tagged): [{ type, title, altText, actualText, children:[…] }]

Operaciones de página

Modifican el documento en su lugar (salvo indicación contraria).

resizePages(range, width, height, opts?)

Redimensiona páginas. Los bounding boxes trim/bleed/crop y el contenido de sangrado se conservan.

Clave opts	Valores	Predeterminado
placement	"fit", "fill", "stretch", "keep"	"fit"

deletePages(range)

Elimina las páginas en el rango range.

rotatePages(range, degrees, opts?)

Rota páginas. degrees es absoluto (0/90/180/270); con opts.increment = true se añade a la rotación actual.

duplicatePages(range, opts?)

Duplica páginas. opts.mode: "after" (predeterminado — una copia después de cada una), "block", "append".

reversePages(range?, opts?)

Invierte el orden de las páginas. opts.mode: "inplace" (predeterminado) o "compact".

movePages(range, destIndex)

Mueve las páginas de range antes del índice destIndex (base 0, en el espacio de páginas original).

setPageBoxes(range, boxes)

Establece los bounding boxes como retracciones desde el MediaBox (unidad actual). boxes: { bleed, trim, crop }.

addBlankPage(at, width, height)

Inserta una página en blanco (dimensiones en la unidad actual) en el índice at (-1 = al final).

addPagesFromFile(path, opts?)

Inserta páginas desde un PDF o una imagen (PNG/JPEG/BMP/GIF/TIFF/WebP → una página).

Clave opts	Descripción
range	Páginas de la fuente (solo PDF).
at	Índice de inserción (-1 = al final).

replacePages(targetRange, source, opts?)

Elimina targetRange e inserta en su lugar páginas de source (PDF o imagen). opts.range selecciona las páginas fuente (predeterminado todas; ignorado para imágenes).

splitPages(cols, rows, opts?) → Document

Divide cada página en una cuadrícula cols × rows. Devuelve un nuevo Document.

Clave opts	Valores
area	"media", "trim", "bleed", "crop"
range	páginas a dividir

rasterizePages(range?, dpiOrOpts?)

Reemplaza las páginas por su versión rasterizada (renderizada, aplanada sobre blanco — sin transparencia). En su lugar. El segundo argumento es un número de DPI (legacy) o un objeto:

Clave opts	Valores	Predeterminado
dpi	number	300
cmyk	bool	false (RGB)
intent	"perceptual", "relative", "saturation", "absolute" (o 0–3)	—
iccProfile	ruta .icc	GRACoL incorporado

generateBleed(range?, opts?)

Construye un marco de sangrado alrededor de las páginas a partir del propio borde del arte (GUI Generar sangrado). La página crece size en cada borde; la caja de corte se fija en la página original y la caja de sangrado en el nuevo borde, de modo que la imposición recorta correctamente. Solo se rasteriza el marco añadido — la página sigue siendo vectorial. Las páginas que ya tienen sangrado se omiten. Devuelve el número de páginas modificadas.

Clave opts	Valores	Predeterminado
size	longitud — ancho del sangrado	—
source	longitud — ancho de la franja de origen (más estrecha que size = se estira)	—
method	"mirror", "extend", "replicate", "solid"	—
dpi	DPI ráster del marco	300
blur	suavizar el marco	false
force	procesar también páginas que ya tienen sangrado	false

copyPages(range?, opts?) → Documento

Copia páginas a un documento nuevo (como GUI Copy → New). Devuelve el nuevo Documento o null. opts.bakeLayer: false excluye la capa de edición de Imposio de la copia (arte PDF limpio).

Ediciones del contenido de página

Editar o eliminar objetos del flujo de contenido de la página (el arte en sí, no la capa de edición). indexPath proviene de pageObjects() — p. ej. [3], o [3, 2] para un hijo dentro de un Form XObject. Todas las ediciones preservan la maquetación: el resto de la página queda idéntico byte a byte (sin alineaciones de texto descolocadas).

Método	Descripción
setPageObjectText(page, indexPath, newText, opts?)	Cambia el texto de un objeto de texto. opts { x, y, w, h } lo mueve/redimensiona en el mismo paso.
setPageObjectBounds(page, indexPath, x, y, w, h)	Mover/redimensionar un objeto (unidad actual, Y hacia arriba).
setPageObjectOpacity(page, indexPath, opacity)	Opacidad no destructiva 0–1 (0 = oculto).
duplicateObject(page, indexPath, opts?)	Duplicado vectorial como forma móvil de la capa de edición; opts { dx, dy } desplazamiento. Devuelve el ID de la nueva forma.

smartDeleteObjects(pageIndex, indexPaths, opts?)

Elimina objetos que coinciden con objetos plantilla a lo largo de muchas páginas (GUI Smart Delete) — p. ej. una marca de agua o cabecera repetida por todas partes. pageIndex + indexPaths (un indexPath o un array) determinan los objetos plantilla. Devuelve el número de objetos eliminados, -1 en caso de error.

Clave opts	Valores	Predeterminado
mode	"identical" (mismo objeto) o "position" (lo que esté en ese lugar)	"identical"
range	páginas a procesar	"all"
tolerance	tolerancia de coincidencia (unidad actual)	0,5 pt
verify	re-renderizar cada página modificada y omitirla si cambió algo más	true

Campos de formulario

Leer y rellenar campos PDF interactivos (AcroForm). Los valores se escriben en el formulario y siguen siendo editables; use flattenForms para fijarlos permanentemente en el contenido de la página.

formFields()

Devuelve los campos interactivos del documento. Cada entrada:

Clave	Descripción
name	Nombre completo del campo — la clave para setFormField.
label	Etiqueta legible (/TU, recurre a name).
type	"text", "checkbox", "radio", "choice", "pushbutton", "signature".
value	Valor actual (valor texto/choice; nombre del estado activo para botones).
checked	true/false para casillas de verificación y botones de opción.
choices	Opciones para campos choice (y nombres de estado activo para botones de opción).
readOnly	Bloqueado por el autor del formulario.
multiline	El campo de texto permite saltos de línea.

setFormField(name, value)

Establece el valor de un campo. value es una cadena para los campos de texto y choice, un booleano (o "on"/"off") para las casillas de verificación, y el nombre del estado activo para los botones de opción. El indicador de solo lectura se ignora — el valor se sobrescribe. Devuelve true si se aplicó.

setFormFields(values)

Establece varios campos a la vez desde un objeto { name: value, … } (una pasada por origen; los nombres desconocidos se omiten).

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?)

Fija los valores de los campos de formulario (y las anotaciones) en el contenido de la página para que sobrevivan al cambio de tamaño, la división y la imposición. En su lugar; range predeterminado "all".

Datos variables

mergeData(table, opts)

Combina registros de datos con el documento (GUI Datos variables → Generar): por cada registro se copian las páginas de origen y se expanden los elementos asignados — las plantillas de texto/texto en marco sustituyen el texto, las de imagen se expanden a una ruta de archivo, las de casilla deciden la marca (1/yes/true marca, vacío/0/no desmarca). Marcadores: {columna}, {i:03}, {=expresión}, {{ = literal.

table es el objeto de imposio.loadData (o { columns: […], rows: [[…]] } construido en el script); null = combinación solo con contadores.

Clave opts	Descripción
mapping	Obligatorio. [{ page: 0, shape: id, template: "{nombre}" }]. Las asignaciones de imagen admiten además fit: "fit"\|"fill"\|"stretch"\|"keep" y align: "top-left"…"center"…"bottom-right" (o 0–8).
mode	"new" (predeterminado), "append", "fill".
sourcePages	Rango 1-based; predeterminado = las páginas usadas en mapping.
records	"all", "1-100", …
targets	Solo "fill": páginas que reciben los elementos (predeterminado = páginas tras el bloque de origen).
replace	Solo "fill": true sustituye los elementos de las páginas destino, false añade encima.
counters	[{ name: "i", start: 0, step: 1, max: 100 }] — max opcional; con max la combinación funciona incluso sin tabla.
imageBaseDir	Carpeta base para rutas de imagen relativas.
hidden	[{ page: 0, shape: id }] — Visibilidad: elementos excluidos de la salida.
pdfContent	false excluye el contenido PDF subyacente de las páginas de origen (elementos sobre páginas en blanco; new/append). Predeterminado true.

Devuelve un Documento nuevo para "new", el número de registros combinados para "append"/"fill". Lanza excepción en caso de error (el documento no cambia).

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");

Exportación, guardado y renderizado

exportImage(path, opts?)

Renderiza páginas en archivos de imagen. path es una carpeta o un archivo.

Clave opts	Valores	Predeterminado
format	"tiff", "png", "jpeg", "webp"	—
dpi	number	—
quality	number (JPEG/WebP)	—
box	"media", "trim", "bleed", "crop"	—
range	páginas	todas
pattern	patrón de nombre, p. ej. "{p}" ({p} = nº de página PDF, {n} = contador de salida)	—
multipageTiff	bool — un TIFF para todo el trabajo	—

save(path, opts?)

Guarda en PDF. Devuelve un bool. opts.autoIndex = true añade _1, _2, … si el archivo de destino ya existe (predeterminado false = sobreescribe).

renderPng(pageIndex, dpi, outPath, opts?)

Renderiza una sola página en PNG. opts.background: "#rrggbb" o "none"/"transparent" (predeterminado blanco).

Metadatos y seguridad

Los cambios se escriben en el PDF al ejecutar save() (modelo dirty); ambos son actualizaciones parciales.

metadata() / setMetadata(m)

metadata() devuelve { title, author, subject, keywords, creator, producer, created, modified } (created/modified son de solo lectura). setMetadata({ title?, author?, subject?, keywords?, creator?, producer? }).

security() / setSecurity(s)

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

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

Visualización

show(title?)

Abre este documento como nueva pestaña en la app (GUI Run). No hace nada en modo headless/CLI.