XMLHttpRequest

XMLHttpRequest (XHR) オブジェクトは、サーバーと対話するために使用されます。ページ全体を更新する必要なしに、データを受け取ることができます。これでユーザーの作業を中断させることなく、ウェブページの一部を更新することができます。 XMLHttpRequest は AJAX プログラミングで頻繁に使用されます。

XMLHttpRequest という名前ではあるものの、 XML だけでなくあらゆる種類のデータを受け取るために使用することができます。

通信においてサーバーからのイベントデータやメッセージデータの受信を含む必要があるのであれば、 Server-sent event の EventSource インターフェイスを使用することも検討してください。全二重の通信では、 WebSocket の方が良いかもしれません。

コンストラクター

XMLHttpRequest()
XMLHttpRequest を初期化するコンストラクターです。これは、他のメソッドを呼び出す前に呼び出さなければなりません。

プロパティ

このインターフェイスは、 XMLHttpRequestEventTarget および EventTarget のプロパティを継承します。

XMLHttpRequest.onreadystatechange
EventHandler で、これは readyState 属性が変化する度に呼び出されます。
XMLHttpRequest.readyState 読取専用
リクエストの状態を unsigned short で返します。
XMLHttpRequest.response 読取専用
リクエストのエンティティ本文を含む ArrayBuffer, Blob, Document, JavaScript オブジェクト, DOMString の何れかを、 XMLHttpRequest.responseType の値に応じて返します。
XMLHttpRequest.responseText 読取専用
リクエストに対するレスポンスがテキスト形式で入った DOMString を返すか、リクエストが失敗した場合や、まだ送信されていない場合は null を返します。
XMLHttpRequest.responseType
レスポンス型を定義する、列挙型の値です。
XMLHttpRequest.responseURL 読取専用
レスポンスのシリアライズされた URL、または URL が null であれば空文字列を返します。
XMLHttpRequest.responseXML 読取専用
リクエストに対するレスポンスが入った Document を返すか、またはリクエストが成功しなかった場合、まだ送信されていない場合、 XML または HTML として解釈できなかった場合は null を返します。
XMLHttpRequest.status 読取専用
リクエストに対するレスポンスのステータスを unsigned short で返します。
XMLHttpRequest.statusText 読取専用
HTTP サーバーから返ってきたレスポンス文字列が入った DOMString を返します。 XMLHTTPRequest.status とは異なり、("200 OK" のように) レスポンスメッセージの完全な文が含まれています。

注: HTTP/2 仕様書 (8.1.2.4 レスポンス擬似ヘッダーフィールド) によれば、 HTTP/2 では、 HTTP/1.1 のステータス行に含まれていたバージョンや原因の文を伝える方法が定義されていません。

XMLHttpRequest.timeout
リクエストを自動的に終了できるようになるまでの時間をミリ秒単位で表す、 unsigned long 型の値です。
XMLHttpRequestEventTarget.ontimeout
リクエストがタイムアウトする都度呼び出される EventHandler。
XMLHttpRequest.upload 読取専用
アップロードプロセスを表す XMLHttpRequestUpload です。
XMLHttpRequest.withCredentials
Boolean で、サイト間の Access-Control リクエストでクッキーや認証ヘッダーなどの資格情報を使用するかどうかを示します。

標準外のプロパティ

XMLHttpRequest.channel読取専用
nsIChannel です。リクエストの実行の際にオブジェクトによって使われるチャンネルです。
XMLHttpRequest.mozAnon読取専用
boolean です。 true の場合、リクエストは cookie や認証ヘッダを伴わずに送信します。
XMLHttpRequest.mozSystem読取専用
boolean です。 true の場合、リクエストで同一オリジンポリシーは適用されません。
XMLHttpRequest.mozBackgroundRequest
boolean です。オブジェクトがバックグラウンドサービスのリクエストであるかどうかを示します。
XMLHttpRequest.mozResponseArrayBuffer Gecko 6 で廃止 読取専用
ArrayBuffer です。リクエストに対する、JavaScript typed array 形式でのレスポンスです。
XMLHttpRequest.multipartGecko 22 で廃止
これは Gecko 独自の機能であり、 Firefox/Gecko 22 で削除されました。代わりに Server-Sent Event、Web Socket、または progress イベントの responseText を使用してください。

イベントハンドラー

onreadystatechange は XMLHttpRequest のインスタンスのプロパティとしてすべてのブラウザーが対応しています。

それ以来、数多くの追加のイベントハンドラーが様々なブラウザーに実装されてきています (onload, onerror, onprogress, など)。 XMLHttpRequest の使用を参照してください。

Firefox を含め、より新しいブラウザーでは、 XMLHttpRequest のイベントを on* プロパティをハンドラー関数に設定する方法に加えて、標準の addEventListener() API で待ち受けすることにも対応しています。

メソッド

XMLHttpRequest.abort()
リクエストがすでに送信されている場合、リクエストを中止します。
XMLHttpRequest.getAllResponseHeaders()
CRLF で区切られた文字列として、すべてのレスポンスヘッダを返します。レスポンスを何も受け取らなかった場合は null を返します。
XMLHttpRequest.getResponseHeader()
指定したヘッダ文を含む文字列を返します。レスポンスを受信していない、またはレスポンス中に指定したヘッダが存在しない場合は null を返します。
XMLHttpRequest.open()
リクエストを初期化します。このメソッドは JavaScript から使用するようにしてください。ネイティブコードからの初期化には、代わりに openRequest() を使用するようにしてください。
XMLHttpRequest.overrideMimeType()
サーバーから返ってくる MIME タイプを上書きします。
XMLHttpRequest.send()
リクエストを送信します。
XMLHttpRequest.setRequestHeader()
HTTP リクエストヘッダーの値を設定します。 setRequestHeader() は open() の後、および send() の前に呼び出さなくてはいけません。

標準外のメソッド

XMLHttpRequest.init()
C++ コードから使用するために、オブジェクトを初期化します。
警告: JavaScript からこのメソッドを呼び出してはいけません。
XMLHttpRequest.openRequest()
リクエストを初期化します。このメソッドはネイティブコードから使用するためのものです。 JavaScript コードからの初期化には、代わりに open() を使用してください。 open() の項目を参照してください。
XMLHttpRequest.sendAsBinary()
バイナリデータを送る、send() メソッドの亜種です。

イベント

abort
例えばプログラムが XMLHttpRequest.abort() を呼び出した時など、リクエストが中断されたときに発生します。
onabort プロパティを通して利用することもできます。
error
リクエストでエラーが発生したときに発生します。
onerror プロパティを通して利用することもできます。
load
XMLHttpRequest のトランザクションが成功裏に完了したときに発生します。
onload プロパティを通して利用することもできます。
loadend
リクエストが完了したときに、成功した場合 (load の後)、成功しなかった場合 (abort または error の後) のどちらでも発生します。
onloadend プロパティを通して利用することもできます。
loadstart
リクエストがデータを読み込み始めたときに発生します。
onloadstart プロパティを通して利用することもできます。
progress
リクエストがもっとデータを受信した際に定期的に発生します。
onprogress プロパティを通して利用することもできます。
timeout
プリセット時間が過ぎたために進行が終了したときに発生します。
ontimeout プロパティを通して利用することもできます。

仕様書

仕様書 状態 備考
XMLHttpRequest 現行の標準 Live standard 最新版

ブラウザーの互換性

BCD tables only load in the browser

関連情報