Content Preview
Content Preview
Box Content Preview UI Elementを使用すると、開発者は、Boxファイルの高品質でインタラクティブなプレビューをデスクトップやモバイルウェブアプリに埋め込むことができます。ライブラリは、ファイルとその変換後のレプリゼンテーションに関する情報をBox APIを介して取得し、ファイルタイプに合ったビューアーを選択して、必要な静的アセットとファイルレプリゼンテーションを動的に読み込み、最後にファイルをレンダリングします。また、このUI Elementを使用すると、複数のファイルのプレビューを同じコンテナに読み込むことができ、ファイル間を移動するための矢印も表示されます。
このUI Elementによって、メインのBoxウェブアプリと「期限付きで埋め込まれた」Box APIエンドポイントでのプレビューが強化されます。
インストール
NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、こちらを参照してください。
認証
UI Elementsは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー(管理対象ユーザー)とBox以外のアカウントを持つユーザー(App User)のどちらにUI Elementsを使用するかどうかに関係なく、UI Elementsを使用するのに特別な設定は必要ありません。その理由は、UI Elementsは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。
Learn about selecting an authentication methodサポートされているファイルタイプ
Box Content Previewでは、ドキュメントと画像のほとんどの形式、HD動画、3Dモデル、360度画像、360度動画など、120以上のファイルタイプがサポートされています。サポートされているファイルタイプの完全なリストについては、こちらで確認できます。
デモ
ナビゲーション用の矢印を使用すると、さまざまなファイルタイプをプレビューできます。
API
const { Preview } = Box;
const preview = new Preview();
/**
* Shows a preview.
*
* @public
* @param {string} fileId - File ID to preview
* @param {string} accessToken - Box API access token
* @param {Object} [options] - Options
* @return {void}
*/
preview.show(fileId, accessToken, options);
/**
* Hides the preview.
*
* @return {void}
*/
preview.hide();
/**
* Prints the current file, if printable.
*
* @return {void}
*/
preview.print();
/**
* Downloads the current file.
*
* @return {void}
*/
preview.download();
/**
* Resizes the current preview, if applicable. This function only needs to
* be called when preview's viewport has changed while the window has not.
* If the window is resizing, then preview will automatically resize itself.
*
* @return {void}
*/
preview.resize();
/**
* Adds an event listener to the preview. Listeners should be added
* before calling show() so no events are missed.
*
* @param {string} eventName - Name of the event
* @param {Function} listener - Callback function
* @return {void}
*/
preview.addListener();
/**
* Removes an event listener from the preview.
*
* @param {string} eventName - Name of the event
* @param {Function} listener - Callback function
* @return {void}
*/
preview.removeListener(eventName, listener);
/**
* Removes all event listeners from the preview.
*
* @return {void}
*/
preview.removeAllListeners();
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
fileId | String | BoxファイルID。 |
accessToken | String | 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。 |
options | Object | 省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false}) を使用すると、削除オプションが非表示になります。 |
オプション
パラメータ | 型 | デフォルト | 説明 |
---|---|---|---|
container | String | document.body | CSS selector of the container in which Preview should be placed |
sharedLink | String | 共有リンクのURL。ファイルが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。 | |
sharedLinkPassword | String | 共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。 | |
collection | Array | プレビューするファイルIDのリスト。これを使用すると、同じコンテナ内にある複数のファイルのプレビューが表示され、ファイル間を移動するための矢印も表示されます。このリストにはFILE_ID を含める必要があること、およびSDKでは共有リンクまたはパスワードが必要なファイルのコレクションがサポートされないことに注意してください。 | |
header | String | light | Values that control header visibility and background color. Use none for no header, light for a light header and background, and dark for a dark header and background |
logoUrl | String | ヘッダーに表示するカスタムロゴのURL。この値が「box」という文字列の場合は、Boxのロゴが表示されます。 | |
showAnnotations | Boolean | false | Whether annotation button in header and annotations on content are shown |
showDownload | Boolean | false | Whether download button is shown in header. Will also control print button visibility in viewers that support print. Note that this option will not override download permissions on the access token. |
トークン生成関数
プレビューライブラリでは、オプションで、文字列トークンの代わりに、トークン生成関数を使用できます。トークン生成関数を使用すると、プレビューで使用するトークンを動的に決定できます。たとえば、ファイルごとに異なるアクセストークンを渡したり、プレビューを表示する前にトークンが更新されて有効であることを確認したりできます。トークン生成関数ではPromiseが返され、プレビューされるすべてのファイルに適用される単一の文字列トークンか、これらのファイルのアクセストークンへの指定のファイルIDのマップに解決されます。
// Example token generator function that resolves to a single access token
var singleTokenGenerator = function() {
return someApi.getToken().then(function(data) {
return data.token;
});
};
// Example token generator function that resolves to a map of tokens
var mapTokenGenerator = function() {
return Promise.resolve({
file_1234: "some_token_abcd",
file_2345: "some_token_bcde"
});
};
イベント
プレビューオブジェクトは、イベントにバインドするためのaddListener
とremoveListener
を公開します。イベントリスナーはshow()
が呼び出される前にバインドする必要があります。そうしないと、イベントが見つからない可能性があります。
const listener = (value) => {
// Do something with value
};
// Attach listener before calling show otherwise events can be missed
var preview = new Box.Preview();
preview.addListener(EVENTNAME, listener);
// Show a preview
preview.show(...);
// Remove listener when needed
preview.removeListener(EVENTNAME, listener);
EVENTNAME
には、以下のいずれかを指定できます。
viewer
イベントは、ビューアーインスタンスが最初に使用可能になったときにトリガーされます。これは、load
イベントにも含まれているプロパティと同じオブジェクトです。プレビューでは、load
の前にこのイベントがトリガーされるため、クライアントは、load
イベントがトリガーされる前にそのリスナーをアタッチできます。load
イベントは、show()
が呼び出されたときかプレビュー間の移動が発生したときに、プレビューが読み込まれるたびにトリガーされます。イベントデータには以下の内容が含まれます。
error: 'message', // Error message if any error occurred while loading
viewer: {...}, // Instance of the current viewer object if no error occurred
metrics: {...}, // Performance metrics
file: {...} // Box file object with properties defined in file.js
navigate
イベントは、移動が発生したときにトリガーされます。イベントには移動先のファイルのファイルIDが含まれており、このイベントはload
の前にトリガーされます。notification
イベントは、プレビューラッパーまたはいずれかのビューアーで警告や致命的ではないエラーなどの通知を表示する場合にトリガーされます。イベントデータには以下の内容が含まれます。
message: 'message', // Message to show
type: 'warning' // 'warning', 'notice', or 'error'
viewerevent
: ビューアーごとに、一連の独自のイベントがトリガーされます。たとえば、画像ビューアーではrotate
やresize
などがトリガーされるのに対し、別のビューアーでは別の一連のイベントがトリガーされる場合があります。プレビューラッパーは、以下を含むイベントデータとともに、プレビューレベルでイベントを再発行します。
event: EVENTNAME, // Event name
data: DATA, // Event data object
viewerName: VIEWERNAME, // Name of the viewer. See VIEWERNAME above
fileId: fileId // The file ID
イベントの使用例
var preview = new Box.Preview();
preview.addListener("viewer", viewer => {
viewer.addListener("rotate", () => {
// Do something when a viewer rotates a preview
});
});
preview.addListener("load", data => {
const viewer = data.viewer;
viewer.addListener("rotate", () => {
// Do something when a viewer rotates a preview
});
});
preview.addListener("viewerevent", data => {
if (data.viewerName === "Image") {
if (data.event === "rotate") {
// Do something when an image preview is rotated
}
} else if (data.viewerName === "Image360") {
if (data.event === "rotate") {
// Do something different when a 360-degree image is rotated
}
} else {
}
});
preview.addListener("rotate", data => {
if (data.viewerName === "Image") {
// Do something when an image preview is rotated
} else if (data.viewerName === "Image360") {
// Do something different when a 360-degree image is rotated
} else {
}
});
スコープ
アプリケーションで、エンドユーザーがContent Explorer機能のサブセットのみにアクセスできるようにする必要がある場合は、ダウンスコープを使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、Content Explorerを初期化するエンドユーザークライアントに安全に渡すことができます。
以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Content ExplorerのUIコントロールを有効/無効にすることができます。詳細については、Box UI Elementsの専用スコープを参照してください。
基本スコープ
スコープ名 | 付与される権限 |
---|---|
base_preview | ファイルのプレビューのみをユーザーに許可します。 |
機能のスコープ
スコープ名 | 付与される権限 |
---|---|
item_download | Allows downloading/printing the content from the generated preview |
annotation_edit | Allow user to edit annotations (delete). Note: For highlight annotations to work, the text layer on the document needs to be enabled for the user. Text layer is disabled for all users that don't have download permissions on the file. To enable highlight annotations for a user, please ensure they have download permissions on the file. |
annotation_view_all | Allows user to view all users' annotations. |
annotation_view_self | Allows user to view their own annotations only. |
サンプルのシナリオ
シナリオ | スコープ |
---|---|
ユーザーがプレビューのみできるようにする(ダウンロード/印刷、注釈は不可) | base_preview |
User should be able to preview, download and print | base_preview + item_download |
ユーザーがプレビュー、すべての注釈の表示を実行できるようにする(注釈のダウンロード、印刷、作成は不可) | base_preview + annotation_view_all |
ユーザーがプレビュー、注釈の作成(表示できるのは自分の注釈のみ)を実行できるようにする | base_preview + annotation_view_self + annotation_edit |
ユーザーがプレビュー、注釈の編集、すべての注釈の表示を実行できるようにする | base_preview + annotation_view_all + annotation_edit |
ユーザーがプレビュー、自分の注釈の表示のみ(追加/削除は不可)を実行できるようにする(例: レビュー期間が終了したら、すべてのドキュメントを読み取り専用モードで保存する必要がある場合) | base_preview + annotation_view_self |