Розробники постійно недооцінюють PDF-переглядачі. Це здається простою задачею «файл у коробці». Ви отримуєте байти, вказуєте URL для компонента — і вважаєте справу зробленою. Vue.js робить більшість завдань з UI такими ж простими, проте PDF-переглядач, готовий до продакшену, — це одна з тих функцій, що непомітно розростаються, поглинаючи цілі спринти. Я побудував один і той самий переглядач чотирма різними способами протягом двох тижнів. Кожна спроба підтверджувала одне й те саме: бібліотека, яку ви оберете в понеділок, визначає, які баги ви будете виправляти через два місяці.
Пастка застарілих туторіалів
Більшість посібників досі рекомендують бібліотеки, які востаннє оновлювалися ще тоді, коли Vue 2 був стандартом. Розробник пробігається очима по README, запускає команду встановлення і вважає, що найскладніше позаду. Насправді найскладніше тільки починається. Вам знадобиться пошук. Вам потрібно буде обробляти 400-сторінковий документ із правилами так, щоб не «покласти» вкладку браузера. Хтось із мобільних користувачів запитає, чому масштабування пальцями (pinch-to-zoom) працює некоректно. У README рідко про це попереджають, бо в демо-версії рендериться лише перша сторінка з п'ятисторінкової наукової статті.
Чотири підходи
Не існує єдиної найкращої PDF-бібліотеки для Vue. Є лише та, що найкраще підходить під конкретні потреби ваших користувачів.
PDF.js: Шлях DIY
PDF.js від Mozilla — це двигун, що лежить в основі майже кожного веб-переглядача. Додати його у Vue 3 додаток — це не те саме, що встановити компонент; це означає взяти на себе цілий проєкт. Ви отримуєте документ за допомогою getDocument, рендерите кожну сторінку на елемент <canvas> і підключаєте ці канваси до свого шаблону. У перший день ви відчуваєте продуктивність. На третій день ви вже налаштовуєте worker-скрипт, щоб він коректно працював із бандлінгом Vite та CORS-заголовками.
Нативний скрол браузера добре працює для десяти сторінок. На тисячі він «захлинається», тому ви створюєте віртуальний скрол. Потім ви помічаєте, що текст неможливо виділити, і накладаєте прозорі div із текстом поверх кожного канвасу. Друк виглядає розмитим, тому ви починаєте полювати на налаштування DPI та медіа-запити. Масштабування пальцями на мобільних пристроях конфліктує з нативною обробкою жестів браузером. Пошук по всьому документу означає асинхронне вилучення та індексацію тексту на кожній сторінці, а потім створення інтерфейсу, який ставить результати в чергу, не блокуючи основний потік. Навіть якщо AI-асистент на кшталт Cursor генерує шаблонний код (boilerplate), архітектура все одно залишається на вас. Складні моменти не зникають; вони переносяться у ваш кодовий базис. Цей шлях має сенс лише тоді, коли ваші вимоги справді специфічні, або коли у вас є кілька вільних тижнів і вагома причина уникати готових рішень.
vue-pdf-embed: Легковажний шлях
Іноді все, що вам потрібно, — це просто показати файл. vue-pdf-embed — це компонент Vue 3, який приймає джерело та рендерить сторінки вертикальним стеком. Встановлення та інтеграція займають лічені хвилини. Для внутрішньої адмін-панелі, що відображає згенеровані інвойси або звіти про відповідність, цього часто цілком достатньо. Компонент бере на себе рендеринг канвасу, а ваші користувачі можуть гортати сторінки.
Ціною цього є все інше. Тут немає ні панелі інструментів, ні пошуку по документу, ні бічної панелі з ескізами, ні навігації по сторінках, окрім прокручування контейнера. Щойно стейкхолдер запитає: «Чи можу я знайти номер інвойсу?», ваша двогодинна інтеграція перетвориться на розробку власного рішення. Обирайте цей варіант, якщо ваші PDF-файли короткі, аудиторія — внутрішні співробітники, а модель взаємодії — суто перегляд шляхом прокручування.
@tato30/vue-pdf: Шлях контролю
Ця бібліотека змінює свою суть: від монолітного компонента до composable-функції. Вона надає usePDF, яку ви викликаєте всередині блоку setup. Замість рендерингу всього документа, що прокручується, ви керуєте кожною сторінкою окремо за допомогою реактивних ref. Це звучить як додаткова робота, але це дає свободу, коли інтерфейс потребує точності.
Уявіть інструмент для розгляду страхових претензій, де експерти перевіряють одну сторінку документа, натискають «Далі», і система реєструє кожну подію перегляду. Безперервний переглядач зі скролом тут був би невідповідною метафорою. Вам потрібен керований пагінатор, можливо, з коментарями на рівні сторінки або кнопками підтвердження, прив'язаними безпосередньо до індексу поточної сторінки. Оскільки usePDF надає вам кількість сторінок і поточну сторінку як реактивні дані, їх підключення до кастомної панелі навігації або індикатора прогресу виглядає природно. Вам все одно доведеться створювати інтерфейс (chrome) навколо канвасу, але ви позбуваєтеся шаблонного коду рендерингу найнижчого рівня. Це підходить для додатків, де користувачі переглядають сторінки по черзі, а не проглядають увесь рукопис цілком.
Vue PDF Viewer: Шлях комплексного рішення
Настає момент, коли повторне створення функцій перегляду стає відволіканням від вашого основного продукту. Vue PDF Viewer — це комерційний компонент, який постачається з повноцінною панеллю інструментів, пошуком тексту, анотаціями, адаптивністю для мобільних пристроїв та віртуальним прокручуванням, що вже протестовано в граничних випадках. Ваше завдання перетворюється з винаходу на конфігурацію. Ви налаштовуєте тему відповідно до вашої дизайн-системи, вмикаєте потрібні функції та переходите до роботи, яка дійсно виділяє ваш додаток серед інших.
Попередня ліцензійна плата — це реальність, але так самою реальністю є вартість двох тижнів інженерного часу, витраченого на відтворення індексації пошуку та шарів анотацій. Це правильний інструмент, коли ви випускаєте робочий додаток у стислі терміни, а ваші користувачі очікують досвіду, порівняного з настільним програмним забезпеченням для PDF.
Скільки насправді коштує встановлення
Найбільша помилка — сприймати команду npm install як повну ціну. Справжня вартість — це те, що ви будуєте після завершення встановлення. Легка бібліотека дешева в перший день, але стає дорогою на двадцятий, коли ви усвідомлюєте, що вам потрібна панель пошуку. Шлях DIY безкоштовний у перший день, але стає дорогим на шістдесятий, коли ви все ще виправляєте зони дотику для мобільних пристроїв та таблиці стилів для друку. Комерційний шлях потребує грошей наперед, але він може заощадити вам тижні інженерного часу, який ви зможете витратити на власну бізнес-логіку.
Не обирайте бібліотеку лише тому, що її README короткий і приємний. Обирайте на основі вимог вашого проєкту. Бічна панель із мініатюрами, пошук тексту та клієнтські анотації вказують на повнофункціональне рішення. Швидкий попередній перегляд чека всередині внутрішньої панелі керування вказує на легке вбудовування.
Головний висновок
Перш ніж зупинитися на будь-якій бібліотеці Vue PDF, запишіть саме те, що мають робити ваші користувачі. Якщо їм потрібно просто гортати короткі документи, vue-pdf-embed вирішить ваше завдання. Якщо вони переходять між сторінками у контрольованому робочому процесі, зверніться до @tato30/vue-pdf. Якщо вони роблять анотації, шукають і друкують у критично важливому для бізнесу додатку, купіть комерційний в'юер. А якщо ваші вимоги справді унікальні, але терміни гнучкі, виділіть кілька тижнів і будуйте безпосередньо на PDF.js. PDF-в'юер — це ніколи не просто файл у коробці. Це повноцінний інтерфейс документа, і ваш вибір базового компонента визначить, чи випустите ви продукт цього місяця, чи наступного кварталу.