Vue 3アプリケーションでのPDF表示

Vue 3 SPAにPDFを埋め込むのは簡単に聞こえますが、最初のCORSエラーに遭遇したり、Safariでのブラウザレンダリングが異なることに気づいたり、200ページのドキュメントがメインスレッドをブロックしていることに気づくまでの話です。この記事では、開発者が実際にVue 3でPDFを表示するために使用する3つの実用的なアプローチを、それぞれの正直なトレードオフとともに解説します。

3つの主要なアプローチ

1. ネイティブブラウザ埋め込み:<iframe>または<embed>

PDFを画面に表示する最速の方法は、ブラウザ組み込みのPDFレンダラーに任せることです。

<template>
  <iframe
    :src="pdfUrl"
    width="100%"
    height="700px"
    style="border: none"
  />
</template>

<script setup lang="ts">
const pdfUrl = '/documents/report.pdf'
</script>

うまく機能する場合: 社内ツール、管理ダッシュボード、またはUI一貫性が重要でなく、PDFが同一オリジンから提供される任意のコンテキスト。

実際の制限事項:

• ツールバー、ズームコントロール、テーマに対する制御がゼロ
• ブラウザ間で動作が異なる—Chrome、Firefox、Safariはそれぞれ異なるレンダリングを行う
• モバイルブラウザはインライン表示ではなくファイルをダウンロードすることが多い
• 読み込み状態がVueコンポーネントから見えないため、スピナーを表示したりエラーを適切に処理できない

異なるドメインからPDFを読み込む場合、サーバーが正しいAccess-Control-Allow-Originヘッダーを送信しない限り、ブラウザはリクエストをブロックします。バックエンドに同一オリジンのプロキシエンドポイントを設置するのが最もクリーンな解決策です。

2. PDF.jsとVue 3:直接統合

PDF.jsはMozillaのオープンソースPDFレンダリングエンジンです。5.xリリースシリーズ以降、ESMファーストパッケージとして提供されています。build/pdf.mjsからインポートし、レンダリングをメインスレッドから外すために別のワーカー(pdf.worker.mjs)を読み込みます。

npm install pdfjs-dist

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs'

pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).toString()

const canvasRef = ref<HTMLCanvasElement | null>(null)

onMounted(async () => {
  const pdf = await pdfjsLib.getDocument('/documents/report.pdf').promise
  const page = await pdf.getPage(1)
  const viewport = page.getViewport({ scale: 1.5 })
  const canvas = canvasRef.value!
  const ctx = canvas.getContext('2d')!
  canvas.height = viewport.height
  canvas.width = viewport.width
  await page.render({ canvasContext: ctx, viewport }).promise
})
</script>

<template>
  <canvas ref="canvasRef" />
</template>

得られるもの: レンダリング、ページナビゲーション、ズーム、テーマの完全な制御。PDF.jsは標準的なアノテーションとAcroFormフィールドをサポートしていますが、フォームとアノテーションの動作はレンダリング設定に依存する場合があります。

知っておくべきこと:

• pdfjs-distパッケージは、クライアントバンドルに顕著なペイロードを追加します。動的なimport()を使用して遅延ロードしてください。
• XFAベースのフォーム(古い政府のPDFで一般的)はサポートが限定的で、正しくレンダリングされない場合があります。
• 大きなドキュメントの場合、サーバーがHTTP範囲リクエスト(Accept-Ranges: bytes)をサポートしていれば、PDF.jsはPDFをチャンクで取得でき、大きなファイルの体感パフォーマンスを向上させることができます。
• ワーカー設定は、Viteプロジェクトで最も一般的なセットアップの問題です。上記のnew URL(..., import.meta.url)パターンは、ビルド時にワーカーパスを正しく解決します。

3. Vue PDFラッパー

いくつかのメンテナンスされているVue 3コンポーネントがPDF.jsをラップし、よりシンプルなコンポーネントAPIを公開しています。vue-pdf-embedは、ワーカーのセットアップ、ページレンダリング、リアクティブなプロップ更新を処理してくれる、アクティブにメンテナンスされているオプションの1つです。

<script setup lang="ts">
import VuePdfEmbed from 'vue-pdf-embed'
</script>

<template>
  <VuePdfEmbed source="/documents/report.pdf" />
</template>

トレードオフは、ボイラープレートの大幅な削減と引き換えに、より細かい制御が少なくなることです。これらのラッパーは、Vue 3 PDFビューアを迅速に必要とし、レンダリングパイプラインをカスタマイズする必要がない場合に適しています。

注意: vue3-pdf-appのような古いパッケージの中には、もはやアクティブにメンテナンスされていないものもあります。採用する前に、ラッパーのメンテナンス状況とViteのような最新のバンドラーとの互換性を評価してください。

適切なアプローチの選択

まとめ

ほとんどのVue 3アプリケーションでは、決定は簡単です。シンプルな同一オリジン埋め込みには<iframe>を使用し、多くのセットアップなしで動作するビューアが必要な場合はメンテナンスされているVueラッパーを使用し、大きなドキュメントのレンダリング、ナビゲーション、パフォーマンスを完全に制御する必要がある場合はPDF.jsを直接統合してください。どの道を選んでも、PDF.jsワーカーを正しく設定し、ライブラリを遅延ロードしてください。この2つのステップだけで、開発者がVueアプリにPDFを埋め込む際に遭遇する最も一般的な問題を防ぐことができます。

よくある質問

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.