syncfusion-react-pdf-viewer

Syncfusion React Pdfviewer – UI サンプルジェネレーター

対象パッケージ：@syncfusion/ej2-react-pdfviewer

ユーザーのプロジェクト向けにコードを生成する（デフォルト）

トリガーキーワード：「方法」「pdfviewer を追加」「コードサンプル」「見せて」「例」「スニペット」「統合」「コンポーネント」「サンプルを作成」「React サンプル」。

目的： ユーザーが React プロジェクトに直接統合できる、最小限でコピーして貼り付け可能な TS および HTML コードを生成します。

ワークフロー： ⚠️ 重要 — 機能サポートポリシー（厳格モード）：

基本ルール： 参照ファイルに明示的に記載されている API とプロパティのみを使用してコードを生成してください。それ以外はすべて違反です。

• コード生成前に必ず行う確認：

  1. 参照ファイルを検索し、API／プロパティ名が正確に記載されているか確認します
  2. メソッドリファレンス、プロパティ、またはイベントの表に記載されていることを確認します
  3. いずれの参照ファイルにも記載されていない場合は、ただちに処理を停止します
  4. 文書化されていない API を、いかなる状況でも生成または提案しないでください

• 厳格な適用 — 例外なし：

  • カスタムプロパティは禁止 — 参照ファイルの表に記載されたプロパティのみ使用してください
  • メソッドの創作は禁止 — 参照ファイルの表に記載されたメソッドのみ使用してください
  • 未定義の API を使った回避策は禁止
  • 文書化されていない動作についての推測は禁止
  • 推測に基づく代替実装は禁止
  • サポートがあるかのように装うことは禁止

• 未サポート機能に対する必須の回答：

  • 要求されたシナリオ／機能／API がいずれの参照ファイルにも記載されていない場合、次のように回答してください：

    "This feature is not supported in the current Syncfusion React PDF Viewer implementation."
    

  • 続けて、該当する参照ファイルでサポートされている項目を列挙してください
  • 参照ファイルに明示的な記載がない限り、代替案を提案しないでください

• 参照ファイルの優先順位：

  • 各参照ファイルには、その対象領域に関する完全かつ正式なドキュメントが含まれています
  • 表（メソッドリファレンス、プロパティ、イベント）が信頼できる唯一の情報源です
  • 参照ファイル内でこれらの表以外にある内容は、説明に限られます
  • 参照ファイルの表に記載されている範囲を超えないでください

• 生成内容を監査する：

  • コードを提示する前に、使用するすべての API が参照ファイルの表に記載されていることを確認します
  • 各 API の出典となる参照ファイルを明記します
  • 参照ファイルの表の項目を引用できない場合は、そのコードを削除します

• これは重要な要件です。 違反すると、このスキルの完全性と信頼性が損なわれます。

ステップ 1 — アプリケーションの種類を検出する（必須 — 省略禁止）

• file_search および read_file ツールを使用して、ワークスペースのプロジェクトファイルを調べます：
  • package.json（プロジェクト設定と依存関係）
  • tsconfig.json（TypeScript の設定）
  • App.tsx または App.jsx（ルートコンポーネント）
  • vite.config.ts または webpack.config.js（ビルド設定）
  • src/ フォルダー内にある既存の .tsx または .jsx ファイル
• 出力： 先に進む前に、検出したアプリケーションの種類が React の TypeScript または JavaScript プロジェクトであることを確認します。

ステップ 2 — 参照ファイルのみからコードを生成する (必須)

• 生成前に: ステップ 1 が完了していることを確認します
• 要求された機能に関連する references/*.md ファイルを読みます
• すべての API、プロパティ、メソッドをこれらの表と照合します
• コンポーネントベースのアプローチ（必須 — React パターンのみ）:
  • React コンポーネントの構成には JSX/TSX 構文を使用します
  • すべての PDF ビューアーのプロパティをコンポーネントの props として直接設定します
  • プログラムからアクセスする必要がある場合は、React フック（useState、useRef、useEffect）を使用します
• 必須: コードを生成する前に、参照ファイルが存在し、アクセス可能であることを確認します
• 要求された機能に適切な参照ファイルを読みます:
  • 関連する references/*.md ファイルで read_file ツールを使用します
  • ファイルに Methods/Properties/Events の各表が含まれていることを確認します
  • 表が完全で読み取れることを確認します
• 参照ファイルがない、または読み取れない場合:
  • コード生成を停止します
  • 次のように応答します: "Reference file for this feature is not available. Please ensure all reference files are present in the references/ directory."
  • 不足している参照ファイル名を列挙します
• これはブロッカーとなるステップです: 参照ファイルの検証なしには先に進めません
• API／プロパティが参照ファイルの表に記載されていない場合は、使用しないでください
• 参照ファイルに明記されていない API、メソッド、プロパティ、クラス、名前空間を創作、推測、提案しないでください

---

参照ファイルのルーティングガイド

すべてのテンプレートと操作スニペットは references/*.md にあります。各ファイルには、サンプルの生成時にエージェントが組み合わせる、特定の用途に絞ったスニペットまたはテンプレートが含まれています。

フロー: 常に getting-started.md から始め、該当する機能をアンカー（PROPS、EVENTS、UI_BUTTONS、HANDLERS）に組み合わせます。キーワードが一致しない場合は、基本的なサンプルのみを返します。

コード生成前のチェックリスト

• 設定プロパティの数: 1～3 個ならインライン、4 個以上なら定数を使用します
• 列挙型を使用しますか？ はい → インポートを含む型付き定数を使用する必要があります | いいえ → インラインで使用できます
• ほかの場所でも再利用しますか？ はい → 定数を使用します | いいえ → インラインを優先します
• 型安全性が必要ですか？ はい → type { SettingsModel } をインポートします | いいえ → 型のインポートは省略します
• 列挙型が必要ですか？ はい → 必要な列挙型をインポートします | いいえ → 列挙型のインポートは省略します
• コンポーネントの prop は十分に単純ですか？ はい → インラインのままにします | いいえ → 定数に切り出します

🎯 コア設定と構成

ファイル	用途	ユーザーから次の質問があった場合に使用
getting-started.md	documentPath、height、width を指定した最小構成の PDFViewer。すべてのサンプルのベーステンプレートです。	「基本設定」、「最小限の例」、「使い始める」、「PDF の読み込み方法」
general-properties.md	ビューアーの主要なプロパティ（サーバー URL、ドキュメントパス、ロケール、リソースのベースパス）を設定します。	「構成」、「サーバー設定」、「ロケール」、「ドキュメントパスの設定」
enable-properties.md	特定の機能（ツールバー、注釈、フォーム、ナビゲーション、テキスト選択、ダウンロード、印刷）を有効／無効にします。	「ツールバーを無効にする」、「機能を非表示にする」、「有効化／無効化」、「読み取り専用モード」、「機能を制限する」

📐 ナビゲーション() とページ管理

ファイル	目的	ユーザーから質問された場合のルーティング先
page-navigation.md	ページ間を移動します（最初、最後、次、前のページ）。特定のページ番号に移動します。	「ページナビゲーション」、「ページに移動」、「次のページ」、「前のページ」、「ページにジャンプ」
bookmark-navigation.md	ブックマークパネル内の PDF ブックマーク／目次を使って移動します。重要：ブックマーク関連のすべてのメソッドは、viewerRef.current から直接ではなく、viewerRef.current.bookmark.* 経由で呼び出す必要があります（例：viewerRef.current.bookmark.openBookmarkPane()）。	「ブックマーク」、「目次」、「TOC ナビゲーション」、「アウトラインパネル」、「ブックマークを取得」、「ブックマークをプログラムから取得」、「ブックマークを取得」、「ブックマークを取得」、「getBookmarks」、「goToBookmark」、「ブックマーク API」、「ブックマークの一覧表示」、「ブックマークを開く」、「ブックマークを閉じる」
hyperlink-navigation.md	PDF 内のハイパーリンクのナビゲーション動作と外部リンクの処理を設定します。	「ハイパーリンク」、「外部リンク」、「URL ナビゲーション」、「クリック可能なリンク」、「URL」、「リンク」
thumbnail-navigation.md	サムネイルパネルでページのサムネイルを表示し、移動に使用します。	「サムネイル」、「ページのプレビュー」、「サムネイルパネル」、「サムネイル」、「ページプレビュー」

🔍 表示と操作

ファイル	目的	ユーザーから質問された場合のルーティング先
magnification.md	ズームレベル、ズームモード、拡大表示のコントロール（ページに合わせる、幅に合わせる）を設定します。	「ズーム」、「拡大表示」、「ページに合わせる」、「ズームレベル」、「ドキュメントの拡大縮小」
interaction-mode.md	選択モード（テキスト選択）とパンモード（タッチスクロール）を切り替えます。	「テキスト選択」、「パン」、「スクロールモード」、「操作モード」、「タッチナビゲーション」
text-selection.md	テキストの選択、コピー、テキスト選択イベントを有効にします。	「テキストを選択」、「テキストをコピー」、「コピーするテキストをハイライト」、「テキスト選択モード」
text-search.md	検索オプションとナビゲーションを備えたテキスト検索機能を実装します。	「テキストを検索」、「PDF 内を検索」、「検索機能」、「検索結果をハイライト」

🛠️ ツールバーとコンテキストメニュー

ツールバーの設定

ファイル	目的	ユーザーから質問された場合のルーティング先
toolbar-settings.md	ツールバーの表示、ツールチップの動作、ツールバー項目のカスタマイズ／削除を設定します。	「ツールバーをカスタマイズ」、「ツールバー項目を非表示」、「ツールバーボタンを削除」、「ツールバーの設定」
toolbar-methods.md	実行時にツールバーをプログラムから表示／非表示にし、ツールバー項目を有効／無効にします。	「ツールバーを動的に表示／非表示」、「ツールバーを切り替え」、「ツールバー項目をプログラムから有効／無効にする」

⚠️ ツールバー項目名の厳密な検証

ツールバー設定を作成する際は、誤ったツールバー項目名を使わないよう、必ず次のルールに従ってください。

1. toolbar-settings.md に記載された正確な項目名を必ず参照してください

   • ツールバー項目名を創作したり、推測したり、決めつけたりしないでください
   • 命名パターンから項目名を導き出さないでください
   • toolbar-settings.md の「Available Primary Toolbar Items」、「Available Annotation Toolbar Items」、「Available Form Designer Items」の各セクションに記載された名前のみを使用してください

2. 項目名を一文字ずつ検証してください

   • 大文字と小文字は区別されます：HighlightTool ≠ HighlightOption
   • 正確な名前のみを使用してください：AnnotationEditTool ≠ AnotatetionEditTool
   • 省略形や短縮形は使用しないでください

3. ツールバー設定コードを作成する前に、次の項目を確認してください

   • 参照ファイル toolbar-settings.md を開く
   • 「Available Primary Toolbar Items」セクションを確認する
   • 「Available Annotation Toolbar Items」セクションを確認する
   • 「Available Form Designer Items」セクションを確認する
   • 項目名をこれらのセクションからのみ正確にコピーする
   • 各項目名を一文字ずつすべて照合する
   • 参照先の各セクションにない項目名は、絶対に使用しない
   • 判断に迷ったら、toolbar-settings.md の「❌ COMMON MISTAKES TO AVOID」表を確認する

4. 防止すべきよくある間違い

   • ❌ AnotatetionEditTool → ✅ AnnotationEditTool（スペルミス）
   • ❌ CalibrationOption → ✅ CalibrateTool（サフィックスの誤り）
   • ❌ ShapeAnnotationOption → ✅ ShapeTool（注釈ツールバー版）
   • ❌ InkAnnotationOption → ✅ InkAnnotationTool（注釈ツールバー版）
   • 避けるべき間違いの完全な一覧は、toolbar-settings.md の「❌ COMMON MISTAKES TO AVOID」表を参照してください

コンテキストメニューのカスタマイズ

ファイル	用途	ユーザーからの問い合わせ内容に応じた案内先
contextmenu.md	コンテキストメニュー項目をカスタマイズし、コンテキストメニューのイベントを処理します。	「右クリックメニュー」、「コンテキストメニュー」、「カスタムコンテキストメニュー」、「コンテキストメニュー項目を無効にする」

📝 注釈

ファイル	用途	ユーザーからの問い合わせ内容に応じた案内先
annotation-settings.md	すべての注釈タイプの外観（色、不透明度、スタイル）と動作を設定します。	「注釈の色」、「注釈のスタイル」、「注釈の外観をカスタマイズ」、「注釈のデフォルト設定」
annotation-events.md	注釈のライフサイクルイベント（追加、削除、移動、サイズ変更、選択、プロパティ変更）を処理します。	「注釈イベント」、「注釈が追加されたとき」、「注釈の変更検出」、「注釈のコールバック」
shape-label-settings.md	図形注釈と計測注釈のラベル（位置、色、フォント、表示状態）をカスタマイズします。	「注釈ラベル」、「図形ラベル」、「計測ラベル」、「ラベルのカスタマイズ」
redaction-annotation.md	機密コンテンツを完全に削除するための墨消し注釈を作成、設定、適用します。	「墨消し」、「コンテンツを墨消しする」、「機密データを削除する」、「テキストを黒塗りする」、「完全な削除」

📄 フォーム

ファイル	用途	ユーザーからの問い合わせ内容に応じた案内先
form-field-settings.md	フォームフィールド（テキスト、チェックボックス、ラジオボタン、ドロップダウン、署名）のデフォルトプロパティを設定します。	「フォームフィールドのデフォルト設定」、「フォームフィールドのスタイル」、「フォームフィールドを設定する」、「フォームフィールドのプロパティ」
form-field-events.md	フォームフィールドの操作イベント（フォーカス、フォーカス解除、値の変更、検証）を処理します。	「フォームフィールドのイベント」、「フィールドが変更されたとき」、「フォーム検証イベント」、「フィールド操作のコールバック」

📋 ドキュメント操作

ファイル	目的	ユーザーが次の内容について質問した場合の参照先
download.md	カスタムファイル名でPDFをダウンロードする機能を有効化・設定します。	「PDFをダウンロード」「PDFを保存」「ドキュメントをエクスポート」「ダウンロードボタン」
print.md	PDFの印刷機能を設定して実行します。	「PDFを印刷」「ドキュメントを印刷」「印刷オプション」「印刷ボタン」
organize-pages.md	PDFページの並べ替え、回転、挿入、削除、コピー、インポート、抽出を行います。	「ページを並べ替え」「ページを回転」「空白ページを追加」「ページを削除」「ページを再配置」「PDFを結合」

⚙️ 高度な機能

ファイル	目的	ユーザーが次の内容について質問した場合の参照先
api-methods.md	プログラムによる制御：ドキュメントの読み込み、フォームの管理、注釈、テキストの抽出、元に戻す／やり直し、ナビゲーションAPI。	「プログラムからPDFを読み込む」「APIメソッド」「フォームデータをエクスポート」「テキストを抽出」「元に戻す／やり直し」「プログラムによる制御」
events.md	すべてのPDFViewerイベント（ドキュメントの読み込み、ダウンロード、注釈、フォーム、検索、ナビゲーション）の完全な一覧。	「イベント一覧」「すべてのイベント」「利用可能なイベント」「イベントリファレンス」「イベントハンドラー」

クイックスタートの例

import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
import './index.css';
import { 
  PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, 
  BookmarkView, ThumbnailView, Print, TextSelection, Annotation, TextSearch, 
  FormFields, FormDesigner, Inject 
} from '@syncfusion/ej2-react-pdfviewer';

function App() {
  return (
    <div>
      <div className='control-section'>
        <PdfViewerComponent
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
          style={{ 'height': '640px' }}>
          <Inject services={[ 
            Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, 
            BookmarkView, ThumbnailView, Print, TextSelection, TextSearch, 
            FormFields, FormDesigner 
          ]} />
        </PdfViewerComponent>
      </div>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

⚙️ 設定構成のベストプラクティス

設定（toolbarSettings、annotationSettings、annotationSelectorSettings、arrowSettings、rectangleSettingsなど）を使ったコードを生成する際は、不要なインポートや過剰な設計を避けるため、次のガイドラインに従ってください。

ルール 1：シンプルな設定 → コンポーネントのプロパティにインラインで定義

次の場合にこの方法を使用してください：

• 設定するプロパティが1～3個のみの場合
• 複雑な列挙型やカスタム型を使わず、設定がシンプルな場合
• TypeScriptの型付き定数が不要な場合

例（こちらを使用してください）：

<PdfViewerComponent
  id="container"
  documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
  annotationSelectorSettings={{
    selectionBorderColor: '#0000ff',
    selectionBorderThickness: 2,
    resizerBorderColor: '#ff0000',
    resizerFillColor: '#4070ff',
    resizerSize: 8,
  }}
  style={{ height: '640px' }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

メリット：

• ✅ 追加のインポートが不要です
• ✅ シンプルで読みやすくなります
• ✅ コードがすっきりします
• ✅ 型チェックも引き続き機能します

---

ルール 2：複雑な設定 → 型付き定数として定義（コンポーネントの外部）

次の場合にこの方法を使用してください：

• 設定するプロパティが4個以上、または関連する設定が複数ある場合
• 列挙型や複雑な設定を使用する場合
• 複数のコンポーネントで同じ設定を再利用する場合
• 設定が複雑で、個別に定義する価値がある場合

例（複雑なケースに限って使用してください）：

import { PdfViewerComponent, Inject, Annotation } from '@syncfusion/ej2-react-pdfviewer';
import type { AnnotationSelectorSettingsModel } from '@syncfusion/ej2-react-pdfviewer';
import { AnnotationResizerLocation, CursorType } from '@syncfusion/ej2-react-pdfviewer';

// Define constant OUTSIDE component with proper types and enums
const annotationSelectorConfig: AnnotationSelectorSettingsModel = {
  selectionBorderColor: '#0000ff',
  selectionBorderThickness: 2,
  resizerBorderColor: '#ff0000',
  resizerFillColor: '#4070ff',
  resizerSize: 8,
  resizerShape: 'Square',
  selectorLineDashArray: [5, 6],
  resizerLocation: AnnotationResizerLocation.Corners | AnnotationResizerLocation.Edges,
  resizerCursorType: CursorType.grab,
};

export function App() {
  return (
    <PdfViewerComponent
      id="container"
      documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
      annotationSelectorSettings={annotationSelectorConfig}
      style={{ height: '640px' }}
    >
      <Inject services={[Annotation]} />
    </PdfViewerComponent>
  );
}

型と列挙型をインポートする場合：

• TypeScriptの型チェックに type { SettingsNameModel } をインポートします
• 設定で使う列挙型をインポートします（例：AnnotationResizerLocation、CursorType）
• インポートは最小限にし、設定で使用するものだけをインポートします

メリット：

• ✅ 型安全な設定になります
• ✅ 列挙型を適切に使用できます
• ✅ 複数のコンポーネントで再利用できます
• ✅ コンポーネントのコードがすっきりします

---

ルール 3：シンプルなケースを過剰に設計しないでください

❌ これは避けてください（過剰な設計）：

import { PdfViewerComponent, Inject, Annotation } from '@syncfusion/ej2-react-pdfviewer';
import type { ToolbarSettingsModel } from '@syncfusion/ej2-react-pdfviewer';

// Unnecessary constant for 2 simple properties
const toolbarSettings: ToolbarSettingsModel = {
  showTooltip: true,
};

export function App() {
  return (
    <PdfViewerComponent
      toolbarSettings={toolbarSettings}
      // ... rest of props
    />
  );
}

✅ 代わりにこちらを使用してください（シンプルですっきり）：

<PdfViewerComponent
  toolbarSettings={{ showTooltip: true }}
  // ... rest of props
/>

---