注釈
注釈
Boxの注釈を使用すると、開発者はアプリケーションに埋め込まれたBoxプレビュー内から直接コラボレーション機能を提供できます。Boxの注釈は幅広いユースケースに対応するため、使用するとプレビューアーの注意を引いたり、ドキュメントや画像の特定の部分に関するフィードバックを提供したりできます。
Learn more about Content Preview現在、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 Elementsは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー(管理対象ユーザー)とBox以外のアカウントを持つユーザー(App User)のどちらにUI Elementsを使用するかどうかに関係なく、UI Elementsを使用するのに特別な設定は必要ありません。その理由は、UI Elementsは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。
Learn about selecting an authentication methodアプリケーションでエンドユーザーが注釈機能のサブセットだけにアクセスできるようにする必要がある場合は、ダウンスコープを使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、注釈を初期化するエンドユーザークライアントに安全に渡すことができます。
以下は、ダウンスコープと一緒に使用する、注釈固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Boxの注釈に対する機能を有効/無効にすることができます。詳細については、Box UI Elementsの専用スコープを参照してください。
パラメータとオプション
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 | Viewer-specific annotator configurations object | |
apiHost | Host for Box API calls for example https://app.box.com/api | |
fileId | Box file ID | |
token | A string auth token, see below for details on how to generate annotator tokens with appropriate scopes | |
container | DOM node or selector where Preview should be placed | |
file | File metadata object | |
file.id | String Box_File id | |
file.file_version.id | String Box_File_Version id | |
file.permissions | File permissions object, see below on how to scope permissions |
| オプション | デフォルト | 説明 |
|---|---|---|
modeButtons | Object containing a CSS selector and accessibility message for the annotation mode button, see parameters and options example above | |
isMobile | false | Whether the user's browser is on a mobile device |
hasTouch | false | Whether the mobile browser has touch enabled |
locale | en-US | Shared link URL |
基本スコープ
| スコープ名 | 付与される権限 |
|---|---|
base_preview | Allows preview access to a file or files in a folder based on user/file/token permissions |
機能のスコープ
| スコープ名 | 付与される権限 |
|---|---|
item_download | Allows files/folders contents to be downloaded |
annotation_view_self | Allows user to view their own annotations |
annotation_view_all | Allows user to view all annotations on the file |
annotation_edit | Allows user to edit their own annotations (includes 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の注釈とともに使用するプレビューインスタンスを設定する方法の詳細については、Box Content Previewを参照してください。
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 | Creates the dialog for the thread | |
show | Shows the annotation indicator | |
hide | Hides the annotation indicator | |
reset | Resets thread state to 'inactive' | |
showDialog | Shows the appropriate dialog for this thread | |
hideDialog | Hides the appropriate indicator for this thread | |
saveAnnotation | Saves an annotation locally and on the server | {string} 注釈の種類、{text} 保存する注釈のテキスト |
deleteAnnotation | Deletes an annotation | {string} 注釈ID、{boolean} サーバー上で削除するかどうか(デフォルトはtrue) |
スレッドのイベント
すべての注釈スレッドでは以下のイベントがトリガーされます。イベントデータには以下の内容が含まれます。
{
data: {
type: 'point', // Annotation type
threadID: '123abc',
userId: '456def',
threadNumber: '1' // Thread number from Annotations API
}
}
| イベント名 | 説明 |
|---|---|
annotationpending | An annotation thread was created but has not yet been saved on the server. |
annotationthreadsaved | An annotation thread was saved on the server. |
annotationthreaddeleted | An annotation thread was deleted on the server. |
annotationsaved | An annotation thread was added and saved to an existing annotation thread on the server |
annotationdeleted | An annotation thread was deleted from an existing thread on the server. The entire annotation thread is not deleted. |
annotationcanceled | An annotation thread was canceled from posting on either a new or existing thread. |
annotationdeleteerror | An error occurs while deleting an annotation on either a new or existing thread. |
annotationcreateerror | An error occurs while posting an annotation on either a new or existing thread. |
イベントの使用例については、上記の「イベント」セクションを参照してください。
注釈ダイアログ
ダイアログのメソッド
注釈ダイアログには、以下のメソッドを使用できます。
| メソッド名 | 説明 | メソッドのパラメータ |
|---|---|---|
show | Positions and shows the dialog | |
hide | Hides the dialog | |
hideMobileDialog | Hides and resets the shared mobile dialog | |
addAnnotation | Adds an annotation to the dialog | {Annotation} 追加する注釈 |
removeAnnotation | Removes an annotation from the dialog | {string} 注釈ID |
postAnnotation | Posts an annotation in the dialog | {string} 投稿する注釈テキスト |
position | Positions the dialog |
サポートされている注釈の種類
ポイント注釈は、ドキュメント形式と画像形式の両方でサポートされています。コメントのハイライト、ハイライトのみ、描画注釈はドキュメント形式でのみサポートされています。
サポートされているドキュメントのファイル拡張子: pdf、doc、docx、ppt、pptx、xlsx、xls、xlsm。
サポートされている画像のファイル拡張子: ai、bmp、dcm、eps、gif、png、ps、psd、svs、tga、tif、tiff。