URL API

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

URL の概念と使用方法

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

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

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

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

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

URL の変更

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

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

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

クエリー

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

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

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

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

URL API インターフェイス

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

仕様の古いバージョンには URLUtilsReadOnly と呼ばれるインターフェイスが含まれていましたが、これはその後 WorkerLocation インターフェイスに統合されました。

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

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

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

この例の働くバージョンは Glitch にあります。 ページをロードするときに URL にパラメーターを追加するだけで、表に表示されます。 例えば、https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable を試してください。

仕様書

仕様書 状態 備考
URL 現行の標準 初回定義

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
URLChrome 完全対応 32
完全対応 32
完全対応 19
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Edge 完全対応 12Firefox 完全対応 19
補足
完全対応 19
補足
補足 Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
補足 To use it from chrome code, JSM and Bootstrap scope, you have to import it with Cu.importGlobalProperties(['URL']);.
IE 完全対応 10Opera 完全対応 19
完全対応 19
完全対応 15
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Safari 完全対応 7
完全対応 7
完全対応 6
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
WebView Android 完全対応 4.4
完全対応 4.4
完全対応 4
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Chrome Android 完全対応 32
完全対応 32
完全対応 25
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Firefox Android 完全対応 19
補足
完全対応 19
補足
補足 Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
補足 To use it from chrome code, JSM and Bootstrap scope, you have to import it with Cu.importGlobalProperties(['URL']);.
Opera Android 完全対応 19
完全対応 19
完全対応 14
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Safari iOS 完全対応 7
完全対応 7
完全対応 6
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
Samsung Internet Android 完全対応 2.0
完全対応 2.0
完全対応 1.5
接頭辞付き
接頭辞付き webkit のベンダー接頭辞が必要
URL() constructorChrome 完全対応 19Edge 完全対応 12Firefox 完全対応 26IE 未対応 なしOpera 完全対応 15Safari 完全対応 6WebView Android 完全対応 ≤37Chrome Android 完全対応 25Firefox Android 完全対応 26Opera Android 完全対応 14Safari iOS 完全対応 6Samsung Internet Android 完全対応 1.5
createObjectURL
実験的
Chrome 完全対応 19Edge 完全対応 12Firefox 完全対応 19
補足
完全対応 19
補足
補足 createObjectURL() is no longer available within the context of a ServiceWorker.
IE 完全対応 10
補足
完全対応 10
補足
補足 If the underlying object does not have a content type set, using this URL as the src of an img tag fails intermittently with error DOM7009.
Opera 完全対応 15Safari 完全対応 6WebView Android 完全対応 ありChrome Android 完全対応 25Firefox Android 完全対応 19
補足
完全対応 19
補足
補足 createObjectURL() is no longer available within the context of a ServiceWorker.
Opera Android 完全対応 14Safari iOS 完全対応 6Samsung Internet Android 完全対応 1.5
hashChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 22IE 未対応 なしOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 22Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
hostChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 22IE 未対応 なしOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 22Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
hostnameChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 22IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 22Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
hrefChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 22IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 22Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
originChrome 完全対応 32Edge 完全対応 12Firefox 完全対応 26
完全対応 26
未対応 26 — 49
補足
補足 Results for URL using the blob scheme incorrectly returned null.
IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ≤37Chrome Android 完全対応 32Firefox Android 完全対応 26
完全対応 26
未対応 26 — 49
補足
補足 Results for URL using the blob scheme incorrectly returned null.
Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 6.0
passwordChrome 完全対応 32Edge 完全対応 12Firefox 完全対応 26IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ≤37Chrome Android 完全対応 32Firefox Android 完全対応 26Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 6.0
pathnameChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 53
完全対応 53
未対応 22 — 53
補足
補足 pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 53
完全対応 53
未対応 22 — 53
補足
補足 pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
portChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 22IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 22Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
protocolChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 22IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 22Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
revokeObjectURL
実験的
Chrome 完全対応 19Edge 完全対応 12Firefox 完全対応 19
補足
完全対応 19
補足
補足 revokeObjectURL() is no longer available within the context of a ServiceWorker.
IE 完全対応 10Opera 完全対応 15Safari 完全対応 6WebView Android 完全対応 ≤37Chrome Android 完全対応 25Firefox Android 完全対応 19
補足
完全対応 19
補足
補足 revokeObjectURL() is no longer available within the context of a ServiceWorker.
Opera Android 完全対応 14Safari iOS 完全対応 6Samsung Internet Android 完全対応 1.5
searchChrome 完全対応 ありEdge 完全対応 13Firefox 完全対応 53
完全対応 53
未対応 22 — 53
補足
補足 pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 53
完全対応 53
未対応 22 — 53
補足
補足 pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
searchParamsChrome 完全対応 51Edge 完全対応 17Firefox 完全対応 29IE 未対応 なしOpera 完全対応 38Safari 完全対応 10WebView Android 完全対応 51Chrome Android 完全対応 51Firefox Android 完全対応 29Opera Android 完全対応 41Safari iOS 完全対応 10Samsung Internet Android 完全対応 5.0
toJSONChrome 完全対応 71Edge 完全対応 17Firefox 完全対応 54IE 未対応 なしOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 71Chrome Android 完全対応 71Firefox Android 完全対応 54Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 10.0
toStringChrome 完全対応 19Edge 完全対応 17Firefox 完全対応 54IE 未対応 なしOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ≤37Chrome Android 完全対応 25Firefox Android 完全対応 54Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 6.0
usernameChrome 完全対応 32Edge 完全対応 12Firefox 完全対応 26IE 未対応 なしOpera 完全対応 ありSafari 完全対応 10WebView Android 完全対応 ≤37Chrome Android 完全対応 32Firefox Android 完全対応 26Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 6.0

凡例

完全対応  
完全対応
未対応  
未対応
実験的。動作が変更される可能性があります。
実験的。動作が変更される可能性があります。
実装ノートを参照してください。
実装ノートを参照してください。
使用するには、ベンダー接頭辞または異なる名前が必要です。
使用するには、ベンダー接頭辞または異なる名前が必要です。

関連情報