Полное руководство по созданию PDF-файлов с помощью Puppeteer: от простых документов до сложных отчетов

Puppeteer — это библиотека для Node.js, которая автоматизирует работу с браузерами Chrome или Chromium, делая её мощным инструментом для создания PDF-документов. Независимо от того, создаёте ли вы простые документы или сложные отчёты, Puppeteer предлагает такие функции, как встроенная поддержка PDF, настройка макетов и интеграция с автоматизацией для упрощения процесса.

Основные возможности Puppeteer для генерации PDF:

• Простая настройка: Используйте Headless-браузер на основе Puppeteer и начните создавать PDF-документы с помощью всего нескольких строк кода.
• Настраиваемые макеты: Изменяйте размер страницы, ориентацию, поля и многое другое.
• Динамический контент: Рендерите страницы с большим количеством JavaScript, применяйте пользовательские стили и добавляйте заголовки, нижние колонтитулы и номера страниц.
• Производительность: Быстрее, чем альтернативы, такие как Selenium, для создания PDF.
• Масштабируемость: Подходит для генерации большого количества PDF-документов, даже для тысяч документов в день.

Почему это полезно:

Puppeteer идеально подходит для автоматизации рабочих процессов, создания отчётов или экспорта веб-контента. От бизнесов, создающих брендированные документы, до разработчиков, работающих с визуализацией данных, Puppeteer упрощает процесс и обеспечивает высокое качество результатов.

Если вы готовы начать, эта статья проведёт вас через настройку, кастомизацию и расширенные функции, такие как обработка больших отчётов и устранение распространённых проблем.

Базовая настройка PDF с помощью Puppeteer

Чтобы начать работу с Puppeteer для создания PDF-документов, необходимо правильно его настроить и понять основные параметры конфигурации. Вот краткое руководство, которое поможет вам начать.

Создание вашего первого PDF

Для генерации простого PDF-документа из веб-страницы создайте файл app.js со следующим кодом:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.freecodecamp.org/', {
    waitUntil: 'networkidle0'
  });
  await page.pdf({
    path: 'example.pdf',
    format: 'Letter'
  });
  await browser.close();
})();

‍

Этот скрипт описывает основной рабочий процесс: запуск браузера, открытие страницы, переход по URL, генерация PDF и закрытие браузера.

Настройки страницы и макета

Puppeteer позволяет настраивать различные параметры для создания PDF. Ниже приведены ключевые параметры, которые можно изменить:

При генерации PDF из веб-страниц используйте параметр waitUntil: 'networkidle0'. Это гарантирует, что вся сетевая активность завершена перед созданием PDF.

Для пользовательского HTML-контента вы можете создавать PDF-документы с использованием локальных файлов. Это особенно полезно для шаблонных документов или пакетной обработки. Обновите функцию page.goto() следующим образом:

await page.goto(`file://${absolutePath}`, {
  waitUntil: 'networkidle0'
});

‍

Поскольку Puppeteer использует движок рендеринга Chrome, любые CSS-стили или форматирование, поддерживаемые Chrome, будут точно отображаться в ваших PDF-документах. Для более сложных задач вы можете изучить расширенные методы форматирования для создания детализированных PDF-отчётов.

Опции форматирования PDF

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

Заголовки и нижние колонтитулы

Вы можете добавить заголовки и нижние колонтитулы, изменив параметры PDF с помощью HTML-шаблонов. Вот пример:

await page.pdf({
  displayHeaderFooter: true,
  headerTemplate: `<div style="font-size: 10px; padding: 10px; width: 100%; text-align: center;">
    <span class="title"></span> | Сгенерировано <span class="date"></span>
  </div>`,
  footerTemplate: `<div style="font-size: 10px; padding: 10px; width: 100%; text-align: center;">
    Страница <span class="pageNumber"></span> из <span class="totalPages"></span>
  </div>`,
  margin: { top: '1.25in', bottom: '1in' }
});

‍

Вот динамические классы, которые вы можете использовать:

• date: Добавляет текущую метку времени.
• title: Отображает заголовок документа.
• url: Показывает URL страницы.
• pageNumber: Вставляет номер текущей страницы.
• totalPages: Указывает общее количество страниц.

Управление разрывами страниц и макетом

Для управления разрывами страниц и обеспечения плавного потока контента используйте CSS-правила, такие как:

.no-break {
  page-break-inside: avoid;
}
<!-- -->
.force-break {
  page-break-after: always;
}

‍

Вы также можете настроить параметры бумаги непосредственно в опциях PDF:

Шрифты и визуальные элементы

Настройте шрифты и визуальные элементы в соответствии с вашим брендингом:

• Пользовательские веб-шрифты:

@font-face {
  font-family: 'CustomFont';
  src: url('path/to/font.woff2') format('woff2');
}

• Включение фоновых цветов и изображений:

await page.pdf({ printBackground: true });

‍

body {
  -webkit-print-color-adjust: exact;
<!-- -->  background-color: #f5f5f5;
<!-- -->}

• Настройка шрифтов для Linux или AWS Lambda:

export FONTCONFIG_FILE=/path/to/fonts.conf

Эти опции позволяют создавать профессионально выглядящие PDF-документы.

Создание сложных PDF-отчётов

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

Таблицы и диаграммы данных

Улучшите свои отчёты с помощью динамической визуализации, объединив Puppeteer, D3.js и Handlebars. Вот пример настройки для интеграции диаграмм данных:

const template = Handlebars.compile(`
  <div class="report-container">
    {{> dataTable}}
    <div id="chart"></div>
  </div>
`);

// Конфигурация диаграммы D3.js
const chartConfig = {
  container: '#chart',
  data: salesData,
  width: 800,
  height: 400
};

‍

Чтобы ваш PDF выглядел профессионально, настройте параметры вывода следующим образом:

await page.pdf({
  printBackground: true,
  format: 'Letter',
  margin: {
    top: '0.75in',
    right: '0.5in',
    bottom: '0.75in',
    left: '0.5in'
  }
<!-- -->});

‍

"D3.js — это библиотека JavaScript для работы с документами на основе данных. D3 помогает оживить данные с помощью HTML, SVG и CSS."

После добавления визуализации организуйте отчёт с содержанием и номерами страниц.

Содержание и нумерация страниц

Следуйте этим шагам, чтобы добавить оглавление и обеспечить точную нумерацию страниц:

1. Создание начального PDF: Создайте первую версию PDF с заголовками и нижними колонтитулами:

const mainPdf = await page.pdf({
  format: 'Letter',
  displayHeaderFooter: true
});

2. Извлечение номеров страниц: Извлеките номера страниц и динамически создайте оглавление:

const pageMapping = await extractPageNumbers(mainPdf);
const tocHtml = generateTocHtml(pageMapping);

3. Объединение финального документа: Объедините оглавление с основным документом:

const finalPdf = await mergePdfs([tocPdf, mainPdf]);

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

Обработка больших отчётов

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

Например, в апреле 2024 года компания Carriyo генерировала 10 000 PDF-документов ежедневно с 95-м процентилем задержки в 365 мс на AWS Lambda. Вот как можно применить обработку временных файлов:

// Оптимизация обработки файлов
const tempFile = await saveTempHtml(content);
await page.goto(`file://${tempFile}`, {
  waitUntil: 'networkidle0',
  timeout: 30000
});

‍

"Используя временные файлы для обхода ограничений протокола, мы улучшили производительность и надёжность." — Данинду де Сильва

Если вы столкнулись с проблемами при навигации, убедитесь, что ошибки логируются, и перезагрузите страницу:

try {
  await page.goto(url, {
    waitUntil: 'networkidle0',
    timeout: 30000
  });
} catch (error) {
  console.error('Ошибка навигации:', error);
  await page.reload();
}

‍

Эти методы гарантируют, что генерация больших отчётов остаётся надёжной и эффективной.

Распространённые проблемы и решения

Решение распространённых проблем — ключ к обеспечению бесперебойной работы ваших автоматизированных процессов генерации PDF. Следующие решения основаны на базовых настройках, рассмотренных ранее.

Совместимость с браузерами

В третьем квартале 2023 года команда разработчиков Acme Corp устранила ошибки "Не удалось запустить Chrome" на серверах Ubuntu, установив необходимые зависимости. Это снизило количество ошибок на 95% и сэкономило 10 часов в неделю на отладку.

Для проблем с запуском Chrome на Windows используйте следующую конфигурацию:

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--disable-extensions'],
  args: ['--disable-features=HttpsFirstBalancedModeAutoEnable']
});

Руководство по устранению ошибок

Вот как эффективно устранять распространённые ошибки:

Например, для обработки тайм-аутов навигации можно использовать следующую логику повторных попыток:

const navigateWithRetry = async (page, url) => {
  try {
    await page.goto(url, {
      waitUntil: 'networkidle0',
      timeout: 30000
    });
  } catch (error) {
    console.error('Ошибка навигации:', error);
    await page.reload();
  }
<!-- -->};

‍

После устранения ошибок можно сосредоточиться на улучшении скорости для повышения эффективности рабочих процессов.

Оптимизация скорости

После устранения ошибок следующим шагом является ускорение генерации PDF. Например, Carriyo генерирует 10 000 PDF-документов ежедневно с 95-м процентилем задержки в 365 мс на AWS Lambda.

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

await page.setRequestInterception(true);
page.on('request', request => {
  if (request.resourceType() === 'font' || request.resourceType() === 'image') {
    request.respond({
      body: localFileContent,
      headers: { 'Cache-Control': 'public, max-age=31536000' }
    });
<!-- -->  }
<!-- -->});

‍

Для крупномасштабных операций рассмотрите следующие стратегии:

• Управление ресурсами: Держите экземпляры браузера "тёплыми" на серверных платформах, чтобы избежать холодных стартов, которые увеличивают задержку.
• Конфигурация системы: На 4-ядерной системе ограничьте одновременную генерацию PDF тремя процессами для повышения стабильности.
• Оптимизация сети: Используйте API перехвата сети Puppeteer для локального обслуживания статических ресурсов.

"Используя временные файлы для обхода ограничений протокола, мы улучшили производительность и надёжность." — Данинду де Сильва

Использование Puppeteer с Нодулем

Нодуль упрощает использование Puppeteer для генерации PDF, предлагая масштабируемый и экономически эффективный способ автоматизации рабочих процессов с документами.

Как работает Нодуль

Нодуль объединяет возможности Puppeteer для создания PDF с такими инструментами, как визуальный конструктор рабочих процессов, генерация кода с использованием ИИ и условная логика. Платформа также поддерживает широкий спектр NPM-пакетов. Нодуль использует кредитную систему на основе времени, что помогает эффективно управлять затратами на автоматизацию PDF.

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

Вот ключевые функции для автоматизации PDF:

• Интеграция с Headless-браузером
• Генерация пользовательского кода с помощью ИИ
• Визуальный конструктор рабочих процессов для настройки логики PDF
• Поддержка условных ветвлений в рабочих процессах

Настройка Puppeteer в Нодуле

Чтобы использовать Puppeteer для генерации PDF в Нодуле, выполните базовую настройку:

const puppeteer = require('puppeteer');

async function generatePDF(url) {
  const browser = await puppeteer.launch({
    headless: true,
    args: ['--disable-dev-shm-usage']
  });
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle0' });
  const pdf = await page.pdf({ format: 'A4' });
  await browser.close();
  return pdf;
}

‍

Для безопасной генерации документов храните конфиденциальную информацию, такую как учётные данные, в переменных окружения:

await page.type('#email', process.env.PDF_USER);
await page.type('#password', process.env.PDF_PASSWORD);

‍

Эта настройка обеспечивает безопасный и эффективный рабочий процесс для генерации PDF.

Сравнение платформ автоматизации

При выборе платформы для автоматизации PDF вот как Нодуль сравнивается с традиционными инструментами:

Для корпоративного использования премиум-план Нодуля ($297/месяц) поддерживает до 1,5 миллионов запусков сценариев и хранит историю выполнения до 60 дней. Это делает его отличным выбором для бизнесов с высокими потребностями в генерации PDF.

Платформа также упрощает задачи, такие как изменение стилей страницы перед созданием PDF. Например, вы можете скрыть определённые элементы с помощью этого фрагмента кода:

await page.addStyleTag({
  content: '.nav { display: none } .navbar { border: 0px } #print-button { display: none }'
});

‍

Эта гибкость помогает упростить даже самые сложные рабочие процессы с PDF.

Заключение

Основные моменты

Puppeteer — это мощный инструмент для генерации PDF, будь то простые документы или сложные отчёты. Его способность работать с современными веб-технологиями и предоставлять точный контроль над выводом PDF делает его отличным выбором для крупномасштабных задач.

Например, в апреле 2024 года Carriyo успешно использовала Puppeteer для генерации 10 000 PDF-документов ежедневно для этикеток доставки на AWS Lambda. Они достигли 95-го процентиля задержки в 365 мс при стоимости $7,68 за 430 000 вызовов.

Вот ключевые функции и их практические преимущества:

Советы для начала работы

Чтобы максимально эффективно использовать Puppeteer, рассмотрите следующие шаги для успешного внедрения:

• Оптимизация производительности: Используйте настройку userDataDir для кэширования ресурсов и отключения неиспользуемых функций, чтобы ускорить генерацию PDF.
• Управление ресурсами: Генерируйте PDF на стороне сервера, чтобы снизить нагрузку на клиентские устройства, особенно для задач с большим объёмом.
• Обработка ошибок: Реализуйте надёжные стратегии обработки ошибок с тайм-аутами и механизмами повторных попыток для стабильности в производственных средах.

Для ещё более плавного опыта вы можете интегрировать Puppeteer с платформами, такими как Нодуль, чтобы упростить рабочие процессы, сохраняя при этом высокую производительность.