URL

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

メモ: この機能はウェブワーカー内で利用可能です。

URL インターフェイスは、URL の解釈、構築、正規化、およびエンコードに使用します。 URL のコンポーネントを簡単に読み取って変更できるプロパティを提供することで機能します。

通常、新しい URL オブジェクトを作成するにはコンストラクターを呼び出すときに URL を文字列として指定するか、相対 URL とベース URL を指定します。その後、解釈された URL のコンポーネントを簡単に読み取ったり、URL を変更したりすることができます。

コンストラクター

URL(): URL オブジェクトを、URL 文字列とオプションのベース URL 文字列から作成し、それを返します。渡された引数が有効な URL を定義していない場合、例外が発生します。

プロパティ

hash: '#' に続いて URL のフラグメント識別子の入った文字列です。
host: ドメイン（ホスト名）に続いて（ポートが指定されている場合）、':' と URL のポート番号の入った文字列。
hostname: URL のドメインの入った文字列です。
href: URL 全体の入った文字列を返す文字列化子です。
origin 読取専用: URL のオリジン、つまりそのスキーム、ドメイン、およびポート番号の入った文字列を返します。
password: ドメイン名の前に指定されたパスワードの入った文字列です。
pathname: 最初の '/' に続いて URL のパスの入り、クエリー文字列やフラグメントが入らない文字列です。
port: URL のポート番号の入った文字列です。
protocol: 最後の ':' までを含めた URL のプロトコルスキームの入った文字列です。
search: URL 引数文字列を示す文字列です。引数が指定されている場合、この文字列には先頭の ? 文字で始まるすべての引数が含まれます。
searchParams 読取専用: search で見つかった個々のクエリー引数にアクセスするために使用できる URLSearchParams オブジェクトです。
username: ドメイン名の前に指定されたユーザー名の入った文字列です。

静的メソッド

canParse(): URL 文字列とオプションのベース URL 文字列から定義された URL が解釈可能で有効かどうかを示す論理値を返します。
createObjectURL(): 一意の blob URL の入った文字列を返します。これは、スキームとして blob: の入った URL で、その後にブラウザー内のオブジェクトを一意に識別する不透明な文字列が続きます。
parse(): URL オブジェクトを、URL 文字列とオプションのベース URL 文字列から作成して返します。渡された引数が無効な URL を定義している場合は、null を返します。
revokeObjectURL(): URL.createObjectURL() を使用して以前に生成したオブジェクト URL を取り消します。

メソッド

toString(): URL 全体の入った文字列を返します。 URL.href と同義ですが、値の変更に使用することはできません。
toJSON(): URL 全体の入った文字列を返します。 href プロパティと同じ文字列を返します。

使用上の注意

コンストラクターは、url 引数と、url 引数が相対 URL の場合にベースとして使用するオプションの base 引数を受け取ります。

const url = new URL("../cats", "http://www.example.com/dogs");
console.log(url.hostname); // "www.example.com"
console.log(url.pathname); // "/cats"

コンストラクターは URL を有効な URL に解釈できない場合に例外を発生させます。上記のコードを try...catch ブロックの中で呼び出すか、canParse() 静的メソッドを使って先に URL が有効かどうかをチェックしてください。

if (URL.canParse("../cats", "http://www.example.com/dogs")) {
  const url = new URL("../cats", "http://www.example.com/dogs");
  console.log(url.hostname); // "www.example.com"
  console.log(url.pathname); // "/cats"
} else {
  console.log("無効な URL"); // 無効な URL
}

URL を構築するために URL のプロパティを設定できます。

url.hash = "tabby";
console.log(url.href); // "http://www.example.com/cats#tabby"

URL は、RFC 3986 にあるルールに従ってエンコードされます。例えば、次のとおりです。

url.pathname = "démonstration.html";
console.log(url.href); // "http://www.example.com/d%C3%A9monstration.html"

URL のクエリー文字列を構築および操作するために、URLSearchParams インターフェイスを使用できます。

現在のウィンドウの URL から検索引数を取得するには、次のようにします。

// https://some.site/?id=123
const parsedUrl = new URL(window.location.href);
console.log(parsedUrl.searchParams.get("id")); // "123"

URL の toString() メソッドは href プロパティの値を返すだけなので、コンストラクターを使用して URL を直接に正規化およびエンコードできます。

const response = await fetch(
  new URL("http://www.example.com/démonstration.html"),
);

仕様書

Specification
URL # url

URL