XMLHttpRequest.upload

XMLHttpRequest の upload プロパティは、アップロードの進捗を監視することができる XMLHttpRequestUpload オブジェクトを返します。

これは不透過なオブジェクトですが、 XMLHttpRequestEventTarget でもあるため、進捗を追跡するためにイベントリスナーを装着することができます。

メモ: このオブジェクトにイベントリスナーを装着すると、リクエストが「単純なリクエスト」ではなくなり、オリジンをまたぐ場合はプリフライトリクエストが発行されるようになります。 CORS を参照してください。このため、イベントリスナーは send() を呼び出す前に登録する必要があり、そうしないとアップロードイベントが発行されなくなります。

メモ: また、仕様書では、イベントリスナーは open() の後に装着すべきとされているようです。しかし、ブラウザーはこの点に関してバグが多く、リスナーを open() の前に登録しないと動作しないことがよくあります。

以下のイベントは、アップロードオブジェクト上で発行され、アップロードを監視するために使用することができます。

イベント イベントリスナー 解説
loadstart onloadstart アップロードが始まった。
progress onprogress 進捗を示すために定期的に発行されます。
abort onabort アップロード操作が中止された。
error onerror アップロードがエラーで失敗した。
load onload アップロードが成功裏に完了した。
timeout ontimeout XMLHttpRequest.timeout で指定された時間内に返答が届かなかったために、アップロードがタイムアウトした。
loadend onloadend アップロードが終了した。このイベントは成功か失敗かにかかわらず、アップロードが終了したときに発行されます。このイベントより前に、 load, error, abort, timeout の何れかが、アップロードが終了した理由を示すために配信されます。

仕様書

Specification
XMLHttpRequest Standard
# the-upload-attribute

ブラウザーの互換性

BCD tables only load in the browser

関連情報