Встраивание в PDF

Одним из распространённых сценариев использования HERE Maps API является генерация PDF-документов, содержащих карты, маршруты, географические метки и результаты пространственного анализа. Такие документы используются в логистике, транспортных системах, корпоративной отчётности, страховании, геомаркетинге, службах доставки и системах мониторинга.

При работе с PDF необходимо учитывать важную особенность: интерактивная карта HERE Maps представляет собой HTML-компонент, основанный на JavaScript, тогда как PDF является статическим документом. Поэтому процесс встраивания карты обычно сводится к получению изображения карты и его последующему размещению внутри PDF-файла.

Основные подходы к интеграции карт в PDF

Существует несколько способов добавления картографических данных в PDF-документ:

Получение статического изображения карты через сервисы HERE.
Создание снимка интерактивной карты.
Генерация карты на сервере и экспорт в PDF.
Использование Canvas для формирования изображения.
Создание отчётов с несколькими картами и маршрутами.

Наиболее распространённым является получение изображения карты с последующей передачей его в библиотеку генерации PDF.

Использование статических карт

Для PDF-документов чаще всего используются статические изображения.

Преимущества:

небольшой размер документа;
высокая скорость генерации;
отсутствие зависимости от JavaScript после создания PDF;
одинаковое отображение на любых устройствах.

Типичная схема выглядит следующим образом:

HERE Maps API
        ↓
Получение изображения карты
        ↓
Base64 или URL изображения
        ↓
PDF Generator
        ↓
Готовый PDF

Библиотеки для генерации PDF

В JavaScript широко используются следующие решения:

Библиотека	Назначение
jsPDF	Создание PDF в браузере
PDFKit	Генерация PDF на Node.js
pdf-lib	Работа с существующими PDF
Puppeteer	Экспорт HTML-страниц в PDF
pdfmake	Декларативное создание документов

Для большинства браузерных приложений используется jsPDF.

Подключение:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

Получение изображения карты

Перед добавлением карты в PDF необходимо получить её графическое представление.

Создание карты:

const platform = new H.service.Platform({
    apikey: "YOUR_API_KEY"
});

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
    document.getElementById("map"),
    defaultLayers.vector.normal.map,
    {
        zoom: 12,
        center: {
            lat: 55.7558,
            lng: 37.6176
        }
    }
);

После визуализации карту необходимо преобразовать в изображение.

Использование Canvas для экспорта карты

Многие элементы HERE Maps рендерятся внутри Canvas.

Получение снимка:

function captureMap() {
    const canvas = document.querySelector("canvas");

    return canvas.toDataURL("image/png");
}

Результат:

const imageData = captureMap();

Переменная будет содержать строку формата:

data:image/png;base64,...

Такой формат напрямую поддерживается большинством PDF-библиотек.

Создание PDF с картой

Простейший пример на jsPDF:

const { jsPDF } = window.jspdf;

const pdf = new jsPDF();

pdf.text("Отчёт по объекту", 20, 20);

pdf.addImage(
    imageData,
    "PNG",
    10,
    30,
    180,
    100
);

pdf.save("report.pdf");

После выполнения будет сформирован документ, содержащий карту.

Добавление нескольких карт

В отчётах часто требуется отображать несколько регионов одновременно.

Пример:

const images = [
    image1,
    image2,
    image3
];

const pdf = new jsPDF();

images.forEach((img, index) => {

    if (index > 0) {
        pdf.addPage();
    }

    pdf.addImage(
        img,
        "PNG",
        10,
        20,
        180,
        100
    );

});

Каждая карта будет размещена на отдельной странице.

Экспорт маршрутов в PDF

Одним из наиболее востребованных сценариев является экспорт маршрута.

Получение маршрута:

router.calculateRoute(
    routingParameters,
    onResult,
    onError
);

После отображения маршрута на карте выполняется создание снимка.

Пример формирования отчёта:

pdf.text("Маршрут доставки", 20, 20);

pdf.addImage(
    routeImage,
    "PNG",
    10,
    30,
    180,
    100
);

pdf.text(
    "Длина маршрута: 24 км",
    20,
    150
);

pdf.text(
    "Время в пути: 35 минут",
    20,
    160
);

В результате PDF содержит не только изображение маршрута, но и сопутствующую информацию.

Добавление маркеров перед экспортом

Перед созданием снимка можно динамически разместить точки интереса.

const marker = new H.map.Marker({
    lat: 55.7558,
    lng: 37.6176
});

map.addObject(marker);

После рендеринга карты выполняется экспорт изображения.

Все маркеры окажутся на итоговой карте внутри PDF.

Добавление нескольких объектов

Карта может содержать большое количество элементов.

Например:

locations.forEach(location => {

    const marker = new H.map.Marker({
        lat: location.lat,
        lng: location.lng
    });

    map.addObject(marker);

});

После генерации PDF получится полноценный географический отчёт.

Использование пользовательских иконок

Для повышения информативности PDF используются кастомные маркеры.

const icon = new H.map.Icon(
    "./images/warehouse.png"
);

const marker = new H.map.Marker(
    {
        lat: 55.75,
        lng: 37.61
    },
    {
        icon
    }
);

При создании снимка пользовательские изображения сохраняются вместе с картой.

Добавление полигонов и зон

В отчётах часто отображаются обслуживаемые территории.

Создание полигона:

const polygon = new H.map.Polygon(
    lineString
);

map.addObject(polygon);

После экспорта PDF содержит визуально выделенную область.

Примеры применения:

зоны доставки;
страховые регионы;
административные границы;
районы обслуживания;
охраняемые территории.

Использование HTML2Canvas

Если карта размещена внутри сложного интерфейса, удобнее сохранять весь контейнер.

Подключение:

<script src="https://cdnjs.cloudflare.com/ajax/libs/html2canvas/1.4.1/html2canvas.min.js"></script>

Создание снимка:

html2canvas(
    document.getElementById("report")
)
.then(canvas => {

    const image = canvas.toDataURL();

});

Преимущество заключается в том, что одновременно сохраняются:

карта;
легенда;
таблицы;
подписи;
графики.

Формирование комплексного отчёта

Типичный PDF-документ может содержать:

Заголовок.
Сведения об объекте.
Карту.
Таблицу координат.
Маршрут.
Статистику.
Дополнительные изображения.

Структура:

pdf.text("Отчёт", 20, 20);

pdf.addImage(mapImage, "PNG", 10, 30, 180, 100);

pdf.text("Координаты", 20, 145);

pdf.text(
    "55.7558, 37.6176",
    20,
    155
);

Использование PDFKit на Node.js

На серверной стороне часто применяется PDFKit.

Установка:

npm install pdfkit

Создание документа:

const PDFDocument = require("pdfkit");
const fs = require("fs");

const doc = new PDFDocument();

doc.pipe(
    fs.createWriteStream(
        "report.pdf"
    )
);

doc.text("Маршрут");

doc.image(
    "map.png",
    {
        width: 500
    }
);

doc.end();

Такой подход удобен для автоматической генерации отчётов без участия браузера.

Экспорт через Puppeteer

Если карта встроена в веб-страницу, можно сформировать PDF напрямую.

Пример:

const browser =
    await puppeteer.launch();

const page =
    await browser.newPage();

await page.goto(
    "http://localhost/report"
);

await page.pdf({
    path: "report.pdf",
    format: "A4"
});

await browser.close();

Преимущества метода:

сохраняется вся верстка;
поддерживаются стили CSS;
возможно создание многостраничных отчётов;
не требуется вручную размещать элементы в PDF.

Работа с высоким разрешением

Для печатных документов рекомендуется использовать изображения повышенного качества.

Увеличение размера экспортируемой карты:

const map = new H.Map(
    container,
    layer,
    {
        pixelRatio: 2
    }
);

Либо:

window.devicePixelRatio = 2;

Высокое разрешение особенно важно для:

формата A4;
плакатов;
технической документации;
отчётов с большим количеством объектов.

Оптимизация размера PDF

Карты могут значительно увеличивать размер документа.

Методы уменьшения объёма:

использование JPEG вместо PNG;
снижение разрешения изображения;
удаление лишних слоёв;
сокращение количества страниц;
повторное использование изображений.

Пример:

const imageData =
    canvas.toDataURL(
        "image/jpeg",
        0.8
    );

Автоматическая генерация отчётов

Часто PDF формируется автоматически после получения данных от сервера.

Схема работы:

База данных
      ↓
Координаты
      ↓
HERE Maps
      ↓
Построение карты
      ↓
Снимок карты
      ↓
Генерация PDF
      ↓
Отправка пользователю

Подобный механизм используется в:

системах логистики;
сервисах доставки;
CRM-платформах;
системах мониторинга транспорта;
аналитических панелях.

Обработка асинхронной загрузки карты

Перед созданием PDF необходимо дождаться полной отрисовки карты.

Пример:

map.addEventListener(
    "mapviewchangeend",
    () => {

        generatePdf();

    }
);

Это предотвращает появление пустых или неполностью загруженных изображений.

Добавление метаданных документа

Большинство PDF-библиотек позволяют сохранять информацию о документе.

Пример:

pdf.setProperties({
    title: "Отчёт маршрута",
    subject: "Логистика",
    author: "HERE Maps System",
    keywords: "maps,routing,pdf"
});

Метаданные используются поисковыми системами, архивами и корпоративными хранилищами документов.

Типичная архитектура решения

Полноценная система генерации PDF на базе HERE Maps обычно состоит из следующих компонентов:

Frontend
    ↓
HERE Maps API
    ↓
Рендеринг карты
    ↓
Canvas Snapshot
    ↓
PDF Generator
    ↓
PDF-файл

Для серверных решений структура может выглядеть иначе:

Backend
    ↓
HERE APIs
    ↓
Получение маршрутов
    ↓
Создание изображений
    ↓
PDFKit
    ↓
Генерация документа

Такой подход позволяет формировать профессиональные картографические отчёты, содержащие статические карты, маршруты, географические объекты, зоны покрытия, пользовательские маркеры и аналитические данные, сохраняя совместимость с любыми системами просмотра и печати PDF-документов.