URL: parse() 静的メソッド
URL.parse()
は URL
インターフェイスの静的メソッドで、引数で定義された URL
を表す、新たに作成された URL オブジェクトを返します。
指定されたベース URL または結果の URL が解析可能で有効な URL でない場合、null
が返されます。
これは、URL()
コンストラクターを使用することに対する、try...catch ブロック内で URL
を構築したり、 canParse()
を使用して引数を調べ、メソッドが false
を返した場合に null
を返したりする代替手段です。
構文
URL.parse(url)
URL.parse(url, base)
引数
url
-
文字列、または文字列化を持つオブジェクトで、絶対 URL または URL への相対参照を表します。
url
が相対参照の場合、base
は要求され、最終的な URL を解決するために使用されます。url
が絶対 URL の場合、指定されたbase
は結果の URL を作成するために使用されません。 base
省略可-
url
が相対 URL の場合に利用するベース URL を表す文字列です。 指定しない場合、既定ではundefined
となります。base
URL を指定すると、解決された URL は単にurl
とbase
を結合したものではありません。 親ディレクトリーおよびカレントディレクトリーへの相対参照は、base
URL のカレントディレクトリーを基準として解決されます。 ルートへの相対参照は、base
のオリジンを基準として解決されます。 詳細については、相対参照の URL への解決を参照してください。
Note:
url
およびbase
引数は、渡した値が例えばHTMLAnchorElement
やHTMLAreaElement
要素など、何であれそれぞれ文字列化されます。文字列を受け入れる他の Web API と同様です。 具体的には、どちらかの引数に既存のURL
オブジェクトを使用することができます。そのオブジェクトのhref
プロパティから文字列化されます。
返値
引数が有効な URL に解決できた場合は URL
です。そうでなければ null
です。
例
相対参照の URL への解決および URL()
コンストラクターの記事には、url
および base
値が最終的な絶対 URL に解決される方法を示す例がもっとあります(主に URL()
を使用するものですが)。
URL.parse() の使用
この例では、いくつかの異なる絶対参照値と相対参照値に対して、静的メソッド URL.parse()
を使用する方法を説明しています。
最初に、URL.parse()
メソッドに対応しているかどうかを "parse" in URL
という条件式でチェックします。
メソッドが対応している場合、絶対URL、相対参照、ベース URL、より複雑なベース URL を持つ相対参照、有効なベース URL を持つ有効な絶対 URL(これは使用されません)、およびメソッドが null
を返す不正なベース URL のチェック結果をログ出力します。
また、URL.parse()
に対応していない場合にもログ出力します。
if ("parse" in URL) {
// Absolute URL
let result = URL.parse("https://developer.mozilla.org/ja/docs");
log(`[1]: ${result.href}`);
// 相対参照を有効なベース URL へ
result = URL.parse("ja/docs", "https://developer.mozilla.org");
log(`[2]: ${result.href}`);
// 相対参照を「複雑」で有効なベース URL へ
// (スキームとドメインのみを使用して URL を解決します)
result = URL.parse(
"/different/place",
"https://developer.mozilla.org:443/some/path?id=4",
);
log(`[3]: ${result.href}`);
// 絶対 URL の引数(ベース URL は無視される)
result = URL.parse(
"https://example.org/some/docs",
"https://developer.mozilla.org",
);
log(`[4]: ${result.href}`);
// 無効なベース URL(コロンの付け忘れ)
result = URL.parse("ja/docs", "https//developer.mozilla.org");
log(`[5]: ${result}`);
} else {
log("URL.parse() に対応していません");
}
最後に、下記のコードでは、base
引数に URL
オブジェクトを渡すとことで、引数が文字列でなくてもよいことを示しています。
if ("parse" in URL) {
// URL オブジェクトとして指定されたベース URL との相対参照
result = URL.parse("/ja/docs", new URL("https://developer.mozilla.org/"));
log(`[6]: ${result.href}`);
}
それぞれのチェックを以下に表示します。
仕様書
Specification |
---|
URL Standard # dom-url-parse |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
URL()
コンストラクター: 渡された引数が不正な引数を定義している場合は例外が発生します。URL.parse()
のポリフィル がcore-js
で利用できます