From 02fd3f93e66f9041f6a037efc17cf85bff020eba Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Fri, 28 Jan 2022 01:38:04 +0900 Subject: 2022/01/22 時点の英語版に同期 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/xmlhttprequest/index.md | 318 ++++++++++++++----------------- 1 file changed, 139 insertions(+), 179 deletions(-) (limited to 'files/ja') diff --git a/files/ja/web/api/xmlhttprequest/index.md b/files/ja/web/api/xmlhttprequest/index.md index e244ae67d6..60899af7f5 100644 --- a/files/ja/web/api/xmlhttprequest/index.md +++ b/files/ja/web/api/xmlhttprequest/index.md @@ -4,187 +4,147 @@ slug: Web/API/XMLHttpRequest tags: - AJAX - API - - Communication + - 通信 - HTTP - - Interface - - Reference - - Web + - インターフェイス + - リファレンス + - ウェブ - XHR - XMLHttpRequest +browser-compat: api.XMLHttpRequest translation_of: Web/API/XMLHttpRequest --- -
{{DefaultAPISidebar("XMLHttpRequest")}}
- -

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

- -

{{InheritanceDiagram(650, 150)}}

- -

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

- -

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

- -

コンストラクター

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

プロパティ

- -

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

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

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

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

標準外のプロパティ

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

イベントハンドラー

- -

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

- -

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

- -

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

- -

メソッド

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

標準外のメソッド

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

イベント

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

仕様書

- - - - - - - - - - - - - - - - -
仕様書状態備考
{{SpecName('XMLHttpRequest')}}{{Spec2('XMLHttpRequest')}}Live standard 最新版
- -

ブラウザーの互換性

- -
{{Compat("api.XMLHttpRequest")}}
- -

関連情報

- - +{{DefaultAPISidebar("XMLHttpRequest")}} + +`XMLHttpRequest` (XHR) オブジェクトは、サーバーと対話するために使用されます。ページ全体を更新する必要なしに、データを受け取ることができます。これでユーザーの作業を中断させることなく、ウェブページの一部を更新することができます。 + +`XMLHttpRequest` は {{Glossary("AJAX")}} プログラミングで頻繁に使用されます。 + +{{InheritanceDiagram}} + +`XMLHttpRequest` という名前ではあるものの、 XML だけでなく、あらゆる種類のデータを受け取るために使用することができます。 + +通信においてサーバーからのイベントデータやメッセージデータの受信を含む必要があるのであれば、 [Server-sent event](/ja/docs/Web/API/Server-sent_events) の {{domxref("EventSource")}} インターフェイスを使用することも検討してください。全二重の通信では、 [WebSocket](/ja/docs/Web/API/WebSockets_API) の方が良いかもしれません。 + +{{AvailableInWorkers("notservice")}} + +## コンストラクター + +- {{domxref("XMLHttpRequest.XMLHttpRequest", "XMLHttpRequest()")}} + - : XMLHttpRequest を初期化するコンストラクターです。これは、他のメソッドを呼び出す前に呼び出さなければなりません。 + +## プロパティ + +_このインターフェイスは、 {{domxref("XMLHttpRequestEventTarget")}} および {{domxref("EventTarget")}} のプロパティを継承しています。_ + +- {{domxref("XMLHttpRequest.onreadystatechange")}} + - : [イベントハンドラー](/ja/docs/Web/Events/Event_handlers) で、 `readyState` 属性が変化する度に呼び出されます。 +- {{domxref("XMLHttpRequest.readyState")}} {{readonlyinline}} + - : `unsigned short` でリクエストの状態を返します。 +- {{domxref("XMLHttpRequest.response")}} {{readonlyinline}} + - : {{jsxref("ArrayBuffer")}}, {{domxref("Blob")}}, {{domxref("Document")}}, JavaScript オブジェクト, {{domxref("DOMString")}} の何れか（{{domxref("XMLHttpRequest.responseType")}} の値による）で、リクエストのエンティティ本文を返します。 +- {{domxref("XMLHttpRequest.responseText")}} {{readonlyinline}} + - : {{domxref("DOMString")}} でリクエストに対するレスポンスをテキスト形式で返すか、リクエストが失敗した場合や、まだ送信されていない場合は `null` を返します。 +- {{domxref("XMLHttpRequest.responseType")}} + - : 列挙型の値で、レスポンス型を定義します。 +- {{domxref("XMLHttpRequest.responseURL")}} {{readonlyinline}} + - : レスポンスのシリアライズされた URL、または URL が null であれば空文字列を返します。 +- {{domxref("XMLHttpRequest.responseXML")}} {{readonlyinline}} + - : {{domxref("Document")}} でリクエストに対するレスポンスが入ったを返すか、またはリクエストが成功しなかった場合、まだ送信されていない場合、 XML または HTML として解釈できなかった場合は `null` を返します。 +- {{domxref("XMLHttpRequest.status")}} {{readonlyinline}} + - : `unsigned short` でリクエストに対するレスポンスのステータスを返します。 +- {{domxref("XMLHttpRequest.statusText")}} {{readonlyinline}} + + - : {{domxref("DOMString")}} で HTTP サーバーから返ってきたレスポンス文字列を返します。 {{domxref("XMLHttpRequest.status")}} とは異なり、("`200 OK`" のような) レスポンスメッセージの完全な文が含まれています。 + + > **Note:** HTTP/2 仕様書 ([8.1.2.4](https://http2.github.io/http2-spec/#rfc.section.8.1.2.4) [レスポンス擬似ヘッダーフィールド](https://http2.github.io/http2-spec/#HttpResponse)) によれば、 HTTP/2 では、 HTTP/1.1 のステータス行に含まれていたバージョンや原因の文を伝える方法が定義されていません。 + +- {{domxref("XMLHttpRequest.timeout")}} + - : `unsigned long` 型で、リクエストを自動的に終了できるようになるまでの時間をミリ秒単位で表します。 +- {{domxref("XMLHttpRequestEventTarget.ontimeout")}} + - : [イベントハンドラー](/ja/docs/Web/Events/Event_handlers)で、リクエストがタイムアウトするたびに呼び出されます。 +- {{domxref("XMLHttpRequest.upload")}} {{readonlyinline}} + - : {{domxref("XMLHttpRequestUpload")}} で、アップロードプロセスを表します。 +- {{domxref("XMLHttpRequest.withCredentials")}} + - : 論理値で、サイト間の `Access-Control` リクエストでクッキーや認証ヘッダーなどの資格情報を使用するかどうかを示します。 + +### 標準外のプロパティ + +- {{domxref("XMLHttpRequest.channel")}}{{ReadOnlyInline}} + - : リクエストの実行の際にオブジェクトによって使われるチャンネルです。 +- {{domxref("XMLHttpRequest.mozAnon")}}{{ReadOnlyInline}} + - : 論理値です。 true の場合、リクエストを Cookie や認証ヘッダーを伴わずに送信します。 +- {{domxref("XMLHttpRequest.mozSystem")}}{{ReadOnlyInline}} + - : 論理値です。 true の場合、リクエストで同一オリジンポリシーは適用されません。 +- {{domxref("XMLHttpRequest.mozBackgroundRequest")}} + - : 論理値です。このオブジェクトがバックグラウンドサービスのリクエストを表しているかどうかを示します。 + +### イベントハンドラー + +`onreadystatechange` は `XMLHttpRequest` のインスタンスのプロパティとして、すべてのブラウザーが対応しています。 + +それ以来、数多くの追加のイベントハンドラーが様々なブラウザーに実装されてきています (`onload`, `onerror`, `onprogress`, など)。 [XMLHttpRequest の使用](/ja/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest)を参照してください。 + +Firefox を含め、より新しいブラウザーでは、 `XMLHttpRequest` のイベントを `on*` プロパティをハンドラー関数に設定する方法に加えて、標準の {{domxref("EventTarget.addEventListener", "addEventListener()")}} API で待ち受けすることにも対応しています。 + +## メソッド + +- {{domxref("XMLHttpRequest.abort()")}} + - : リクエストがすでに送信されている場合、リクエストを中止します。 +- {{domxref("XMLHttpRequest.getAllResponseHeaders()")}} + - : すべてのレスポンスヘッダーを、 {{Glossary("CRLF")}} で区切り、文字列として返します。レスポンスを何も受け取らなかった場合は `null` を返します。 +- {{domxref("XMLHttpRequest.getResponseHeader()")}} + - : 指定したヘッダーを含む文字列を返します。レスポンスを受信していない、またはレスポンス内に指定したヘッダーが存在しない場合は `null` を返します。 +- {{domxref("XMLHttpRequest.open()")}} + - : リクエストを初期化します。 +- {{domxref("XMLHttpRequest.overrideMimeType()")}} + - : サーバーから返ってくる MIME タイプを上書きします。 +- {{domxref("XMLHttpRequest.send()")}} + - : リクエストを送信します。このリクエストが非同期（既定）の場合、このメソッドはリクエストが送るとすぐに返ります。 +- {{domxref("XMLHttpRequest.setRequestHeader()")}} + - : HTTP リクエストヘッダーの値を設定します。 `setRequestHeader()` は [`open()`](#open) の後、および `send()` の前に呼び出さなくてはいけません。 + +## イベント + +- {{domxref("XMLHttpRequest/abort_event", "abort")}} + - : 例えばプログラムが {{domxref("XMLHttpRequest.abort()")}} を呼び出した時など、リクエストが中断されたときに発生します。 + {{domxref("XMLHttpRequestEventTarget/onabort", "onabort")}} プロパティを通して利用することもできます。 +- {{domxref("XMLHttpRequest/error_event", "error")}} + - : リクエストでエラーが発生したときに発生します。 + {{domxref("XMLHttpRequestEventTarget/onerror", "onerror")}} プロパティを通して利用することもできます。 +- {{domxref("XMLHttpRequest/load_event", "load")}} + - : {{domxref("XMLHttpRequest")}} のトランザクションが成功裏に完了したときに発生します。 + {{domxref("XMLHttpRequestEventTarget/onload", "onload")}} プロパティを通して利用することもできます。 +- {{domxref("XMLHttpRequest/loadend_event", "loadend")}} + - : リクエストが完了したときに、成功した場合 ({{domxref("XMLHttpRequest/load_event", "load")}} の後)、成功しなかった場合 ({{domxref("XMLHttpRequest/abort_event", "abort")}} または {{domxref("XMLHttpRequest/error_event", "error")}} の後) のどちらでも発生します。 + {{domxref("XMLHttpRequestEventTarget/onloadend", "onloadend")}} プロパティを通して利用することもできます。 +- {{domxref("XMLHttpRequest/loadstart_event", "loadstart")}} + - : リクエストがデータを読み込み始めたときに発生します。 + {{domxref("XMLHttpRequestEventTarget/onloadstart", "onloadstart")}} プロパティを通して利用することもできます。 +- {{domxref("XMLHttpRequest/progress_event", "progress")}} + - : リクエストがもっとデータを受信した際に定期的に発生します。 + {{domxref("XMLHttpRequestEventTarget/onprogress", "onprogress")}} プロパティを通して利用することもできます。 +- {{domxref("XMLHttpRequest/timeout_event", "timeout")}} + - : プリセット時間が過ぎたために進行が終了したときに発生します。 + {{domxref("XMLHttpRequestEventTarget/ontimeout", "ontimeout")}} プロパティを通して利用することもできます。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("XMLSerializer")}}: DOM ツリーの XML へのシリアライズ +- `XMLHttpRequest` に関連する MDN の記事 + + - [Ajax — 始めましょう](/ja/docs/Web/Guide/AJAX/Getting_Started) + - [XMLHttpRequest の使用](/ja/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest) + - [XMLHttpRequest における HTML の扱い](/ja/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest) + - [Fetch API](/ja/docs/Web/API/Fetch_API) + +- [HTML5 Rocks — New Tricks in XMLHttpRequest2](https://www.html5rocks.com/en/tutorials/file/xhr2/) +- Feature-Policy のディレクティブ {{httpheader("Feature-Policy/sync-xhr", "sync-xhr")}} -- cgit v1.2.3-54-g00ecf