Параметры страницы

Оформление листа задаёт объект options в теле запроса. Все поля необязательные: без них получится A4 с полями по сантиметру.

json

{
  "source": "html",
  "html": "<h1>Счёт №95</h1>",
  "options": { "marginTop": "20mm", "marginBottom": "20mm", "landscape": false }
}

Поля options#

landscapebooleanнеобязательное
Альбомная ориентация.
По умолчанию:
false
paperWidthstringнеобязательное
Ширина листа. По умолчанию A4.
Формат:
число и единица pt, px, in, mm, cm или pc без пробела: «20mm», «1.5cm», «.5in»; без единицы — дюймы
Пример:
"8.27in"
paperHeightstringнеобязательное
Высота листа. По умолчанию A4.
Формат:
число и единица pt, px, in, mm, cm или pc без пробела: «20mm», «1.5cm», «.5in»; без единицы — дюймы
Пример:
"11.7in"
marginTopstringнеобязательное
Верхнее поле.
Формат:
число и единица pt, px, in, mm, cm или pc без пробела: «20mm», «1.5cm», «.5in»; без единицы — дюймы
Пример:
"20mm"
marginBottomstringнеобязательное
Нижнее поле.
Формат:
число и единица pt, px, in, mm, cm или pc без пробела: «20mm», «1.5cm», «.5in»; без единицы — дюймы
Пример:
"20mm"
marginLeftstringнеобязательное
Левое поле.
Формат:
число и единица pt, px, in, mm, cm или pc без пробела: «20mm», «1.5cm», «.5in»; без единицы — дюймы
Пример:
"0.39in"
marginRightstringнеобязательное
Правое поле.
Формат:
число и единица pt, px, in, mm, cm или pc без пробела: «20mm», «1.5cm», «.5in»; без единицы — дюймы
Пример:
"0.39in"
waitDelaystringнеобязательное
Подождать перед печатью, пока скрипт на странице дорисует содержимое: график, шрифт с CDN, данные по fetch.
Формат:
число и s или ms, не больше 10 секунд: «2s», «500ms»
По умолчанию:
"0s"
Пример:
"1s"

Неизвестный ключ в options или значение не того типа вернёт ответ 400 invalid_request с именем поля в message, а не молча проигнорированный параметр. Для документов Office работает только landscape.

Единицы размеров#

Размер — число и единица без пробела: pt, px, in, mm, cm или pc. Например: 20mm, 1.5cm, .5in.

Пробел (20 mm), заглавные буквы (20MM) и запятая вместо точки (1,5cm) — ошибка 400.

Число без единицы API понимает как дюймы. Библиотеки pdfapi такого рода значений не пропускают: "20" почти всегда задумано как миллиметры, а 20 дюймов полей просто не влезут на лист.

Лист	paperWidth	paperHeight
A4 (по умолчанию)	`8.27in`	`11.7in`
A5	`5.83in`	`8.27in`
A3	`11.7in`	`16.54in`
Letter	`8.5in`	`11in`

Ожидание скриптов#

Если страница дорисовывается скриптом — график, данные по fetch, шрифт с CDN — без необходимой паузы PDF напечатается раньше времени. waitDelay откладывает печать на время до 10 секунд:

json

{ "source": "url", "url": "https://example.com/report", "options": { "waitDelay": "2s" } }

Ставьте наименьшую паузу, которой точно хватит. Она добавляется к времени каждого запроса.

CSS для печати#

Документ печатается как при печати в браузере, поэтому работает обычный CSS для печати.

Разрыв страницы перед элементом и запрет разрыва внутри:

css

.new-page { break-before: page; }
table, figure { break-inside: avoid; }

Стили только для PDF:

css

@media print {
  nav, .no-print { display: none; }
}

Фон страницы

Фон элементов печатается, а фон самой страницы ( body или html) нет. Если нужна цветная страница целиком, то оберните содержимое в блок с фоном и задайте ему высоту листа.

Шрифты и картинки#

Шрифты подключайте через @font-face или Google Fonts — и добавьте waitDelay на 1–2 секунды, чтобы шрифт успел загрузиться. Кириллица в стандартных шрифтах есть.

Картинки — полными адресами https://… или в data:. Относительные пути вроде img/logo.png в источнике HTML не сработают, потому что документу не от чего их отсчитывать.