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
(en-US) 読取専用- 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
(en-US)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.multipart
Gecko 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()
(en-US)- サーバーから返ってくる 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
関連情報
XMLSerializer
: DOM ツリーの XML へのシリアライズXMLHttpRequest
に関連する MDN の記事- HTML5 Rocks — New Tricks in XMLHttpRequest2
- Feature-Policy のディレクティブ sync-xhr (en-US)