XMLHttpRequest: upload プロパティ

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015年7月.

メモ: この機能はウェブワーカー内で利用可能ですが、サービスワーカーでは使用できません。

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

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

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

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

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

イベント解説

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