Document¶
Document является обёрткой PDF. Его можно получить через
imposio.open(),
imposio.newDocument(), imposio.activeDocument() или через операции, создающие новый
документ (generateImposition(), splitPages(), copyPages()).
Все индексы страниц начинаются с 0. Диапазоны — строки: "all", "1-5", "odd",
"even", "2,4,7" (пустая = все). Длины задаются в текущей единице, если не указана
строка с суффиксом.
Информация¶
| Метод | Возвращает | Описание |
|---|---|---|
isValid() |
bool | Успешно ли загружен документ. |
pageCount() |
int | Количество страниц. |
filePath() |
string | Путь к источнику (пустой для новых документов). |
title() |
string | Заголовок, заданный скриптом. |
setTitle(title) |
— | Задаёт заголовок вкладки для show() / save(). |
Боксы и размеры страниц¶
Каждый возвращает объект в текущей единице (PDF-координаты, Y вверх). pageSize
возвращает {w, h}; геттеры боксов возвращают {x, y, w, h}.
| Метод | Возвращает |
|---|---|
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} |
Инспекция страниц (только чтение)¶
| Метод | Возвращает |
|---|---|
pageObjects(pageIndex) |
Объекты content stream (рекурсивно в 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) |
Структура tagged PDF (пустая, если не tagged): [{ type, title, altText, actualText, children:[…] }] |
Операции со страницами¶
Изменяют документ на месте (если не указано иное).
resizePages(range, width, height, opts?)¶
Изменяет размер страниц. Боксы trim/bleed/crop и контент вылета сохраняются.
Ключ opts |
Значения | По умолчанию |
|---|---|---|
placement |
"fit", "fill", "stretch", "keep" |
"fit" |
deletePages(range)¶
Удаляет страницы в диапазоне range.
rotatePages(range, degrees, opts?)¶
Поворачивает страницы. degrees — абсолютное (0/90/180/270); при
opts.increment = true добавляется к текущему повороту.
duplicatePages(range, opts?)¶
Дублирует страницы. opts.mode: "after" (по умолчанию — копия после каждой),
"block", "append".
reversePages(range?, opts?)¶
Меняет порядок страниц на обратный. opts.mode: "inplace" (по умолчанию) или
"compact".
movePages(range, destIndex)¶
Перемещает страницы из range перед индекс destIndex (0-базированный, в
пространстве исходных страниц).
setPageBoxes(range, boxes)¶
Задаёт боксы как отступы от MediaBox (текущая единица). boxes: { bleed, trim, crop }.
addBlankPage(at, width, height)¶
Вставляет пустую страницу (размеры в текущей единице) по индексу at (-1 = в конец).
addPagesFromFile(path, opts?)¶
Вставляет страницы из PDF или изображения (PNG/JPEG/BMP/GIF/TIFF/WebP → одна страница).
Ключ opts |
Описание |
|---|---|
range |
Страницы источника (только PDF). |
at |
Индекс вставки (-1 = в конец). |
replacePages(targetRange, source, opts?)¶
Удаляет targetRange и вставляет на это место страницы из source (PDF или
изображение). opts.range выбирает страницы источника (по умолчанию все; для
изображений игнорируется).
splitPages(cols, rows, opts?) → Document¶
Разрезает каждую страницу на сетку cols × rows. Возвращает новый Document.
Ключ opts |
Значения |
|---|---|
area |
"media", "trim", "bleed", "crop" |
range |
страницы для разрезания |
rasterizePages(range?, dpiOrOpts?)¶
Заменяет страницы их растеризованной версией (отрендеренной, выровненной по белому — без прозрачности). На месте. Второй аргумент — число DPI (legacy) или объект:
Ключ opts |
Значения | По умолчанию |
|---|---|---|
dpi |
number | 300 |
cmyk |
bool | false (RGB) |
intent |
"perceptual", "relative", "saturation", "absolute" (или 0–3) |
— |
iccProfile |
путь .icc |
встроенный GRACoL |
generateBleed(range?, opts?)¶
Строит рамку вылета вокруг страниц из собственного края графики (GUI Создать вылет).
Страница растёт на size с каждого края; обрезной формат устанавливается на исходную
страницу, а вылет — на новый край, так что спуск полос обрежет правильно. Растрируется
только добавленная рамка — страница остаётся векторной. Страницы с уже имеющимся вылетом
пропускаются. Возвращает число изменённых страниц.
Ключ opts |
Значения | По умолчанию |
|---|---|---|
size |
длина — ширина вылета | — |
source |
длина — ширина исходной полосы (уже size = растягивается) |
— |
method |
"mirror", "extend", "replicate", "solid" |
— |
dpi |
растровое DPI рамки | 300 |
blur |
смягчить рамку | false |
force |
обрабатывать и страницы с уже имеющимся вылетом | false |
copyPages(range?, opts?) → Документ¶
Копирует страницы в новый документ (как GUI Copy → New). Возвращает новый Документ или
null. opts.bakeLayer: false не включает слой редактирования Imposio в копию (чистая
PDF-графика).
Правки содержимого страницы¶
Редактирование или удаление объектов собственного потока содержимого страницы (сама
графика, не слой редактирования). indexPath берётся из pageObjects() — напр. [3] или
[3, 2] для потомка внутри Form XObject. Все правки сохраняют вёрстку: остальная часть
страницы остаётся байт в байт той же (никаких поехавших выравниваний текста).
| Метод | Описание |
|---|---|
setPageObjectText(page, indexPath, newText, opts?) |
Меняет текст текстового объекта. opts { x, y, w, h } тем же шагом перемещает/масштабирует его. |
setPageObjectBounds(page, indexPath, x, y, w, h) |
Перемещение/изменение размера объекта (текущие единицы, Y вверх). |
setPageObjectOpacity(page, indexPath, opacity) |
Недеструктивная непрозрачность 0–1 (0 = скрыт). |
duplicateObject(page, indexPath, opts?) |
Векторный дубликат как подвижная фигура слоя редактирования; opts { dx, dy } смещение. Возвращает ID новой фигуры. |
smartDeleteObjects(pageIndex, indexPaths, opts?)¶
Удаляет объекты, соответствующие объектам-образцам, на многих страницах (GUI Smart
Delete) — например, водяной знак или колонтитул, повторяющийся везде. pageIndex +
indexPaths (один indexPath или их массив) задают объекты-образцы. Возвращает число
удалённых объектов, -1 при ошибке.
Ключ opts |
Значения | По умолчанию |
|---|---|---|
mode |
"identical" (тот же объект) или "position" (что бы там ни находилось) |
"identical" |
range |
какие страницы обрабатывать | "all" |
tolerance |
допуск совпадения (текущие единицы) | 0,5 pt |
verify |
перерендерить каждую изменённую страницу и пропустить её, если изменилось что-то ещё | true |
Поля формы¶
Чтение и заполнение интерактивных полей PDF (AcroForm). Значения записываются в форму и остаются редактируемыми; используйте flattenForms, чтобы навсегда впечатать их в содержимое страницы.
formFields()¶
Возвращает интерактивные поля документа. Каждый элемент:
| Ключ | Описание |
|---|---|
name |
Полное имя поля — ключ для setFormField. |
label |
Читаемая подпись (/TU, запасной вариант — name). |
type |
"text", "checkbox", "radio", "choice", "pushbutton", "signature". |
value |
Текущее значение (значение text/choice; имя активного состояния для кнопок). |
checked |
true/false для флажков и переключателей. |
choices |
Варианты для choice-полей (и имена активного состояния для переключателей). |
readOnly |
Заблокировано автором формы. |
multiline |
Текстовое поле допускает переносы строк. |
setFormField(name, value)¶
Задаёт значение одного поля. value — строка для text и choice-полей, логическое значение (или "on"/"off") для флажков и имя активного состояния для переключателей. Признак «только для чтения» игнорируется — значение перезаписывается. Возвращает true, если применено.
setFormFields(values)¶
Задаёт несколько полей сразу из объекта { name: value, … } (один проход на источник; неизвестные имена пропускаются).
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?)¶
Впечатывает значения полей формы (и аннотации) в содержимое страниц, чтобы они пережили изменение размера, разделение и спуск полос. На месте; range по умолчанию "all".
Переменные данные¶
mergeData(table, opts)¶
Объединяет записи данных с документом (GUI Переменные данные → Создать): для каждой
записи копируются исходные страницы и разворачиваются сопоставленные элементы — шаблоны
текста/текста в рамке заменяют текст, шаблон изображения разворачивается в путь к файлу,
шаблон флажка определяет отметку (1/yes/true отмечает, пусто/0/no снимает).
Заполнители: {столбец}, {i:03}, {=выражение}, {{ = литерал.
table — объект из imposio.loadData (или
{ columns: […], rows: [[…]] }, собранный в скрипте); null = объединение только со
счётчиками.
Ключ opts |
Описание |
|---|---|
mapping |
Обязателен. [{ page: 0, shape: id, template: "{имя}" }]. Сопоставления изображений принимают также fit: "fit"\|"fill"\|"stretch"\|"keep" и align: "top-left"…"center"…"bottom-right" (или 0–8). |
mode |
"new" (по умолчанию), "append", "fill". |
sourcePages |
Диапазон с 1; по умолчанию = страницы, использованные в mapping. |
records |
"all", "1-100", … |
targets |
Только "fill": страницы, получающие элементы (по умолчанию = страницы после исходного блока). |
replace |
Только "fill": true заменяет элементы целевых страниц, false добавляет поверх. |
counters |
[{ name: "i", start: 0, step: 1, max: 100 }] — max необязателен; с max объединение работает и без таблицы. |
imageBaseDir |
Базовая папка для относительных путей изображений. |
hidden |
[{ page: 0, shape: id }] — Видимость: пункты, исключённые из вывода. |
pdfContent |
false исключает подложку PDF исходных страниц (элементы на чистых страницах; new/append). По умолчанию true. |
Возвращает новый Документ для "new", число объединённых записей для
"append"/"fill". При ошибке бросает исключение (документ не меняется).
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");
Экспорт, сохранение и рендеринг¶
exportImage(path, opts?)¶
Рендерит страницы в файлы изображений. path — папка или файл.
Ключ opts |
Значения | По умолчанию |
|---|---|---|
format |
"tiff", "png", "jpeg", "webp" |
— |
dpi |
number | — |
quality |
number (JPEG/WebP) | — |
box |
"media", "trim", "bleed", "crop" |
— |
range |
страницы | все |
pattern |
шаблон имени, напр. "{p}" ({p} = № страницы PDF, {n} = счётчик вывода) |
— |
multipageTiff |
bool — один TIFF для всей работы | — |
save(path, opts?)¶
Сохраняет в PDF. Возвращает bool. opts.autoIndex = true добавляет _1, _2, … если
целевой файл уже существует (по умолчанию false = перезаписывает).
renderPng(pageIndex, dpi, outPath, opts?)¶
Рендерит одну страницу в PNG. opts.background: "#rrggbb" или
"none"/"transparent" (по умолчанию белый).
Метаданные и безопасность¶
Изменения записываются в PDF при save() (модель dirty); оба — частичные обновления.
metadata() / setMetadata(m)¶
metadata() возвращает { title, author, subject, keywords, creator, producer, created,
modified } (created/modified — только чтение). setMetadata({ title?, author?,
subject?, keywords?, creator?, producer? }).
security() / setSecurity(s)¶
security() возвращает { encrypt, algorithm, userPassword, ownerPassword, allowPrint,
allowHighResPrint, allowCopy, allowModify, allowAnnotate, allowForms, allowExtract,
allowAssembly, wasEncrypted }.
setSecurity({ encrypt?, userPassword?, ownerPassword?, algorithm?, allow…? }) —
encrypt: false снимает защиту при сохранении. algorithm: "rc4-128", "aes-128",
"aes-256".
Отображение¶
show(title?)¶
Открывает этот документ новой вкладкой в приложении (GUI Run). В режиме headless/CLI ничего не делает.