Ajax (XMLHttpRequest)

https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest

概要
プロパティ
コンストラクタ
メソッド
注意事項
ブラウザの互換性
関連項目

概要

XMLHttpRequestは、Microsoftによって設計され、Mozilla、Apple、Googleによって採用されたJavaScriptオブジェクトです。現在では、W3Cによって標準化されています。これは、ページ全体のリフレッシュをする必要なく、URLからデータを簡単に取得する方法を提供してくれます。 Webページは、ユーザーが何が起こったのか分からず混乱すること無く、ページ内の一部分を更新することが可能です。 XMLHttpRequestはAjaxプログラミングで頻繁に使用されます。

XMLHttpRequestという名前にも関わらず、XMLに限らず幾つかのタイプのデータを取得することが可能で、 HTTP以外のプロトコル(fileとftpを含む)もサポートします。

XMLHttpRequestのインスタンスを作成するには、単に下記のようにするだけです。

var myRequest = new XMLHttpRequest();

XMLHttpRequestの詳細な使用方法については、XMLHttpRequestの使用方法を確認してください。

プロパティ

属性説明

onreadystatechange

型：Function?

readyStateの属性が変更された際に呼び出されるJavaScript関数(Function)オブジェクトを指定します。コールバックは、ユーザーインターフェイススレッドから呼び出されます。

警告: これは同期リクエストと一緒に使用されるべきではありません。また、ネイティブコードから使用してはいけません。

readyState

型：unsigned short

リクエストの状態です。

値	状態	説明
0	`UNSENT`	`open()`は、まだ呼ばれていない。
1	`OPENED`	`send()`は、まだ呼ばれていない。
2	`HEADERS_RECEIVED`	send()が呼ばれ、headersとstatusが利用可能。
3	`LOADING`	ダウンローディング中。 responseTextは部分的にデータを保持。
4	`DONE`	処理が完了。

response

型：varies

responseTypeに沿ったArrayBuffer、Blob、Document、 JavaScriptオブジェクト("json"のための)、文字列としてのresponseのbody実体になります。リクエストが完了していない、または成功しなかった場合はnullです。

responseText
読取専用

型：DOMString

リクエストへのテキストとしてのレスポンスになります。リクエストが成功しない、またはまだ送信されていない場合はnullになります。

responseType

型：XMLHttpRequestResponseType

レスポンスの種類を変更するように、設定することが出来ます。

値	レスポンスプロパティのデータ型
"" (空文字列)	文字列(デフォルト)
"arraybuffer"	ArrayBuffer
"blob"	Blob
"document"	Document
"json"	サーバによって返されたJSON文字列からパースしたJavaScriptオブジェクトです。
"json"	文字列

注意: WebKitビルド528と同様に、Gecko 11.0(Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8)以降では、同期リクエスト実行の際にresponseType属性の使用させないようになりました。(翻訳に自信無し) それを行おうとすると、NS_ERROR_DOM_INVALID_ACCESS_ERR例外がスローされます。この変更は、標準化のためにW3Cに提案されています。

responseXML
読取専用

型：Document?

DOMドキュメントオブジェクトとしての、リクエストに対するレスポンスです。もし、リクエストが失敗、まだ送信されていない、またはXML・HTMLにパース出来なければnullになります。レスポンスは、text/xmlストリームであるかのようにパースされます。 responseTypeが"document"に設定されていて、リクエストが非同期である場合、レスポンスはtext/htmlストリームとしてパースされます。

注意: もし、サーバがtext/xml Content-Typeヘッダーを適用しない場合、 overrideMimeType()を使用して、XMLHttpRequestを強制的にXMLとしてパースすることが出来ます。

status
読取専用

型：unsigned short

リクエストに対するレスポンスのステータスです。これは、HTTPのコードになります。(例えば、200はリクエスト成功を意味します。)

statusText
読取専用

型：DOMString

HTTPサーバによって返されるレスポンス文字列です。 statusとは異なり、これにはレスポンスメッセージのテキストが全て含まれます。(例: "200 OK")

timeout

型：unsigned long 初期値：0

リクエストが自動終了されるまで確保する時間をミリ秒単位で指定します。値が0(デフォルト)の場合、タイムアウト無しとみなされます。

注意: 自身のwindowでの同期リクエストでは、timeoutは使用できないかもしれません。

ontimeout

型：Function

このJavaScript関数オブジェクトは、リクエストがタイムアウトした際に呼び出されます。

upload

型：XMLHttpRequestUpload

アップロードプロセスは、アップロードのためのイベントリスナーを追加することによって追跡することが可能になります。

withCredentials

型：boolean 初期値：false

cross-site(クロスサイト)のAccess-Controlリクエストは、 Cookieまたは認証ヘッダーのような証明を使用して作られるべきか否かを指定します。デフォルトはfalseです。

注意: これは同じサイト内でのリクエストであれば、影響を及ぼすことはありません。

注意: Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8)以降、同期リクエスト実行時に、GeckoはwithCredentials属性を使用させないようになりました。それをしようと試みると、NS_ERROR_DOM_INVALID_ACCESS_ERR例外をスローします。

コンストラクタ

XMLHttpRequest()

コンストラクタはXMLHttpRequestをインスタンス化します。他のメソッドを呼び出す前に、これを行う必要があります。

XMLHttpRequest (
  JSObject objParameters
);

メソッド

abort()

もし既にリクエストが送信されていた場合、それを中断します。

getAllResponseHeaders()

DOMString getAllResponseHeaders();

文字列として全てのレスポンスヘッダーを返します。レスポンスを何も受け取っていなければ、nullになります。注意: マルチパートリクエストのために、これは元のチャンネルでは無く、現在のリクエストの一部からヘッダーを返します。

getResponseHeader()

DOMString? getResponseHeader(DOMString header);

指定したヘッダーのテキストを含む文字列を返します。レスポンスをまだ受け取っていない、またはレスポンス内にヘッダーが存在しない場合はnullになります。

open()

リクエストを初期化します。このメソッドは、openRequest()を使用する代わりにネイティブコードからリクエストを初期化するために、JavaScriptコードから使用されます。

注意: 既にアクティブなリクエスト(open()またはopenRequest()が既に呼ばれていた)に対して、このメソッドを呼び出すのは、abort()を呼び出すのと同等です。

void open(
   DOMString method,
   DOMString url,
   optional boolean async,
   optional DOMString user,
   optional DOMString password
);

引数	説明
method	型：`DOMString` "GET"、"POST"、"PUT"、"DELETE"のような、使用するHTTPメソッドを指定します。 HTTP(S)では無いURLでは無視されます。
url	型：`DOMString` リクエストを送信するURLです。
[async]	型：`boolean` 初期値：`true` 初期値がtrueの任意の真偽値パラメータで、非同期で実行するか否かを指定します。もし、この値がfalseであれば、`send()`メソッドはレスポンスを受け取るまで、returnしません。もしtrueであれば、完了したトランザクションの通知がイベントリスナーを使用して提供されます。もし、`multipart`属性がtrueであれば、この値をtrueにしなければいけません。そうしなければ、例外がスローされてしまいます。
[user]	型：`DOMString` 初期値：`""` 認証に使用するための任意のユーザー名を指定します。デフォルトは空文字列です。
[password]	型：`DOMString` 初期値：`""` 認証に使用するための任意のパスワードを指定します。デフォルトは空文字列です。

overrideMimeType()

サーバから返されるMIME-typeを上書きします。例えば、サーバがtext/xmlと返答しなかったとしても、強制的にtext/xmlとして、一連の処理の扱いと解析を強制的に行うのに使用することが出来るかもしれません。このメソッドは、send()の前に呼ばれなければいけません。

void overrideMimeType(DOMString mimetype);

send()

リクエストを送信します。もし、そのリクエストが非同期(デフォルト)であれば、このメソッドはすぐにリクエスト送信を返します。もし、そのリクエストが同期であれば、このメソッドはレスポンスが返るまでリクエスト送信を返しません。

注意: 設定したいイベントリスナーは、send()が呼ばれる前に設定されなければいけません。

注意: パラメータにプレーンなArrayBufferを使用しないように注意してください。これはもはや、XMLHttpRequest使用の一部ではありません。代わりにArrayBufferViewを使用してください。(バージョン情報の互換性テーブルを参照してください。)

void send();
// void send(ArrayBuffer data); *ArrayBufferは廃止*
void send(ArrayBufferView data);
void send(Blob data);
void send(Document data);
void send(DOMString? data);
void send(FormData data);

注意

もし、dataがDocumentであれば、送信される前にシリアライズされます。 Documentを送る際に、バージョンが3より前のFirefoxでは常にUTF-8エンコーディングを使用してリクエストを送信し、 Firefox3では、body.xmlEncodingに指定されたエンコーディングを使用して、または未指定であればUTF-8を使用して適切にDocumentを送信します。

もし、nsIInputStreamの場合、nsIUploadChannelのsetUploadStream()メソッドと互換性を取る必要があります。この場合、その値をnsIInputStreamで利用可能なavailable()メソッドで取得し、 Content-Lengthヘッダーがリクエストに追加されます。ストリーム(stream)の上部に含まれるヘッダーは、メッセージボディ(本文)の一部として扱われます。ストリームのMIMEtypeは、send()呼び出しより前にsetRequestHeader()メソッドを使用して、 Content-Typeヘッダーの設定によって指定されるべきです。

バイナリコンテンツを送信する(ファイルアップロード等)最善の方法は、 send()メソッドとArrayBufferViewまたはBlobsを組み合わせて使用することです。ただし、もし文字列的(stringifiable)な生のデータを送信したいのであれば、代わりにsendAsBinary()メソッドか、非ネイティブの配列のスーパークラスに型指定されたStringViewを使用してください。(翻訳に自信無し)

setRequestHeader()

HTTPリクエストヘッダーの値を設定します。 setRequestHeader()は、open()の後、send()の前に呼び出さなければいけません。もし、このメソッドが同一ヘッダーで何度か呼び出されると、単一のリクエストヘッダー内にその値をマージします。

void setRequestHeader(
   DOMString header,
   DOMString value
);

引数	説明
header	値を設定するヘッダーの名前を指定します。
value	ヘッダーのボディとして設定する値を指定します。

注意事項

Firefox3はデフォルトで、サーバーごとのXMLHttpRequest接続の数を6に制限していました。 (更に前のバージョンでは、この数は2でした) インタラクティブなWebサイトでは、XMLHttpRequest接続のオープンを保持している可能性があり、そのようなサイトと複数のセッションを開いていると、ウインドウが再描画と応答の制御が出来なくなり、ブラウザが固まってしまうかもしれません。(翻訳に自信なし) この値は、about:configの設定の中で、 network.http.max-persistent-connections-per-serverを編集することで変更することが出来ます。
Gecko 7.0から、setRequestHeader()に設定されるヘッダーは、リダイレクトの際にリクエストと一緒に送信されるようになりました。それ以前では、リダイレクトの際にこれは送信されていませんでした。
リクエストがtimeout値に達した場合、 "timeout"イベントが発生します。

Event

XMLHttpRequestのインスタンス・プロパティとしてのonreadystatechangeは、全てのブラウザでサポートされます。

また、様々なブラウザで追加のイベントハンドラ(onload、 onerror、 onprogress ( onprogress は非標準でIEのみ?) 等)が実装されています。これらはFirefoxでもサポートされています。詳細については、Using XMLHttpRequestを参照してください。

Firefoxを含む最近の多くのブラウザは、ハンドラ関数へon*プロパティを付加した、標準のaddEventListenerのAPIを介して、 XMLHttpRequestのリッスンもサポートします。

ブラウザの互換性

Geckoでの注意事項

Gecko 11.0(Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8)では、同期リクエスト実行時のresponseTypeとwithCredentials属性のサポートが削除されました。この実行を試みると、NS_ERROR_DOM_INVALID_ACCESS_ERR例外がスローされます。この変更は、標準化のためにW3Cに提案されています。

Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9)とそれ以降のバージョンは、 XMLHttpRequestを使用したdata: URIsからの読み取りをサポートします。

Gecko 20.0 (Firefox 20.0 / Thunderbird 20.0 / SeaMonkey 2.17)は、 ArrayBufferViewの送信のサポートを追加します。プレーンなArrayBufferの送信は、もはやXMLHttpRequest仕様の一部では無いため、非推奨として扱われるべきです。

Operaでの注意事項

Blink/Chromiumに切り替わる前のOperaでは、Opera12～15の間、responseType=jsonがサポートされていました。このサポートは、その後Blink(Opera 17)でも実装されたことで、再び追加されました。(翻訳に自信なし)