Box Content Picker UI Elementを使用すると、開発者は、デスクトップまたはモバイル ウェブアプリでBoxからファイルやフォルダを選択するためのサポートを追加できます。ライブラリは、指定されたフォルダに関する情報をBox APIを介して取得し、そのコンテンツをフォルダビューにレンダリングします。ユーザーはファイルまたはフォルダを選択でき、その後、このコンテンツ情報がアプリケーションの別の部分に渡されます。
NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、こちら を参照してください。
UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。
認証方法の選択について確認する
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8" />
<title>Box File Selection</title>
<!-- Latest version of the picker css for your locale -->
<link
rel="stylesheet"
href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.css"
/>
</head>
<body>
<div class="container" style="height:600px"></div>
<!-- Latest version of the picker js for your locale -->
<script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.js"></script>
<script>
var folderId = "123";
var accessToken = "abc";
var filePicker = new Box.FilePicker();
filePicker.show(folderId, accessToken, {
container: ".container"
});
</script>
</body>
</html>
上記のデモは、有効なアクセストークンを指定しなければ、完全に動作しない可能性があります。テスト目的の場合は、一時的な開発者トークンを使用できます。このトークンは、デモにある [JS] タブで更新する必要があります。
const { FilePicker } = Box;
const filePicker = new FilePicker();
/**
* Shows the file selection.
*
* @public
* @param {String} folderId - The root folder id.
* @param {String} accessToken - The API access token.
* @param {Object|void} [options] - Optional options.
* @return {void}
*/
filePicker.show(folderId, accessToken, options);
/**
* Hides the file picker, removes all event listeners, and clears out the HTML.
*
* @public
* @return {void}
*/
filePicker.hide();
/**
* Clears out the internal in-memory cache for the file picker. This forces
* items to be reloaded from the API.
*
* @public
* @return {void}
*/
filePicker.clearCache();
/**
* Adds an event listener to the file picker. Listeners should be added before
* calling show() so no events are missed.
*
* @public
* @param {String} eventName - Name of the event.
* @param {Function} listener - Callback function.
* @return {void}
*/
filePicker.addListener(eventName, listener);
/**
* Removes an event listener from the file picker.
*
* @public
* @param {String} eventName - Name of the event.
* @param {Function} listener - Callback function.
* @return {void}
*/
filePicker.removeListener(eventName, listener);
/**
* Removes all event listeners from the file picker.
*
* @public
* @return {void}
*/
filePicker.removeAllListeners();
パラメータ 型 説明 folderIdString BoxフォルダのID。選択しようとしているコンテンツが含まれるフォルダのIDです。Boxの [すべてのファイル] フォルダを使用する場合は、folderIdとして0を使用します。 accessTokenString 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。 optionsObject 省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})を使用すると、削除オプションが非表示になります。
パラメータ 型 デフォルト 説明 containerStringdocument.bodyContent Pickerが配置されるコンテナのCSSセレクタ。hide() を呼び出すと、このコンテナは空になります。 sortByStringnameコンテンツリストの最初の並べ替え基準オプション。値は名前またはdateになります。 sortDirectionStringASCコンテンツリストの最初の並べ替え方向オプション。値はASCまたはDESCになります。 logoUrlStringヘッダーに表示するカスタムロゴのURL。この値が「box」という文字列の場合は、Boxのロゴが表示されます。 extensionsArray<string>[]選択対象として許可するファイル拡張子の配列 (例: ['doc', 'ppt'])。ファイル選択機能のみに適用され、フォルダ選択機能には適用されません。拡張子が指定されている場合は、その拡張子のみを選択できます。空の配列の場合は、すべてのファイル拡張子が選択対象として許可されることを示します。 maxSelectableNumberInfinity選択可能なファイルまたはフォルダの数。ファイルまたはフォルダが1つだけ選択されるようにする場合は1を指定します。 canUploadBooleantrueこれをfalseに設定すると、アップロードオプションが非表示になります。このオプションを非表示にするだけではアップロードを防ぐことはできず、現在のフォルダに対する権限でもcan_uploadをfalseに設定する必要があります。フォルダに対する権限can_uploadがfalseに設定されている場合、このオプションによる効果はありません。 canSetShareAccessBooleantruefalseに設定すると、共有ドロップダウン選択が非表示になります。この選択のドロップダウンを非表示にするだけでは共有権限の変更を防ぐことはできず、フォルダ項目に対する権限でもcan_set_share_accessをfalseに設定する必要があります。フォルダ項目に対する権限can_set_share_accessがfalseに設定されている場合、このオプションによる効果はありません。canCreateNewFolderBooleantrueフォルダの新規作成オプションが非表示になります。このオプションを非表示にするだけではフォルダの新規作成を防ぐことはできず、フォルダ項目に対する権限でもcan_uploadをfalseに設定する必要があります。フォルダ項目に対する権限can_uploadがfalseに設定されている場合、このオプションによる効果はありません。 sharedLinkString共有リンクのURL。フォルダが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。 sharedLinkPasswordString共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。 modalObjectウィンドウ属性を指定すると、Content Pickerは所定の位置に作成されません。代わりに、コンテナ内にボタンが作成され、そのボタンをクリックすると、ウィンドウポップアップでContent Pickerが起動します。 sizeStringundefinedContent Pickerが、幅がsmallまたはlargeのコンテナに合わせて表示されるように示します。値には空白か、smallまたはlargeを指定できます。空白にした場合、UI Elementはそのコンテナに合わせて調整され、自動でsmallの幅とlargeの幅が切り替わります。 isTouchBoolean デフォルトでは、ブラウザとデバイスのデフォルトのタッチサポートが設定されます。 コンテンツエクスプローラがタッチ対応デバイスにレンダリングされることを示します。 autoFocusBooleanfalsetrueに設定すると、初回読み込み時に項目グリッドに焦点が当てられます。defaultViewString files値はfilesまたはrecentsになります。recentsに設定すると、デフォルトで、通常のファイル/フォルダ構造ではなく最近使用した項目が表示されます。 chooseButtonLabelString[選択] ボタンのラベルに置き換わる文字列 cancelButtonLabelString[キャンセル] ボタンのラベルに置き換わる文字列 requestInterceptorFunctionリクエストをインターセプトする関数。例については、このCodePen を参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチ に従っています。 responseInterceptorFunctionレスポンスをインターセプトする関数。例については、このCodePen を参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチ に従っています。
パラメータ 型 デフォルト 説明 buttonLabelStringボタンのラベル buttonClassNameStringBoxの青いボタン ボタンを装飾するためのCSSクラス modalClassNameStringウィンドウポップアップコンテンツを装飾するためのCSSクラス overlayClassNameStringウィンドウ ポップアップオーバーレイを装飾するためのCSSクラス
イベント名 イベントデータ 説明 chooseArray<File | Web Link | Folder>[選択] ボタンが押されたときに発生します。イベントデータは、ファイルの選択とフォルダの選択のどちらであるかに応じて、フォルダオブジェクト、ファイルオブジェクト、またはウェブリンクオブジェクトの配列になります。 cancel[キャンセル] ボタンが押されたときに発生します。
クリックによって手動で、またはJavaScriptや上記のautoFocusプロパティによってプログラムで項目グリッドがフォーカスされていると、以下のキーボードショットカットが機能します (対応する操作が適切で許可されている場合)。
キー 動作 Arrow Up前の項目行 Arrow Down次の項目行 Ctrl/Cmd + Arrow Up最初の項目行 Ctrl/Cmd + Arrow Down最後の項目行 /検索 Shift + X項目行を選択 Enter選択した項目を開く g then fルートフォルダに移動 g then u現在のフォルダにアップロード g then bルートフォルダの階層リンクをフォーカス g then s選択した項目を表示 g then xキャンセル g then c選択 g then r最近使用した項目
アプリケーションで、エンドユーザーがContent Picker機能のサブセットのみにアクセスできるようにする必要がある場合は、ダウンスコープ を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、Content Pickerを初期化するエンドユーザークライアントに安全に渡すことができます。
以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Content PickerのUIコントロールを有効/無効にすることができます。詳細については、Box UI Elementsの専用スコープ を参照してください。
スコープ名 付与される権限 base_pickerユーザー/ファイル/トークンの権限に 基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。
スコープ名 付与される権限 item_shareトークン交換リクエストの「resource」で指定されたリソースの共有を許可します。 item_uploadContent Pickerでのアップロードを許可します。
シナリオ スコープ ユーザーが単にフォルダ構造内を移動してファイル/フォルダを選択する base_pickerユーザーがフォルダ構造内を移動して、ファイル/フォルダを選択し、アクセスレベルも設定する base_picker + item_shareユーザーがフォルダ構造内を移動して、ファイル/フォルダを選択し、ファイル/フォルダもアップロードする base_picker + item_uploadユーザーがフォルダ構造内を移動して、ファイル/フォルダを選択し、ファイル/フォルダをアップロードして、ファイル/フォルダのアクセスレベルも設定する base_picker + item_share + item_upload
