Headers
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.
* Some parts of this feature may have varying levels of support.
メモ: この機能はウェブワーカー内で利用可能です。
Headers はフェッチ API のインターフェイスで、 HTTP リクエスト／レスポンスヘッダー上のさまざまなアクションを実行します。アクションとしては、リクエストヘッダーのリストに対するヘッダーの取得、設定、追加、削除などがあります。
Headers オブジェクトは Request.headers および Response.headers プロパティから受け取ることができ、新しい Headers オブジェクトは Headers() コンストラクターで作成することができます。
メモ: 利用可能なヘッダーについての詳細は、 HTTP ヘッダーのリファレンスをお読みください。
解説
Headers オブジェクトは、初期状態では空で 0 個以上の名前と値のペアで構成される関連するヘッダーの連想リストを持っています。 append() （例を見てください）のようなメソッドを使用して、ヘッダーを追加することができます。このインターフェイスのすべてのメソッドで、ヘッダー名は大文字小文字を区別しないバイト列として照合されます。
Headers を実装しているオブジェクトは、 entries() を使用しなくても、 for...of 構造で直接使用することができます。 for (const p of myHeaders) は for (const p of myHeaders.entries()) と同等です。
変更の制限
一部の Headers オブジェクトは、set()、delete()、append() の各メソッドでヘッダーが変更できるかどうかの制限があります。この変更の制限は、その Headers オブジェクトがどのように作成されたかによって決まります。
Headers()コンストラクターで作成されたヘッダーについては、変更の制限はありません。Requestオブジェクトのヘッダーについては次の通りです。- そのリクエストの
modeがno-corsである場合、すべての CORS セーフリストリクエストヘッダーの名前と値が変更できます。 - そうでない場合、すべての 禁止ヘッダーでないヘッダーの名前と値が変更できます。
- そのリクエストの
Responseオブジェクトのヘッダーについては次の通りです。- そのレスポンスが
Response.error()またはResponse.redirect()から作成されたか、fetch()呼び出しから取得されたものであるヘッダーは不変であり、変更することはできません。 - そうでない場合、そのレスポンスが
Response()またはResponse.json()で作成されたものであれば、すべての 禁止ヘッダーでないレスポンスヘッダーの名前と値が変更できます。
- そのレスポンスが
Headers のすべてのメソッドは、有効な HTTP ヘッダー名ではない名前を参照として渡そうとすると、 TypeError が発生します。そのヘッダーが不変である場合は、変更操作で TypeError が発生します。それ以外の失敗は、すべて暗黙に失敗します。
コンストラクター
Headers()-
新しい
Headersオブジェクトを生成します。
インスタンスメソッド
Headers.append()-
Headersオブジェクト内の既存のヘッダーに新しい値を追加するか、まだ存在しない場合はヘッダーを追加します。 Headers.delete()-
Headersオブジェクトからヘッダーを削除します。 Headers.entries()-
このオブジェクトに含まれるすべてのキー/値のペアを通して処理するためのイテレーターを返します。
Headers.forEach()-
指定された関数を、この
Headersオブジェクトのキー/値のペアそれぞれに対して一度ずつ実行します。 Headers.get()-
Headersオブジェクトにある指定された名前を持つ、ヘッダーのすべての値を示す文字列の配列を返します。 -
レスポンスに関連付けられたすべての
Set-Cookieヘッダーの値の入った配列を返します。 Headers.has()-
Headersオブジェクトが特定のヘッダーを含むかどうかを示す値を、論理値で返します。 Headers.keys()-
このオブジェクトに含まれるキー/値のペアのすべてのキーを通して処理するための イテレーターを返します。
Headers.set()-
オブジェクト内の既存のヘッダーに新しい値を設定するか、まだ存在しない場合はヘッダーを追加する。
Headers.values()-
このオブジェクトに含まれるキー/値のペアのすべての値を通して処理するためのイテレーターを返します。
メモ: Headers.set() と Headers.append() の明確な違いは、複数の値を受け入れる特定のヘッダーが既に存在しているときの挙動です。Headers.set() は既存の値を新しい値で上書きしますが、Headers.append() は既存の値の末尾に新しい値を追加します。サンプルコードはそれぞれの専用ページで確認してください。
メモ: ヘッダーを反復処理する時は、自動的に辞書順への並び替えが行われ、重複する名前は結合されます。
例
次のコードスニペットでは、Headers() コンストラクターを使用して新しいヘッダーを生成し、append() を使用して新しいヘッダーを追加しています。その後、 get() を使用してヘッダーの値を返します。
const myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.get("Content-Type"); // 'text/xml' を返す。
同じことがコンストラクターにオブジェクトリテラルか配列リテラルの配列リテラルを渡すことでできます。
let myHeaders = new Headers({
"Content-Type": "text/xml",
});
// または、配列の配列を使用して
myHeaders = new Headers([["Content-Type", "text/xml"]]);
myHeaders.get("Content-Type"); // 'text/xml' が返される
仕様書
| Specification |
|---|
| Fetch # headers-class |