Разработчики постоянно недооценивают PDF-вьюеры. Это кажется простой задачей из разряда «взял и вставил». Вы загружаете байты, указываете URL для компонента — и дело сделано. Vue.js делает большую часть работы с UI такой же простой, однако PDF-вьюер, готовый к продакшену, — это одна из тех функций, которые незаметно разрастаются, поглощая целые спринты. За две недели я четыре раза создавал один и тот же вьюер разными способами. Каждая попытка подтверждала один и тот же вывод: библиотека, которую вы выберете в понедельник, определит, какие баги вы будете исправлять два месяца спустя.
Ловушка устаревших туториалов
Большинство руководств до сих пор рекомендуют библиотеки, которые обновлялись в те времена, когда Vue 2 был стандартом. Разработчик пробегает глазами README, запускает команду установки и считает, что самое сложное позади. На самом деле самое сложное только начинается. Вам понадобится поиск. Вам нужно будет обрабатывать 400-страничный документ с правилами так, чтобы не «уронить» вкладку браузера. Кто-то с мобильного устройства спросит, почему масштабирование щипком (pinch-to-zoom) работает некорректно. В README редко предупреждают о чем-либо из этого, потому что в демо-версии рендерится только первая страница пятистраничной научной статьи.
Четыре подхода
Для Vue не существует одной идеальной PDF-библиотеки. Есть только та, которая лучше всего подходит под задачи ваших пользователей.
PDF.js: Путь DIY
PDF.js от Mozilla — это движок, лежащий в основе почти каждого веб-вьюера. Использование его в приложении на Vue 3 — это не просто установка компонента, это принятие на себя целого проекта. Вы загружаете документ с помощью getDocument, рендерите каждую страницу в элемент <canvas> и привязываете эти canvas к своему шаблону. В первый день вы чувствуете продуктивность. К третьему дню вы уже настраиваете воркер-скрипт, чтобы он нормально работал со сборкой Vite и CORS-заголовками.
Нативного скролла браузера вполне хватает для десяти страниц. На тысяче он начинает тормозить, поэтому вы пишете виртуальный скроллинг. Затем вы замечаете, что текст нельзя выделить, и накладываете прозрачные текстовые div поверх каждого canvas. Печать выглядит размытой, и вы начинаете бороться с настройками DPI и медиа-запросами. Масштабирование щипком на мобильных устройствах конфликтует с нативной обработкой жестов в браузере. Поиск по всему документу означает асинхронное извлечение и индексацию текста на каждой странице, а затем создание интерфейса, который ставит результаты в очередь, не блокируя основной поток. Даже если ИИ-ассистент вроде Cursor генерирует шаблонный код, архитектура всё равно остается на вас. Сложные задачи никуда не исчезают — они просто перекочевывают в ваш код. Этот путь имеет смысл только тогда, когда ваши требования действительно специфичны или когда у вас есть несколько свободных недель и веская причина избегать стандартного поведения готовых решений.
vue-pdf-embed: Легковесный путь
Иногда всё, что вам нужно, — это просто показать файл. vue-pdf-embed — это компонент для Vue 3, который принимает источник и рендерит страницы вертикальным стеком. Установка и интеграция занимают считанные минуты. Для внутренней админ-панели, отображающей сгенерированные счета или отчеты о соответствии, этого часто бывает вполне достаточно. Компонент берет на себя рендеринг canvas, и ваши пользователи могут прокручивать документ.
Обратная сторона медали — отсутствие всего остального. Здесь нет ни панели инструментов, ни поиска по документу, ни боковой панели с миниатюрами, ни навигации по страницам, кроме прокрутки контейнера. Как только стейкхолдер спросит: «А я могу найти номер счета?», ваша двухчасовая интеграция раздуется до полноценной кастомной разработки. Выбирайте этот вариант, если ваши PDF-файлы короткие, аудитория — внутренние сотрудники, а модель взаимодействия — чистое пролистывание в режиме чтения.
@tato30/vue-pdf: Путь контроля
Эта библиотека меняет форму: из монолитного компонента она превращается в composable-функцию. Она предоставляет usePDF, которую вы вызываете внутри блока setup. Вместо рендеринга всего документа с прокруткой, вы управляете каждой страницей по отдельности через реактивные ссылки (refs). Это звучит как лишняя работа, но это дает свободу, когда интерфейс требует точности.
Представьте инструмент для проверки страховых случаев, где эксперты проверяют одну страницу документа, нажимают «Далее», и система регистрирует каждое событие просмотра. Вьюер с непрерывной прокруткой здесь будет неподходящей метафорой. Вам нужен управляемый пагинатор, возможно, с комментариями на уровне страниц или кнопками подтверждения, привязанными непосредственно к индексу текущей страницы. Поскольку usePDF передает вам количество страниц и текущую страницу как реактивные данные, их привязка к кастомной панели навигации или индикатору прогресса кажется естественной. Вам всё равно придется создавать интерфейс (chrome) вокруг canvas, но вы избавляетесь от шаблонного кода низкоуровневого рендеринга. Это подходит для приложений, где пользователи просматривают страницы по одной, а не изучают рукопись целиком.
Vue PDF Viewer: Путь комплексного решения
Наступает момент, когда переписывание функций вьюера начинает отвлекать вас от создания основного продукта. Vue PDF Viewer — это коммерческий компонент, который поставляется с полноценной панелью инструментов, поиском по тексту, аннотациями, адаптивностью для мобильных устройств и виртуальной прокруткой, уже протестированными на всех граничных сценариях. Ваша задача превращается из изобретения в настройку. Вы просто подстраиваете тему под свою дизайн-систему, включаете нужные функции и переходите к работе, которая действительно выделяет ваше приложение среди других.
Первоначальный лицензионный взнос — это реальные расходы, но так же реальны и затраты двух недель работы инженеров на воссоздание индексации поиска и слоев аннотаций. Это правильный инструмент, когда вы выпускаете продакшн-приложение в сжатые сроки и ваши пользователи ожидают интерфейс, сопоставимый с настольным ПО для PDF.
Реальная стоимость установки
Самая большая ошибка — считать команду npm install полной стоимостью. Реальная цена — это то, что вы строите после завершения установки. Легковесная библиотека дешева в первый день, но становится дорогой на двадцатый, когда вы понимаете, что вам нужна строка поиска. Путь самостоятельной разработки (DIY) бесплатен в первый день, но обходится дорого на шестидесятый, когда вы всё еще исправляете области нажатия на мобильных устройствах и стили для печати. Коммерческий путь требует денег сразу, но он может сэкономить недели инженерного времени, которое вы сможете потратить на свою основную бизнес-логику.
Не выбирайте библиотеку только потому, что её README короткий и дружелюбный. Выбирайте, исходя из требований вашего проекта. Боковая панель с миниатюрами, поиск по тексту и аннотации на стороне клиента указывают на необходимость полнофункционального решения. Быстрый предпросмотр чека внутри внутренней панели управления указывает на необходимость легковесного встраивания.
Главный вывод
Прежде чем остановиться на какой-либо Vue PDF библиотеке, четко запишите, что именно должны делать ваши пользователи. Если им нужно просто прокручивать короткие документы, vue-pdf-embed будет достаточно. Если они перелистывают страницы в рамках контролируемого рабочего процесса, выбирайте @tato30/vue-pdf. Если же они делают аннотации, ищут и печатают внутри критически важного для бизнеса приложения — покупайте коммерческий вьюер. А если ваши требования действительно уникальны, но сроки гибкие, выделите несколько недель и стройте решение напрямую на PDF.js. PDF-вьюер — это не просто файл в рамке. Это полноценный интерфейс документа, и ваш выбор строительного блока определит, выпустите ли вы продукт в этом месяце или в следующем квартале.