XMLHttpRequest.upload
XMLHttpRequest の upload プロパティは、アップロードの進捗を監視することができる XMLHttpRequestUpload オブジェクトを返します。
これは不透過なオブジェクトですが、 XMLHttpRequestEventTarget でもあるため、進捗を追跡するためにイベントリスナーを装着することができます。
Note: このオブジェクトにイベントリスナーを装着すると、リクエストが「単純なリクエスト」ではなくなり、オリジンをまたぐ場合はプリフライトリクエストが発行されるようになります。 CORS を参照してください。このため、イベントリスナーは
send()を呼び出す前に登録する必要があり、そうしないとアップロードイベントが発行されなくなります。
Note: また、仕様書では、イベントリスナーは
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