バージョン

クライアント側イベントの使用 (igUpload)

igUpload コントロールは、多数のイベントを備えた豊富なクライアント側 API を公開します。7 種類の異なるクライアント側イベントがあり、これらは、ユーザーがコントロールを操作しているとき、またはアップロードの処理中に発生します。

このトピックでは、基本的な jQuery バージョンおよび Ignite UI for MVC Upload を使用して、クライアント側イベント ハンドラーを igUpload にアタッチする方法を説明します。さらに、このドキュメントでは、関連するイベント引数の詳細と各イベントを記述する方法についても説明します。

jQuery でのクライアント側イベントへのアタッチ

基本的な igUpload jQuery ウィジェットを使用する場合、イベントに対するハンドラーは、jQuery UI オプションと同様に定義します。

たとえば、このドキュメントのクライアント イベントのセクションで説明する fileSelecting イベントを考えてみます。イベントの名前をキーとして使用し、その値は、ロジックを実装するハンドラーである必要があります。

jQuery の場合:

$(window).load(function () {
    $("#igUpload1").igUpload({
        autostartupload: true,
        fileSelecting: function (e, args) {
        }
    });
});

Ignite UI for MVC を使用したクライアント側イベントへのアタッチ

デフォルトで、Ignite UI for MVC は、ラッパー構文のコンテキストでのイベント ハンドラーの定義をサポートしていません。jQuery を使用して、イベント バインドをもう一度設定します。

  1. 最初に、Ignite UI for MVC Upload のインスタンスを作成します。

    ASPX の場合:

    <%= Html.Infragistics().Upload()
    .ID("igUpload1")
    .AutoStartUpload(true)
    .ProgressUrl("/IGUploadStatusHandler.ashx")
    .Render()
%>

  2. 次に、jQuery bind() 関数を使用して、イベント ハンドラーをイベントに関連付けます。

    jQuery の場合:

    $(window).load(function () {
    $("#igUpload1").bind({ iguploadfileselecting: function (e, args) {    }});});

    注: ここで、イベントの名前はコントロール名とイベント名の組み合わせです。これは、ハンドラーをイベントにアタッチする際の jQuery UI の規則です。詳細については、jQuery UI Developer Guide を参照してください。

  3. アタッチしたハンドラーの中に、必要なロジックを実装できます。そのために、イベントの属性を使用できます。すべてのイベントで同じ名前が付いています。e はイベントを表し、args は引数を表します。イベントによって、args 引数に含まれているプロパティ セットが異なります。

    注: イベントをキャンセルしたい場合（キャンセル可能なイベントは、fileSelecting および fileUploading）、関数から false を返す必要があるだけです。

このサンプルは、igUpload のイベントおよびメソッドの使用方法を紹介します。

API およびイベント

クライアント イベント

表 1 は、igUpload コントロールで使用可能なイベントを示しています。

表 1: igUpload コントロールから使用可能なクライアント イベント

イベント名 説明
fileSelecting 参照ボタンをクリックすると、すぐに fileSelecting イベントが発生します。このイベントが発生したとき、参照ウィンドウを作成する処理をキャンセルできます。 fileSelecting イベントが発生したとき、args 属性は空です。(関数から false を返すことによって) キャンセルすると、参照ダイアログは表示されません。
fileSelected ブラウザーのポップアップ ウィンドウからファイルを選択すると、すぐに fileSelected イベントが発生します。 選択時、イベント引数は、そのファイルの基本的な情報の一部をすでに持っています。args オブジェクトには 2 つのプロパティがあります。
  • fileID: すべてのファイルに対する 0 から始まる連続した数。これは、複数ファイルをアップロードするシナリオで有効です。その場合、この ID を使用して異なるファイルを識別できます。
  • filePath: 選択したファイルの名前。
注: ファイルを追加すると、fileSelecting および fileSelected イベントの発生するサイクルが繰り返されます。
fileUploading アップロード処理中およびファイルのアップロード中に fileUploading イベントが発生します。このイベントはキャンセルできます。 ファイルをアップロードするボタンを押したときに、このイベントは初めて呼び出されます。次に、progressUpdateInterval の値 (更新周期を決定します) に応じて、fileUploading が再び発生します。 この時、イベント引数には、以下の情報が含まれています。
  • fileID: すべてのファイルに対する 0 から始まる連続した数。これは、複数ファイルをアップロードするシナリオで有用です。その場合、この ID を使用して異なるファイルを識別できます。
  • filePath: 選択したファイルの名前。
  • fileStatus: ファイルの状態を表す整数。この値は、整数値を状態の説明にマップする列挙体を持っているサーバーによって決定されます。詳細については、表 2 を参照してください。
  • TotalSize: 選択したすべてのアップロード対象ファイルの合計ファイル サイズを返します。単位はバイトです。
  • UploadedBytes: fileUpload イベントが発生すると、現在のアップロード済みバイト数を返します。
イベント ハンドラー メソッド内で False の値を返すことによって、このイベントをキャンセルすることもできます。
fileUploaded すべてのファイルがサーバーにアップロードされると、fileUploaded イベントが発生します。このイベントが発生すると、args パラメーターには、fileID、filePath、および TotalSize の 3 つのプロパティが含まれます。 これらの項目の詳細については、fileUploading イベントを参照してください。
fileUploadAborted 各ファイルに関連付けられたキャンセル ボタンを使用して個々のファイルのアップロードをキャンセルすると、fileUploadAbort イベントが発生します。イベント引数オブジェクトには、fileUploading 引数と同じプロパティがあります。唯一の違いは、状態に、キャンセルしたファイルの値が含まれている点です。
cancelAllClicked アップロード処理中に、すべてのアップロード対象ファイルに有効なグローバル キャンセル ボタンをユーザーがクリックすると、cancelAllClicked イベントが発生します。
onError サーバーまたはクライアント側に例外がスローされると、onError イベントが発生します。 イベント引数には、次の情報が含まれます。
  • errorCode: エラー コードを表す整数。表 3 は、サーバー側のエラー コードを示しています。表 4 は、クライアント側のエラー コードを示しています。
  • errorMessage: 詳細なエラー情報。
  • errorType: エラーの種類。値は、server-side または client-side です。
  • serverMessage: これは、サーバー イベント UploadStarting の中で設定できるプロパティです。設定していない場合は、空の文字列です。(これを使用して、カスタム エラー メッセージを表示できます。)
注: アップロードの状態を監視するために、ハンドラーを onError イベントにアタッチできることに注意してください。サーバーにエラーが発生した場合、このイベントが発生し、操作の基本的な問題を errorCode が公開します。 さらに、ローカライズされた JavaScript ファイル (ig.ui.upload-en.js および ig.ui.upload-ja.js) を使用して、ローカライズされたエラー説明を検索することもできます。それらのファイルに、エラーについての独自の文字列を定義することもできます。
onFormDataSubmit onFormDataSubmit イベントは、アプロードされるファイルおよび追加データ (がある場合) がサーバーに送信される前に発生されます。 FormData オブジェクトに追加データ フィールドを追加するために使用します。
  • fileId: ファイルの一意識別子を取得します。
  • fileInfo: fileName、fileSize、serverMessage などの情報を含む fileInfo オブジェクトへの参照を取得します。
  • xhr: ブラウザーが HTML 5 ファイル API をサポートする場合、元の XMLHttpRequest オブジェクトへの参照を取得します。サポートしない場合、未定義です。
  • formData: ブラウザーが HTML 5 ファイル API をサポートする場合、FormData オブジェクトへの参照、または <form> の jQuery 表現への参照を取得します。
  • owner: igUpload ウィジェット オブジェクトを取得します。
onXHRLoad onXHRLoad イベントは、XmlHttpRequest の onload イベントが発生されたときに発生されます。ブラウザーが HTML5 API をサポートする場合のみ、イベントが発生されます。

以下の表に、サーバーが返すメッセージ コードをそれらの意味にマップしたものを示します。

表 2: UploadStatus タイプの列挙体

値 説明
0 ファイルのアップロードが始まっていません。
1 ファイルのアップロードが始まりました。
2 ファイルのアップロードが終了しました。
3 ファイルが見つかりません。ディクショナリにそのようなキーが見つからないときに、この状態を使用します。
4 クライアントの指示によってファイルのアップロードをキャンセルしました。
5 ファイルのサイズが大きすぎます。
6 ファイルのアップロード中にエラーが発生しました。
7 サーバー側のイベント ハンドラーによって、ファイルのアップロードをキャンセルしました。
8 クライアントの接続が途切れたため、ファイルのアップロードをキャンセルしました。
9 コンテンツ自体はアップロード済みで、ファイル名が一時的な名前のときのファイルの状態。

表 3: FileError タイプの列挙体 (サーバー側エラー)

値 説明
-1 エラーはありません。
0 要求からファイル名を取得する際にファイル エラーが発生しました。
1 MIME タイプの検証に失敗しました
2 ファイル サイズを超えています
3 ファイルがアップロードされる一時フォルダーが見つかりませんでした
4 要求ヘッダーの取得中にエラーが発生しました
5 要求で指定されたキーのファイルは存在しません
6 ファイルの保存に失敗しました
7 ファイル コンテンツの書き込みに失敗しました
8 ファイル コンテンツを初めて書き込む際にエラーが発生しました
9 ファイルの削除に失敗しました
10 イベント ハンドラーでファイルのアップロード開始時にアップロードがキャンセルされたときにエラーが発生しました。

表 4: FileError タイプの列挙体 (クライアント側エラー コード)

値 説明
1 アップロード可能なファイルの最大数を超えました。
2 クライアント側の拡張子の検証。
3 存在しない ID を持つファイルのアップロードを開始しようとしたときにエラーがスローされました。
4 ファイル状態の取得中に AJAX エラーが発生しました。
5 httpHandler でキャンセル コマンドを呼び出すときに AJAX エラーが発生しました。
6 存在しない ID を持つファイルを削除しようとしたときにエラーがスローされました。
7 ファイル サイズの取得中に AJAX エラーが発生しました。
8 ファイルがキャンセルされたかどうか、および maxSimultaneousFilesUploads が 0 以下かどうかを確認しようとしたときにエラーがスローされました。

関連リンク

オンラインで表示: GitHub