このガイドでは、JavaScript による PDF アノテーションと、それをプロジェクトに追加する方法について説明します。

この記事は、Part 1 の続きとなります。Part 1 の記事はこちら。

ユースケース

アノテーションが何であるかはお判りいただけましたでしょうか？それでは、実際にはどのように実装するのでしょうか？様々な方法がありますが、26 種類の標準タイプを全て提供できるものは限られています。PDFTron SDK は全ての標準アノテーションに加え、9 種類の追加アノテーション、そしてカスタム アノテーションをサポートしています。

WebViewer では、ユーザーがアノテーション ツールバーを使って、UI に直接アノテーションを追加することができます。また、クライアント アプリケーションで直接透かしを追加するコードを使用して、プログラム的に PDF にアノテーションを追加することもできます。

他にも、以下のような使用例があります。

スレッド形式の会話

アノテーションを使用すると、コンテンツ上でリアルタイムのコラボレーションやディスカッションを行うことができます。WebViewer では、コメントによるスレッド形式の会話を追加したり、任意のアノテーションのコメントに返信したりすることができます。

多くの PDF ビューアーは、単一のメモやコメントを追加しますが、これはレビューや会話のための乱雑な形式です。たとえば、コピー エディターが特定の段落にコメントを残したとしても、著者がその場ですぐに見たり返信したりすることはできません。複数のコメントがページ上に散らばっていると、会話の流れを把握するのはほぼ不可能です。

しかし、スレッド化された会話では、編集者がコメントを追加し、他の人がそれに直接返信することで、連鎖的な議論を行うことができます。これにより、コメントや返信が整理され、見やすく、見つけやすくなり、返信も簡単になります。

ドキュメント レビューの詳細とサンプルコードについては、こちらをご覧ください:

• JavaScriptドキュメント連携ライブラリ
• JavaScript PDF Viewer におけるメンションを用いたドキュメント連携
• アノテーション ステータス

計測

CAD や BIM プログラムからエクスポートされた PDF 図面では、建設やエンジニアリングのワークフローで計測が一般的に使用されています。計測ツール付きのアノテーションを使用すると、JavaScript を使用して、ブラウザーやアプリでエンジニアリング図面の面積寸法を計算したり、線間を測定したり、周囲をトレースしたりすることができます。また、アプリケーションに計測ツールを追加して、施工図の面積、距離、周囲長を計測することもできます。

詳細とサンプルコードについては、こちらをご覧ください:

• PDFTron WebViewer デモにおける計測ツールのアノテーション
• JavaScript PDF 計測ライブラリ

スタンプの追加

実際の書類にゴム印を押すように、PDF のスタンプはドキュメントの状態 (承認、拒否、無効など) を示します。WebViewer では、スタンプの作成者、作成日時などのカスタム テキストを動的に作成することができます。

電子署名

電子署名を使用して、レビューしたドキュメントを承認することもできます。これは、ドキュメントに簡単なビジュアル署名を追加するものです。視覚的に識別可能な自筆の署名で、エクスポートしてデータベースに保存することができます。

電子署名の詳細については、こちらをご覧ください:

• 署名欄の追加

注意: 電子署名は、画像、手書き、写真、入力されたテキストとして作成されます。電子署名は、より複雑で、認証局 (自己署名または第三者) によるデジタル ID または証明書を必要とするデジタル署名ではありません。

デジタル署名の詳細については、こちらをご覧ください:

• JavaScript デジタル署名のデモ
• JavaScript PDF デジタル署名ライブラリ
• GitHub: PDFTron 署名アプリ

アノテーションの追加: UI vs プログラム

実装後は、UI から、またはプログラムからの 2 つの方法で PDF の JavaScript アノテーションを追加することができます。

UI ベース

このアプローチでは、ユーザーはビューアー インターフェースのツールでアノテーションにアクセスします。

PDFTron は、墨消しや透かしを含むすべてのアノテーションをブラウザー クライアントで追加するため、データはサードパーティ サーバーに送信されず、情報はブラウザー環境から外れることはありません。サーバーやネットワーク リソースへの依存度が低いため、ユーザーにとってより信頼性の高い、拡張性の高いソリューションとなります。

プログラムから

コードによって自動的にアノテーションを適用することも可能です。これには、機密ドキュメントに透かしを追加することも含まれます。

• カスタム アノテーション: PDF プログラムの中には、個人のロゴを適用したり、テキストをクリック可能なリンクに変換したりするものがあります。

PDFTron の WebViewer は、プログラムでアノテーションを操作したりカスタマイズしたりするための多くの API を提供しています。詳細については、ビューアーのカスタム アノテーションの作成を参照してください。

• 自動化ワークフロー: 政府機関や金融機関では、自動化ソフトウェアを使用して、電子ドキュメントにプログラムでスタンプを押したり、タイム スタンプを挿入したりしています。

JavaScript でアノテーションを追加する

JavaScript で PDF のアノテーションを組み込むには、独自のソリューションを構築する方法と、既存のライブラリを使用する方法の 2 つがあります。

JavaScript のソリューションを作成する

独自のソリューションを作成することで、より多くの制御を行うことができます。しかし、多くの作業と、細かい点の理解が必要です。PDF の仕様に慎重に準拠し、エッジ ケースを処理し、広く使われている他の PDF リーダーで確実にアノテーションが動作するようにし、アノテーションを保存するための PDF 仕様標準の XFDF 形式と相互運用する必要があります。

既存のソリューションの利用する

カスタム アノテーション、フォーム入力、署名機能のサポートを構築するには、プロセス全体を理解する必要がありますが、これは商用 SDK の UI 内で自動的に処理されます。

例えば、PDFTron SDK は評価版であってもアノテーションをサポートしており、ユーザーは WebViewer で直接アノテーションを処理することができます。

WebViewer は、プロフェッショナルな PDF および Office ビューアー コンポーネントで簡単にアノテーションを追加するためのいくつかの API を公開しています。その後、ツールバー リボンで好みのアノテーションやツール グループをカスタマイズしたり、既存のエクスペリエンスや UI の中で、プログラム的に、そしてヘッドレスで独自のアノテーションを追加したりすることができます。また、WebViewer は、すべての主要な JavaScript フレームワークで動作するため、プロジェクトに簡単に組み込むことができます。

WebViewer は、カスタム アノテーション タイプのサポートなど、PDF の仕様で提供されているもの以外にもサポートを追加しています。

アノテーション用の WebViewer のインストール

WebViewer のインストールには様々な方法がありますが、ここでは NPM を使用します。

アノテーション用の WebViewer を使用するには、バージョン 8.0+ を NPM 経由でダウンロードし、インストールします。(以下の例はすべてバージョン 8.0+ のものです)

WebViewer は静的リソースを提供する必要があるため (バンドル不可)、静的ファイルを手動で dist ディレクトリにコピーする追加の手順があります。

前提条件

まず、Node と NPM をインストールします。

WebViewer は Node、NPM、node_modules を必要としません。サンプルを実行するために推奨されます。

NPM 経由でインストール

プロジェクトで以下のコマンドを実行します。

npm i @pdftron/webviewer

JavaScript のメイン エントリポイントをインストールし、WebViewer の動作に必要な静的アセットをダウンロードします。

静的アセットのコピー

次に、WebViewer の実行に必要な静的アセットを HTTP/HTTPS で提供されるパブリックな場所 (通常は dist または build フォルダ) にコピーします。静的ファイルの場所は、以下の通りです。

node_modules/@pdftron/webviewer/public

package.json に、ビルド完了後に静的ファイルを移動させるスクリプトを追加することができます。

これは、ビルドが完了した後に、すべての必要なファイルを dist/public フォルダにコピーします。

{
  "scripts": {
    "move-static": "cp -a ./node_modules/@pdftron/webviewer/public/. ./dist/public/webviewer",
    "build": "mybuildscript && npm run move-static"
  }
}

使用方法

WebViewer をコードで使用する場合、path パラメーターを使用して、静的ファイルをコピーした場所を指定する必要があります。

例えば、静的ファイルを dist/public/webviewer にコピーした場合、以下のようなコードになります。

import WebViewer from '@pdftron/webviewer'
 
WebViewer({
  path: '/public/webviewer',
}, document.getElementById('viewer'))
  .then(instance => {
    const { UI, Core } = instance;
    const { documentViewer, annotationManager, Tools, Annotations } = Core;
    // call methods from UI, Core, documentViewer and annotationManager as needed
 
    documentViewer.addEventListener('documentLoaded', () => {
      // call methods relating to the loaded document
    });
 
    instance.UI.loadDocument('http://fileserver/documents/test.pdf');
  })

次のステップについては、NPM を介した WebViewer の統合をご覧ください。

PDFTron アノテーションを統合する

PDFTron SDK は、UI のツールバーを使用して、またはアノテーション タイプのコードを書くことによってプログラム的に、すぐにアノテーションを提供します。

コードを書くときは、ドキュメントがロードされた後にアノテーションを追加してください。例えば、ドキュメントがロードされた直後に追加するには、documentLoaded イベントを使用します。

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;

    documentViewer.addEventListener('documentLoaded', () => {
      // create annotation here
    });
  });

アノテーション タイプのプロパティと関数は、アノテーション API のドキュメントで確認できます。

詳細とサンプルへのリンクは、Create Annotations Programmatically のページをご覧ください。

使用例

アノテーションの権限設定、アノテーションの追加または編集、描画アノテーションの作成には、次の例を使用します。詳しくは、JavaScriptのアノテーション コード サンプルをご覧ください。

アノテーションのアクセス権を設定する

アノテーションのアクセス権限は柔軟にカスタマイズできます。WebViewerは、誰がどのアノテーションを変更するかを制御するために、クライアントサイドのユーザー権限をサポートしています。デフォルトでは、ユーザーは自分が作成したアノテーションのみを変更できますが、これをカスタマイズすることができます。アクセス権限は以下の通りです。

• 管理者: あらゆるアノテーションの作成/返信/編集/削除が完全に許可されます。
• ユーザー: あらゆるアノテーションの作成/返信が可能、自分のアノテーションの編集/削除のみ可能です。
• 閲覧のみ: アノテーションの作成/返信/編集/削除はできません。

AnnotationManager の setPermissionCheckCallback 関数を使用して、独自のロジックを定義します。

この関数は、定義したコールバック関数を受け取り、現在のユーザーにアノテーションを修正する許可を与えた場合は true を返し、そうでない場合は false を返します。

WebViewer(...)
  .then(instance => {
    const { annotationManager } = instance.Core;
 
    annotationManager.setPermissionCheckCallback((author, annotation) => {
      // the default permission check that is used
      // you can combine this with your own custom checks
      const defaultPermission = annotation.Author === annotationManager.getCurrentUser();
      // any annotation with 50% opacity will also be editable regardless of the author
      const customPermission = annotation.Opacity === 0.5;
 
      return defaultPermission || customPermission;
    });
  });

PDF アノテーションの追加と編集

以下のサンプル コードは、PDFTron SDK の JavaScript PDF アノテーション ライブラリを使用してアノテーションを追加または編集するものです。サンプル アノテーションの種類は、ハイパーリンク、ドキュメント内リンク、スタンプ、ゴム印、ファイル添付、音声、テキスト、フリーテキスト、線分、円、四角形、多角形、折れ線、ハイライト、波線、キャレット、インクがあります。

JavaScript PDF ライブラリと PDF アノテーション ライブラリについて詳しくはこちら。

図形のアノテーションを作成する

この例を使用して、長方形の JavaScript PDF アノテーションを作成します。他のタイプのアノテーションを作成することも同様です。

WebViewer(...)
  .then(instance => {
    const { Annotations, annotationManager, documentViewer } = instance.Core;
 
    documentViewer.addEventListener('documentLoaded', () => {
      const rectangleAnnot = new Annotations.RectangleAnnotation();
      rectangleAnnot.PageNumber = 1;
      // values are in page coordinates with (0, 0) in the top left
      rectangleAnnot.X = 100;
      rectangleAnnot.Y = 150;
      rectangleAnnot.Width = 200;
      rectangleAnnot.Height = 50;
      rectangleAnnot.Author = annotationManager.getCurrentUser();
 
      annotationManager.addAnnotation(rectangleAnnot);
      // need to draw the annotation otherwise it won't show up until the page is refreshed
      annotationManager.redrawAnnotation(rectangleAnnot);
    })
  })

アノテーションのインポートとエクスポート

アノテーションの保存と読み込みに XFDF ファイルを使用するのも 1 つの方法です。AJAX リクエストを使用してサーバーから XFDF 文字列を保存および読み込み、XFDF ファイルを書き込みおよび読み込むようにサーバーをセットアップすることができます。

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager } = instance.Core;
 
    documentViewer.setDocumentXFDFRetriever(async () => {
      // load the annotation data
      const response = await fetch('path/to/annotation/server');
      const xfdfString = await response.text();
 
      // 
      // 
      // 
      // 
      // 
      return xfdfString;
    });
 
    // later save the annotation data
    // widgets and links will remain in the document without changing so it isn't necessary to export them
    annotationManager.exportAnnotations({ links: false, widgets: false }).then(xfdfString => {
      fetch('path/to/annotation/server', {
        method: 'POST',
        body: xfdfString // written into an XFDF file in server
      });
      // Full samples are available at the end of this section.
    })
  })

詳しくは、アノテーションのインポートとエクスポートを参照してください。

関連リソース

PDF アノテーションの詳細については、以下のリソースを参照してください:

• PDFTron アノテーション機能
• JavaScript PDF アノテーション ライブラリ
• アノテーションのインポートとエクスポート
• アノテーションのリアルタイム同期
• アノテーションの権限
• ドキュメント ステータスのアノテーション
• アノテーションのフラット化

まとめ

この記事では、以下の項目についても説明しました。

• アプリケーションにおけるアノテーションのユースケース
• PDFTron のアノテーションを使用して、JavaScript で PDF にアノテーションする方法
• アノテーションの作成と追加例

本製品に関するご質問、ご不明な点はエクセルソフトまでお気軽にお問い合わせください。

PDFTron 製品の詳細は、弊社 Web サイトをご確認ください。

記事参照：
© 2022 PDFTron
「A Comprehensive Guide to PDF Annotations with JavaScript」