注釈 - Box Dev Docs

Boxの注釈を使用すると、開発者はアプリケーションに埋め込まれたBoxプレビュー内から直接コラボレーション機能を提供できます。Boxの注釈は幅広いユースケースに対応するため、使用するとプレビューアーの注意を引いたり、ドキュメントや画像の特定の部分に関するフィードバックを提供したりできます。

コンテンツプレビューの詳細を確認する

現在、Box Content Previewは、コメントのハイライト、ハイライトのみ、描画、ポイント注釈という4種類の注釈をサポートしています。Boxの注釈は、現在、ドキュメントと画像のプレビューでのみサポートされています。Box Content Previewでサポートされるファイルタイプの詳細なリストについては、こちらで確認できます。

ブラウザのサポート

Box UI Elementのを確認してください。

使用方法

Boxの注釈は、NPMパッケージから取り込むと使用できます。

初期化

/* global BoxAnnotations */
const boxAnnotations = new BoxAnnotations();
const annotatorConf = boxAnnotations.determineAnnotator(
    options,
    disabledAnnotationTypes
);

// Construct and init annotator
const annotator = new annotatorConf.CONSTRUCTOR(options);

annotator.init(scale);

ここで、disabledAnnotationTypesは、無効にする有効な注釈の種類の文字列です。ビューアー固有の注釈の構成の詳細については、以下を参照してください。

認証

UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。

認証方法の選択について確認する

アプリケーションでエンドユーザーが注釈機能のサブセットだけにアクセスできるようにする必要がある場合は、を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、注釈を初期化するエンドユーザークライアントに安全に渡すことができます。以下は、ダウンスコープと一緒に使用する、注釈固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Boxの注釈に対する機能を有効/無効にすることができます。詳細については、を参照してください。

パラメータとオプション

const annotator = new annotatorConf.CONSTRUCTOR({
    annotator,
    apiHost,
    token,
    container,
    file: {
        id,
        file_version: {
            id
        },
        permissions
    },
    isMobile,
    hasTouch,
    locale,
    modeButtons: {
        // Annotation mode buttons, i.e. point, draw, etc
        point: {
          // Accessibilty message for the point annotation mode button
          title: "Point annotation mode",
          // CSS selector for the point annotation mode button
          selector: ".bp-btn-annotate-point"
        }
    }
});

パラメータ	デフォルト	説明
`annotator`		ビューアー固有の注釈構成オブジェクト
`apiHost`		Box APIコールのホスト (`https://app.box.com/api`など)
`fileId`		BoxファイルID
`token`		文字列認証トークン。適切なスコープを使用した注釈トークンの生成方法の詳細については、以下を参照してください。
`container`		プレビューが配置されるDOMノードまたはセレクタ
`file`		ファイルメタデータオブジェクト
`file.id`		文字列`Box_File` ID
`file.file_version.id`		文字列`Box_File_Version` ID
`file.permissions`		ファイル権限オブジェクト。権限のスコープを設定する方法については、以下を参照してください。

オプション	デフォルト	説明
`modeButtons`		注釈モードボタンのCSSセレクタとアクセシビリティメッセージを含むオブジェクト。上記のパラメータとオプションを参照してください。
`isMobile`	`false`	ユーザーのブラウザがモバイルデバイスにあるかどうか
`hasTouch`	`false`	モバイルブラウザがタッチ対応かどうか
`locale`	`en-US`	共有リンクのURL

基本スコープ

スコープ名	付与される権限
`base_preview`	ユーザー/ファイル/トークンの権限に基づいて、フォルダ内のファイルに対するプレビュー権限を許可します。

機能のスコープ

スコープ名	付与される権限
`item_download`	ファイル/フォルダのコンテンツのダウンロードを許可します。
`annotation_view_self`	ユーザーに自分の注釈の表示を許可します。
`annotation_view_all`	ユーザーにファイルに付いているすべての注釈の表示を許可します。
`annotation_edit`	ユーザーに自分の注釈の編集を許可します (`annotation_view_self`を含む)。

サンプルのシナリオ

シナリオ	スコープの組み合わせ
ユーザーが基本的なプレビュー機能と自分の注釈の編集機能を必要とする	`base_preview` + `annotation_edit`
ユーザーが基本的なプレビュー機能、自分の注釈の編集機能、およびドキュメントのテキストの選択機能を必要とする	`base_preview` + `annotation_edit` + `item_download`
ユーザーが基本的なプレビュー機能、すべての注釈の表示機能、および自分の注釈の編集機能を必要とする	`base_preview` + `annotation_view_all` + `annotation_edit`
ユーザーが基本的なプレビュー機能と自分の注釈のみを表示する機能を必要とする	`base_preview` + `annotation_view_self`

注釈の有効化/無効化と注釈の種類

注釈の種類は、プレビューオプションで選択して無効にすることができます。ビューアーオプションによって、そのビューアーに対してグローバルなshowAnnotationsの値が上書きされます。ここでBoxの注釈とともに使用するプレビューインスタンスを設定する方法の詳細については、を参照してください。

preview.show(..., {
    showAnnotations: Boolean
});

次と組み合わせます。

preview.show(..., {
    viewers: {
        VIEWER_NAME: {
            annotations: {
                enabled: Boolean,
                enabledTypes: String[] | null
            }
        }
    }
});

これにより、enabledがtrueに設定されている場合は、注釈が有効になります。空の場合はshowAnnotationsの値に従います。enabledTypesの値は、このビューアーに対して有効にする注釈の種類のリストです。空の場合は、その注釈者のデフォルトの種類に従います。

例

すべての注釈を有効にし、画像ビューアーに対してはオフにします。また、ドキュメントビューアーに対してはポイント注釈のみ有効にします。

preview.show(fileId, token, {
    showAnnotations: true,
    viewers: {
        Image: {
            annotations: {
                enabled: false
            }
        },
        Document: {
            annotations: {
                enabled: true,
                enabledTypes: ["point"]
            }
        }
    }
});

注釈者

注釈者の名前には、DocAnnotatorとImageAnnotatorのいずれかを指定することができます。boxAnnotations.getAnnotators()を呼び出すと、使用できる注釈のリストを取得できます。

その他のメソッド

annotator.init(): 注釈者を初期化します。
annotator.isModeAnnotatable(/* String */ type): 現在のビューアー/注釈者で現在の注釈モードが有効になっているかどうかを返します。
annotator.showModeAnnotateButton(/* String */ currentMode): 指定した注釈モードの注釈ボタンを示します。
annotator.getAnnotateButton(/* String */ annotatorSelector): 注釈ボタンの要素を取得します。
annotator.showAnnotations(): 保存されている注釈を取得して表示します。
annotator.hideAnnotations(): 注釈を非表示にします。
annotator.hideAnnotationsOnPage(/* number */ pageNum): 指定したページで注釈を非表示にします。
annotator.setScale(): 拡大/縮小倍率を設定します。
annotator.toggleAnnotationHandler(): 注釈モードのオンとオフを切り替えます。注釈モードがオンの場合は、その場所に注釈スレッドが作成されます。
annotator.disableAnnotationMode(/* String */ mode, /* HTMLElement */ buttonEl): 指定した注釈モードを無効にします。
annotator.enableAnnotationMode(/* String */ mode, /* HTMLElement */ buttonEl): 指定した注釈モードを有効にします。
annotator.getAnnotatedEl(/* HTMLElement */ containerEl): ビューアー内の注釈付きの要素を特定します。
annotator.createAnnotationThread(/* Annotation[] */ annotations, /* Object */ location, /* String */ [annotation type]): 適切な種類の注釈スレッドを作成し、インメモリのマップに追加して返します。

イベント

イベントは、addListenerを使用して注釈者オブジェクトにバインドし、removeListenerを使用して削除することができます。イベントリスナーはshowAnnotations()が呼び出される前にバインドする必要があります。そうしないと、イベントが見つからない可能性があります。

/* global BoxAnnotations */
const boxAnnotations = new BoxAnnotations();
const annotatorConf = boxAnnotations.determineAnnotator(
    options,
    disabledAnnotationTypes
);

// Construct and init annotator
const annotator = new annotatorConf.CONSTRUCTOR(options);
var listener = value => {
    // Do something with value
};

// Attach listener before calling show otherwise events can be missed
annotator.addListener(EVENTNAME, listener);

// Initialize a annotator
annotator.showAnnotations();

// Remove listener when appropriate
annotator.removeListener(EVENTNAME, listener);

EVENTNAMEには、以下のいずれかを指定できます。

annotatorイベントは、注釈者インスタンスが最初に使用可能になったときにトリガーされます。Boxの注釈により、loadの前にこのイベントがトリガーされるため、クライアントは、loadイベントがBox Content Previewからトリガーされる前にそのリスナーをアタッチできます。
annotationsfetchedイベントは、Box APIから注釈が取得されているときにトリガーされます。
annotationmodeenterイベントは、注釈モードに入るとトリガーされます。イベントデータには以下の内容が含まれます。

{
  // Annotation mode that was entered
  mode: 'point',
  // Optional CSS selector for the container's header
  headerSelector: '.bp-preview-header',
}

annotationmodeexitイベントは、注釈モードが終了するとトリガーされます。イベントデータには以下の内容が含まれます。

{
  // Annotation mode that was exited
  mode: 'point',
  // Optional CSS selector for the container's header
  headerSelector: '.bp-preview-header',
}

annotationerrorイベントは、注釈エラーが発生したときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  message: 'message', // Error message to show
}

annotationpendingイベントは、注釈スレッドが作成されたにもかかわらず、まだサーバーに保存されていない場合にトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationthreadsavedイベントは、注釈スレッドがサーバーに保存されたときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationthreaddeletedイベントは、注釈スレッドがサーバーで削除されたときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationsavedイベントは、注釈が追加され、サーバー上の既存の注釈スレッドに保存されたときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationdeletedイベントは、サーバー上の既存のスレッドから注釈が削除されたときにトリガーされます。注釈スレッド全体は削除されません。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationcanceledイベントは、新しいスレッドまたは既存のスレッドで注釈の投稿がキャンセルされたときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationdeleteerrorイベントは、新しいスレッドまたは既存のスレッドで注釈の削除中にエラーが発生したときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotationcreateerrorイベントは、新しいスレッドまたは既存のスレッドで注釈の投稿中にエラーが発生したときにトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

annotatorevent: 注釈者ごとに、一連の独自のイベントがトリガーされます。たとえば、画像の注釈者ではrotateやresizeなどがトリガーされるのに対し、別の注釈者では別の一連のイベントがトリガーされる場合があります。また、注釈者ラッパーは、以下を含むイベントデータとともに、Box Content Previewのプレビューレベルでイベントを再発行します。

{
  event: EVENTNAME,             // Event name
  data: DATA,                   // Event data object
  annotatorName: ANNOTATORNAME, // Name of the annotator
  fileVersionId: fileVersionId  // The file version id
  fileId: fileId                // The file id
}

イベントの使用例

preview.addListener("annotator", viewer => {
    annotator.addListener("annotationsfetched", () => {
        // Do something when annotations are fetched on a preview
    });
});

// Event listeners can be attached to viewers
preview.addListener("load", data => {
    var viewer = data.viewer;
    viewer.addListener("annotationsfetched", () => {
        // Do something when annotations are fetched on a preview
    });
});

// Event listeners can be attached to annotators
preview.addListener("load", data => {
    var annotator = data.viewer.annotator;
    annotator.addListener("annotationsfetched", () => {
        // Do something when annotations are fetched on a preview
    });
});

preview.addListener("annotatorevent", data => {
    if (data.event === "annotationsfetched") {
        // Do something when annotations are fetched on a preview
    } else if (data.event === "annotationerror") {
        // Do something different when an annotation error has occurred
    } else {
    }
});

preview.addListener("annotatorevent", data => {
    if (data.viewerName === "Image") {
        if (data.event === "annotationsfetched") {
            // Do something when annotations are fetched on an image preview
        }
    } else if (data.viewerName === "MultiImage") {
        if (data.event === "annotationsfetched") {
            // Do something different when annotations are fetched on a multi-page image
        }
    } else {
    }
});

preview.addListener("annotationsfetched", data => {
    if (data.viewerName === "Image") {
        // Do something when annotations are fetched on an image preview
    } else if (data.viewerName === "MultiImage") {
        // Do something different when annotations are fetched on a multi-page image
    } else {
    }
});

注釈スレッド

スレッドのメソッド

注釈スレッドには、以下のメソッドを使用できます。

メソッド名	説明	メソッドのパラメータ
`createDialog`	スレッドのダイアログボックスを作成します。
`show`	注釈インジケータを表示します。
`hide`	注釈インジケータを非表示にします。
`reset`	スレッドの状態を「inactive」にリセットします。
`showDialog`	このスレッドに適切なダイアログを表示します。
`hideDialog`	このスレッドに適切なダイアログを非表示にします。
`saveAnnotation`	注釈をローカルとサーバーに保存します。	注釈の種類、保存する注釈のテキスト
`deleteAnnotation`	注釈を削除します。	注釈ID、サーバー上で削除するかどうか (デフォルトはtrue)

スレッドのイベント

すべての注釈スレッドでは以下のイベントがトリガーされます。イベントデータには以下の内容が含まれます。

{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}

イベント名	説明
`annotationpending`	注釈スレッドは作成されましたが、まだサーバーに保存されていません。
`annotationthreadsaved`	注釈スレッドはサーバーに保存されました。
`annotationthreaddeleted`	注釈スレッドはサーバーで削除されました。
`annotationsaved`	注釈スレッドは追加され、サーバー上の既存の注釈スレッドに保存されました。
`annotationdeleted`	注釈スレッドはサーバー上の既存のスレッドから削除されました。注釈スレッド全体は削除されていません。
`annotationcanceled`	新しいスレッドまたは既存のスレッドで注釈スレッドの投稿がキャンセルされました。
`annotationdeleteerror`	新しいスレッドまたは既存のスレッドで注釈の削除中にエラーが発生しました。
`annotationcreateerror`	新しいスレッドまたは既存のスレッドで注釈の投稿中にエラーが発生しました。

イベントの使用例については、上記の「イベント」セクションを参照してください。

注釈ダイアログ

ダイアログのメソッド

注釈ダイアログには、以下のメソッドを使用できます。

メソッド名	説明	メソッドのパラメータ
`show`	ダイアログを配置して表示します。
`hide`	ダイアログを非表示にします。
`hideMobileDialog`	共有モバイルダイアログを非表示にしてリセットします。
`addAnnotation`	注釈をダイアログに追加します。	追加する注釈
`removeAnnotation`	注釈をダイアログから削除します。	注釈ID
`postAnnotation`	注釈をダイアログで投稿します。	投稿する注釈テキスト
`position`	ダイアログを配置します。

サポートされている注釈の種類

ポイント注釈は、ドキュメント形式と画像形式の両方でサポートされています。コメントのハイライト、ハイライトのみ、描画による注釈はドキュメント形式でのみサポートされています。サポートされているドキュメントのファイル拡張子: pdf、doc、docx、ppt、pptx、xlsx、xls、xlsm。サポートされている画像のファイル拡張子: ai、bmp、dcm、eps、gif、idml、indd、indt、inx``png、ps、psd、svs、tga、tif、tiff。

コンテンツプレビューの詳細を確認する

​ブラウザのサポート

​使用方法

​初期化

​認証

認証方法の選択について確認する

​パラメータとオプション

​基本スコープ

​機能のスコープ

​サンプルのシナリオ

​注釈の有効化/無効化と注釈の種類

​例

​注釈者

​その他のメソッド

​イベント

​イベントの使用例

​注釈スレッド

​スレッドのメソッド

​スレッドのイベント

​注釈ダイアログ

​ダイアログのメソッド

​サポートされている注釈の種類