URL API は URL 標準のコンポーネントであり、有効なUniform Resource Locator の構成要素と URL にアクセスして操作する API を定義します。 URL 標準は、ドメイン、ホスト、IP アドレスなどの概念も定義し、ウェブフォームのコンテンツをキー/値のペアのセットとして送信するために使用される従来のapplication/x-www-form-urlencodedMIME タイプを標準的な方法で記述しようとします。

概念と使用方法

URL 標準の大部分は、URL の定義と、それがどのように構造化および解析されるかによって構成されます。 また、ネットワーク上のコンピューターのアドレス指定に関連するさまざまな用語の定義も取り上げており、IP アドレスと DOM アドレスを解析するアルゴリズムが指定されています。 ほとんどの開発者にとってより興味深いのは、API 自体です。

URL のコンポーネントへのアクセス

所与の URL のURL オブジェクトを作成すると、URL が構文解析され、そのプロパティを介して構成部分にすばやくアクセスできます。

let addr = new URL("https://developer.mozilla.org/ja/docs/Web/API/URL_API");let host = addr.host;let path = addr.pathname;

上記のスニペットは、今読んでいる記事のURL オブジェクトを作成し、host プロパティとpathname プロパティを取得します。 この場合、これらの文字列はそれぞれdeveloper.mozilla.org と/ja/docs/Web/API/URL_API です。

URL の変更

URL のほとんどのプロパティは設定可能です。 それらに新しい値を書き込んで、オブジェクトが表す URL を変更できます。 例えば、URL を作成してそのユーザー名を設定するには、次のようにします。

let myUsername = "someguy";let addr = new URL("https://example.com/login");addr.username = myUsername;

username の値を設定すると、そのプロパティの値が設定されるだけでなく、URL 全体が更新されます。 上記のコードスニペットを実行した後、href によって返される値はhttps://someguy@example.com/login です。 これは、書き込み可能なプロパティのいずれにも当てはまります。

クエリー

URL のsearch プロパティには、URL のクエリー文字列部分が含まれます。 例えば、URL がhttps://example.com/login?user=someguy&page=news の場合、search プロパティの値は?user=someguy&page=news です。URLSearchParams オブジェクトのget() メソッドを使用して、個々の引数の値を検索することもできます。

let addr = new URL("https://example.com/login?user=someguy&page=news");try {  loginUser(addr.searchParams.get("user"));  gotoPage(addr.searchParams.get("page"));} catch (err) {  showErrorMessage(err);}

例えば、上記のスニペットでは、ユーザー名と対象のページをクエリーから取得し、サイトのコードで使用される適切な関数に渡してログインし、サイト内の目的の宛先にユーザーを案内します。

URLSearchParams 内の他の関数を使用すると、キーに属する値を変更したり、キーとその値を追加および削除したり、引数のリストをソートしたりすることができます。

インターフェイス

URL API は単純な API で、それに対するインターフェイスは次の 2 つだけです。

URL

URL の解釈、構築、正規化、エンコードに使用することができます。

URLSearchParams

URL のクエリー文字列で作業するユーティリティメソッドを定義します。

例

URL に含まれる引数の処理は手動でもきますが、URL オブジェクトを作成してそれを行う方がはるかに簡単です。 以下のfillTableWithParameters() 関数は、<table> を表すHTMLTableElement オブジェクトを入力として受け取ります。 引数で見つかった各キーに対応する行が表に追加され、最初の列にはキーの名前が含まれ、2 番目の列には値が含まれます。

表を生成する前にURLSearchParams.sort() を呼び出して引数リストをソートしていることに注意してください。

function fillTableWithParameters(tbl) {  const url = new URL(document.location.href);  url.searchParams.sort();  const keys = url.searchParams.keys();  for (const key of keys) {    const val = url.searchParams.get(key);    const row = document.createElement("tr");    const cell1 = document.createElement("td");    cell1.innerText = key;    row.appendChild(cell1);    const cell2 = document.createElement("td");    cell2.innerText = val;    row.appendChild(cell2);    tbl.appendChild(row);  }}

この例の動作するバージョンはGlitch にあります。 ページを読み込むときに URL に引数を追加するだけで、表に表示されます。 例えば、https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable を試してください。

仕様書

ブラウザーの互換性

api.URL

api.URLSearchParams

関連情報

• フェッチ API
• CSS<url_value> 型
• encodeURI()
• encodeURIComponent()