Headers

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2017年3月.

* 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 オブジェクトにある指定された名前を持つ、ヘッダーのすべての値を示す文字列の配列を返します。
Headers.getSetCookie(): レスポンスに関連付けられたすべての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' が返される