URL

[安定版: 2 - 安定版]

ソースコード: lib/url.js

node:url モジュールは、URL の解決と解析のためのユーティリティを提供します。以下の方法でアクセスできます。

ESMCJS

import url from 'node:url'

const url = require('node:url')

URL 文字列と URL オブジェクト

URL 文字列は、複数の意味のあるコンポーネントを含む構造化された文字列です。解析されると、これらのコンポーネントそれぞれに対応するプロパティを含む URL オブジェクトが返されます。

node:url モジュールは、URL を操作するための 2 つの API を提供します。1 つは Node.js 固有のレガシー API で、もう 1 つは Web ブラウザで使用されているのと同じ WHATWG URL 標準を実装する新しい API です。

WHATWG API とレガシー API の比較を以下に示します。URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash' の上に、レガシーな url.parse() が返すオブジェクトのプロパティを示します。その下に、WHATWG の URL オブジェクトのプロパティを示します。

WHATWG URL の origin プロパティには protocol と host が含まれますが、username や password は含まれません。

text

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│          │  │          │          │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
( ""行のスペースは無視してください。書式設定のためだけに存在します。)

WHATWG API を使用した URL 文字列の解析:

const myURL = new URL('https://user::8080/p/a/t/h?query=string#hash')

レガシー API を使用した URL 文字列の解析:

ESMCJS

import url from 'node:url'
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

const url = require('node:url')
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

コンポーネントから URL を構築し、構築された文字列を取得する

WHATWG URL は、プロパティセッターまたはテンプレートリテラル文字列を使用して、コンポーネントから構築できます。

const myURL = new URL('https://example.org')
myURL.pathname = '/a/b/c'
myURL.search = '?d=e'
myURL.hash = '#fgh'

const pathname = '/a/b/c'
const search = '?d=e'
const hash = '#fgh'
const myURL = new URL(`https://example.org${pathname}${search}${hash}`)

構築された URL 文字列を取得するには、hrefプロパティアクセサを使用します。

console.log(myURL.href)

WHATWG URL API

クラス: `URL`

[履歴]

バージョン	変更
v10.0.0	このクラスはグローバルオブジェクトで使用可能になりました。
v7.0.0, v6.13.0	追加：v7.0.0, v6.13.0

WHATWG URL 標準に従って実装された、ブラウザと互換性のあるURLクラス。解析された URL の例は、標準自体にあります。URLクラスはグローバルオブジェクトでも使用できます。

ブラウザの慣例に従って、URLオブジェクトのプロパティはすべて、オブジェクト自体へのデータプロパティではなく、クラスプロトタイプ上のゲッターとセッターとして実装されています。したがって、レガシーurlObjectとは異なり、URLオブジェクトのプロパティに対してdeleteキーワードを使用しても（例：delete myURL.protocol、delete myURL.pathnameなど）、効果はありませんが、trueを返します。

`new URL(input[, base])`

[履歴]

バージョン	変更
v20.0.0, v18.17.0	ICU の要件が削除されました。

input <string> 解析する絶対または相対入力 URL。inputが相対的な場合、baseが必要です。inputが絶対的な場合、baseは無視されます。inputが文字列でない場合、まず文字列に変換されます。
base <string> inputが絶対でない場合に解決する基準 URL。baseが文字列でない場合、まず文字列に変換されます。

inputをbaseを基準に解析して、新しいURLオブジェクトを作成します。baseが文字列として渡された場合、new URL(base)と等価に解析されます。

const myURL = new URL('/foo', 'https://example.org/')
// https://example.org/foo

URL コンストラクタは、グローバルオブジェクトのプロパティとしてアクセスできます。組み込みの url モジュールからインポートすることもできます。

ESMCJS

import { URL } from 'node:url'
console.log(URL === globalThis.URL) // 'true'を出力します。

console.log(URL === require('node:url').URL) // 'true'を出力します。

inputまたはbaseが有効な URL でない場合、TypeErrorがスローされます。与えられた値は文字列に変換する試みがなされます。例えば：

const myURL = new URL({ toString: () => 'https://example.org/' })
// https://example.org/

inputのホスト名内に表示される Unicode 文字は、Punycodeアルゴリズムを使用して ASCII に変換されます。

const myURL = new URL('https://測試')
// https://xn--g6w251d/

inputが絶対 URL であるかどうかが事前に不明であり、baseが提供されている場合は、URLオブジェクトのoriginが期待どおりであることを検証することをお勧めします。

let myURL = new URL('http://Example.com/', 'https://example.org/')
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/')
// https://example.com/

myURL = new URL('foo://Example.com/', 'https://example.org/')
// foo://Example.com/

myURL = new URL('http:Example.com/', 'https://example.org/')
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/')
// https://example.org/Example.com/

myURL = new URL('foo:Example.com/', 'https://example.org/')
// foo:Example.com/

`url.hash`

<string>

URL のフラグメント部分を取得および設定します。

const myURL = new URL('https://example.org/foo#bar')
console.log(myURL.hash)
// #barを出力

myURL.hash = 'baz'
console.log(myURL.href)
// https://example.org/foo#bazを出力

hashプロパティに代入された値に含まれる無効な URL 文字は、パーセントエンコードされます。パーセントエンコードする文字の選択は、url.parse()およびurl.format()メソッドが生成するものと多少異なる場合があります。

`url.host`

<string>

URL のホスト部分を取得および設定します。

const myURL = new URL('https://example.org:81/foo')
console.log(myURL.host)
// example.org:81を出力

myURL.host = 'example.com:82'
console.log(myURL.href)
// https://example.com:82/fooを出力

hostプロパティに代入された無効なホスト値は無視されます。

`url.hostname`

<string>

URL のホスト名部分を取得および設定します。url.hostとurl.hostnameの主な違いは、url.hostnameにはポートが含まれていないことです。

const myURL = new URL('https://example.org:81/foo')
console.log(myURL.hostname)
// example.orgを出力

// ホスト名の設定はポートを変更しません
myURL.hostname = 'example.com'
console.log(myURL.href)
// https://example.com:81/fooを出力

// ホスト名とポートを変更するにはmyURL.hostを使用します
myURL.host = 'example.org:82'
console.log(myURL.href)
// https://example.org:82/fooを出力

hostnameプロパティに代入された無効なホスト名値は無視されます。

`url.href`

<string>

シリアル化された URL を取得および設定します。

const myURL = new URL('https://example.org/foo')
console.log(myURL.href)
// https://example.org/fooを出力

myURL.href = 'https://example.com/bar'
console.log(myURL.href)
// https://example.com/barを出力

hrefプロパティの値を取得することは、url.toString()を呼び出すことと同等です。

このプロパティの値に新しい値を設定することは、new URL(value)を使用して新しいURLオブジェクトを作成することと同等です。URLオブジェクトのプロパティはそれぞれ変更されます。

hrefプロパティに代入された値が無効な URL の場合、TypeErrorがスローされます。

`url.origin`

[履歴]

バージョン	変更点
v15.0.0	スキーム "gopher" はもはや特別なものではなく、`url.origin` はそれに対して `'null'` を返すようになりました。

<string>

URL のオリジンの読み取り専用のシリアライゼーションを取得します。

const myURL = new URL('https://example.org/foo/bar?baz')
console.log(myURL.origin)
// https://example.org と出力

const idnURL = new URL('https://測試')
console.log(idnURL.origin)
// https://xn--g6w251d と出力

console.log(idnURL.hostname)
// xn--g6w251d と出力

`url.password`

<string>

URL のパスワード部分を取得および設定します。

const myURL = new URL('https://abc:')
console.log(myURL.password)
// xyz と出力

myURL.password = '123'
console.log(myURL.href)
// https://abc:/ と出力

password プロパティに割り当てられた値に含まれる無効な URL 文字は、/api/url#percent-encoding-in-urlsでパーセントエンコードされます。パーセントエンコードする文字の選択は、url.parse()メソッドとurl.format()メソッドが生成するものとは多少異なる場合があります。

`url.pathname`

<string>

URL のパス部分を取得および設定します。

const myURL = new URL('https://example.org/abc/xyz?123')
console.log(myURL.pathname)
// /abc/xyz と出力

myURL.pathname = '/abcdef'
console.log(myURL.href)
// https://example.org/abcdef?123 と出力

pathname プロパティに割り当てられた値に含まれる無効な URL 文字は、/api/url#percent-encoding-in-urlsでパーセントエンコードされます。パーセントエンコードする文字の選択は、url.parse()メソッドとurl.format()メソッドが生成するものとは多少異なる場合があります。

`url.port`

[履歴]

バージョン	変更
v15.0.0	スキーム "gopher" は特別なものでなくなりました。

<string>

URL のポート部分を取得および設定します。

ポート値は、数値、または0から65535（を含む）の範囲の数値を含む文字列です。protocolが与えられたURLオブジェクトのデフォルトポートに値を設定すると、port値は空文字列('')になります。

ポート値は空文字列にすることができ、その場合はプロトコル/スキームによってポートが決まります。

プロトコル	ポート
"ftp"	21
"file"
"http"	80
"https"	443
"ws"	80
"wss"	443

ポートに値を代入すると、その値は最初に.toString()を使用して文字列に変換されます。

その文字列が無効だが数値で始まっている場合、先頭の数値がportに代入されます。その数値が上記の範囲外にある場合は無視されます。

const myURL = new URL('https://example.org:8888')
console.log(myURL.port)
// 8888と出力

// デフォルトポートは自動的に空文字列に変換されます
// (HTTPSプロトコルのデフォルトポートは443です)
myURL.port = '443'
console.log(myURL.port)
// 空文字列を出力
console.log(myURL.href)
// https://example.org/と出力

myURL.port = 1234
console.log(myURL.port)
// 1234と出力
console.log(myURL.href)
// https://example.org:1234/と出力

// 完全無効なポート文字列は無視されます
myURL.port = 'abcd'
console.log(myURL.port)
// 1234と出力

// 先頭の数値はポート番号として扱われます
myURL.port = '5678abcd'
console.log(myURL.port)
// 5678と出力

// 整数ではないものは切り捨てられます
myURL.port = 1234.5678
console.log(myURL.port)
// 1234と出力

// 科学表記で表されていない範囲外の数は無視されます。
myURL.port = 1e10 // 10000000000, 以下のように範囲チェックされます
console.log(myURL.port)
// 1234と出力

浮動小数点数や科学表記の数値など、小数点を含む数値も、この規則の例外ではありません。小数点までの先頭の数値は、有効であれば URL のポートとして設定されます。

myURL.port = 4.567e21
console.log(myURL.port)
// 4と出力（'4.567e21'の先頭の数値であるため）

`url.protocol`

<string>

URL のプロトコル部分を取得および設定します。

const myURL = new URL('https://example.org')
console.log(myURL.protocol)
// https:と出力

myURL.protocol = 'ftp'
console.log(myURL.href)
// ftp://example.org/と出力

protocolプロパティに無効な URL プロトコル値を代入しても無視されます。

特殊なスキーム

[履歴]

バージョン	変更点
v15.0.0	"gopher"スキームは、もはや特別なスキームではありません。

WHATWG URL 標準では、いくつかの URL プロトコルスキームが、解析とシリアライズの方法において特殊であると見なされています。これらの特殊なプロトコルのいずれかを使用して URL を解析する場合、url.protocolプロパティは別の特殊なプロトコルに変更できますが、非特殊なプロトコルに変更することはできません。その逆も同様です。

例えば、「http」から「https」への変更は機能します。

const u = new URL('http://example.org')
u.protocol = 'https'
console.log(u.href)
// https://example.org/

しかし、「http」から仮説上の「fish」プロトコルへの変更は機能しません。新しいプロトコルは特殊ではないためです。

const u = new URL('http://example.org')
u.protocol = 'fish'
console.log(u.href)
// http://example.org/

同様に、非特殊なプロトコルから特殊なプロトコルへの変更も許可されません。

const u = new URL('fish://example.org')
u.protocol = 'http'
console.log(u.href)
// fish://example.org

WHATWG URL 標準によると、特殊なプロトコルスキームはftp、file、http、https、ws、wssです。

`url.search`

<string>

URL のシリアライズされたクエリ部分を取得および設定します。

const myURL = new URL('https://example.org/abc?123')
console.log(myURL.search)
// ?123と出力

myURL.search = 'abc=xyz'
console.log(myURL.href)
// https://example.org/abc?abc=xyzと出力

searchプロパティに代入された値に含まれる無効な URL 文字は、パーセントエンコードされます。パーセントエンコードする文字の選択は、url.parse()メソッドとurl.format()メソッドが生成するものと多少異なる場合があります。

`url.searchParams`

<URLSearchParams>

URL のクエリパラメータを表すURLSearchParamsオブジェクトを取得します。このプロパティは読み取り専用ですが、提供されるURLSearchParamsオブジェクトを使用して URL インスタンスを変更できます。URL のクエリパラメータ全体を置き換えるには、url.searchセッターを使用します。詳細はURLSearchParamsのドキュメントを参照してください。

.searchParamsを使用してURLを変更する際には注意が必要です。WHATWG 仕様によると、URLSearchParamsオブジェクトは、どの文字をパーセントエンコードするかを決定するために異なるルールを使用するためです。たとえば、URLオブジェクトは ASCII のチルダ文字(~)をパーセントエンコードしませんが、URLSearchParamsは常にエンコードします。

const myURL = new URL('https://example.org/abc?foo=~bar')

console.log(myURL.search) // ?foo=~barが出力されます

// searchParamsを介してURLを変更します…
myURL.searchParams.sort()

console.log(myURL.search) // ?foo=%7Ebarが出力されます

`url.username`

<string>

URL のユーザー名部分を取得および設定します。

const myURL = new URL('https://abc:')
console.log(myURL.username)
// abcが出力されます

myURL.username = '123'
console.log(myURL.href)
// https://123:/が出力されます

usernameプロパティに割り当てられた値に含まれる無効な URL 文字は、パーセントエンコードされます。どの文字をパーセントエンコードするかの選択は、url.parse()とurl.format()メソッドが生成するものとは多少異なる場合があります。

`url.toString()`

戻り値: <string>

URLオブジェクトのtoString()メソッドは、シリアル化された URL を返します。返される値はurl.hrefとurl.toJSON()の値と同じです。

`url.toJSON()`

追加日：v7.7.0, v6.13.0

戻り値: <string>

URLオブジェクトのtoJSON()メソッドは、シリアライズされた URL を返します。返される値は、url.hrefとurl.toString()の値と等価です。

このメソッドは、JSON.stringify()を使用してURLオブジェクトがシリアライズされると自動的に呼び出されます。

const myURLs = [new URL('https://www.example.com'), new URL('https://test.example.org')]
console.log(JSON.stringify(myURLs))
// ["https://www.example.com/","https://test.example.org/"]が出力されます

`URL.createObjectURL(blob)`

追加日：v16.7.0

[安定性: 1 - 実験的]

安定性: 1 安定性: 1 - 実験的

blob <Blob>
戻り値: <string>

与えられた <Blob>オブジェクトを表す'blob:nodedata:...' URL 文字列を作成し、後でBlobを取得するために使用できます。

const { Blob, resolveObjectURL } = require('node:buffer')

const blob = new Blob(['hello'])
const id = URL.createObjectURL(blob)

// 後で…

const otherBlob = resolveObjectURL(id)
console.log(otherBlob.size)

登録された <Blob>によって保存されたデータは、URL.revokeObjectURL()が呼び出されて削除されるまでメモリに保持されます。

Blobオブジェクトは現在のスレッド内で登録されます。ワーカースレッドを使用している場合、1 つのワーカー内で登録されたBlobオブジェクトは、他のワーカーまたはメインスレッドでは使用できません。

`URL.revokeObjectURL(id)`

追加日：v16.7.0

[安定性: 1 - 実験的]

安定性: 1 安定性: 1 - 実験的

id <string> 以前のURL.createObjectURL()呼び出しによって返された'blob:nodedata:... URL 文字列。

指定された ID で識別される保存された <Blob>を削除します。登録されていない ID の削除を試行しても、何も起こりません。

`URL.canParse(input[, base])`

追加日時: v19.9.0, v18.17.0

input <string> 解析する絶対または相対入力 URL。inputが相対的な場合、baseが必要です。inputが絶対的な場合、baseは無視されます。inputが文字列でない場合は、最初に文字列に変換されます。
base <string> inputが絶対的でない場合に解決するために使用するベース URL。baseが文字列でない場合は、最初に文字列に変換されます。
戻り値: <boolean>

baseを基準としたinputがURLとして解析できるかどうかを確認します。

const isValid = URL.canParse('/foo', 'https://example.org/') // true

const isNotValid = URL.canParse('/foo') // false

`URL.parse(input[, base])`

追加日時: v22.1.0

input <string> 解析する絶対または相対入力 URL。inputが相対的な場合、baseが必要です。inputが絶対的な場合、baseは無視されます。inputが文字列でない場合は、最初に文字列に変換されます。
base <string> inputが絶対的でない場合に解決するために使用するベース URL。baseが文字列でない場合は、最初に文字列に変換されます。
戻り値: <URL> | <null>

文字列を URL として解析します。baseが指定されている場合、非絶対的なinput URL を解決するためのベース URL として使用されます。inputが無効な場合はnullを返します。

Class: `URLSearchParams`

[履歴]

バージョン	変更
v10.0.0	このクラスはグローバルオブジェクトで使用可能になりました。
v7.5.0, v6.13.0	追加: v7.5.0, v6.13.0

URLSearchParams API は、URLのクエリ文字列への読み書きアクセスを提供します。URLSearchParamsクラスは、以下の 4 つのコンストラクタのいずれかを使用してスタンドアロンでも使用できます。URLSearchParamsクラスはグローバルオブジェクトでも使用できます。

WHATWG のURLSearchParamsインターフェースとquerystringモジュールは同様の目的を持ちますが、querystringモジュールの目的はより一般的であり、区切り文字（&と=）のカスタマイズを許可します。一方、この API は URL クエリ文字列専用に設計されています。

const myURL = new URL('https://example.org/?abc=123')
console.log(myURL.searchParams.get('abc'))
// 123が出力されます

myURL.searchParams.append('abc', 'xyz')
console.log(myURL.href)
// https://example.org/?abc=123&abc=xyzが出力されます

myURL.searchParams.delete('abc')
myURL.searchParams.set('a', 'b')
console.log(myURL.href)
// https://example.org/?a=bが出力されます

const newSearchParams = new URLSearchParams(myURL.searchParams)
// 上記は以下と同等です
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c')
console.log(myURL.href)
// https://example.org/?a=bが出力されます
console.log(newSearchParams.toString())
// a=b&a=cが出力されます

// newSearchParams.toString()は暗黙的に呼び出されます
myURL.search = newSearchParams
console.log(myURL.href)
// https://example.org/?a=b&a=cが出力されます
newSearchParams.delete('a')
console.log(myURL.href)
// https://example.org/?a=b&a=cが出力されます

`new URLSearchParams()`

新しい空のURLSearchParamsオブジェクトをインスタンス化します。

`new URLSearchParams(string)`

string <string> クエリ文字列

stringをクエリ文字列として解析し、それを用いて新しいURLSearchParamsオブジェクトをインスタンス化します。先頭の'?'は存在する場合でも無視されます。

let params

params = new URLSearchParams('user=abc&query=xyz')
console.log(params.get('user'))
// 'abc'が出力されます
console.log(params.toString())
// 'user=abc&query=xyz'が出力されます

params = new URLSearchParams('?user=abc&query=xyz')
console.log(params.toString())
// 'user=abc&query=xyz'が出力されます

`new URLSearchParams(obj)`

追加日: v7.10.0, v6.13.0

obj <Object> 鍵と値のペアのコレクションを表すオブジェクト

クエリハッシュマップを使用して新しいURLSearchParamsオブジェクトをインスタンス化します。objのプロパティのキーと値は常に文字列に変換されます。

querystringモジュールとは異なり、配列値の形式の重複キーは許可されません。配列はarray.toString()を使用して文字列化されます。これは、単にすべての配列要素をコンマで結合します。

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
})
console.log(params.getAll('query'))
// [ 'first,second' ]が出力されます
console.log(params.toString())
// 'user=abc&query=first%2Csecond'が出力されます

`new URLSearchParams(iterable)`

追加日: v7.10.0, v6.13.0

iterable <Iterable> 要素がキーと値のペアである反復可能なオブジェクト

Mapのコンストラクタと同様の方法で、反復可能なマップを使用して新しいURLSearchParamsオブジェクトをインスタンス化します。iterableはArrayまたは任意の反復可能なオブジェクトにすることができます。つまり、iterableは別のURLSearchParamsにすることができ、その場合、コンストラクタは提供されたURLSearchParamsのクローンを作成するだけです。iterableの要素はキーと値のペアであり、それ自体が任意の反復可能なオブジェクトになることができます。

重複キーは許可されます。

let params

// 配列を使用
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
])
console.log(params.toString())
// 'user=abc&query=first&query=second'が出力されます

// Mapオブジェクトを使用
const map = new Map()
map.set('user', 'abc')
map.set('query', 'xyz')
params = new URLSearchParams(map)
console.log(params.toString())
// 'user=abc&query=xyz'が出力されます

// ジェネレータ関数を使用
function* getQueryPairs() {
  yield ['user', 'abc']
  yield ['query', 'first']
  yield ['query', 'second']
}
params = new URLSearchParams(getQueryPairs())
console.log(params.toString())
// 'user=abc&query=first&query=second'が出力されます

// 各キーと値のペアには正確に2つの要素が必要です
new URLSearchParams([['user', 'abc', 'error']])
// TypeError [ERR_INVALID_TUPLE]がスローされます:
//        各クエリペアは反復可能な[name, value]タプルでなければなりません

`urlSearchParams.append(name, value)`

name <string>
value <string>

クエリ文字列に新しい名前と値のペアを追加します。

`urlSearchParams.delete(name[, value])`

[履歴]

バージョン	変更内容
v20.2.0, v18.18.0	オプションの`value`引数のサポートを追加

name <string>
value <string>

valueが指定されている場合、nameがnameでvalueがvalueであるすべての名前と値のペアを削除します。

valueが指定されていない場合、nameがnameであるすべての名前と値のペアを削除します。

`urlSearchParams.entries()`

戻り値: <Iterator>

クエリ内の各名前と値のペアに対する ES6 Iteratorを返します。イテレーターの各項目は JavaScript Arrayです。Arrayの最初の項目はname、2 番目の項目はvalueです。

urlSearchParams[@@iterator]()のエイリアスです。

`urlSearchParams.forEach(fn[, thisArg])`

[履歴]

バージョン	変更内容
v18.0.0	無効なコールバックを`fn`引数に渡すと、`ERR_INVALID_CALLBACK`ではなく`ERR_INVALID_ARG_TYPE`がスローされるようになりました。

fn <Function> クエリ内の各名前と値のペアに対して呼び出されます
thisArg <Object> fnが呼び出されるときのthis値として使用されます

クエリ内の各名前と値のペアを反復処理し、指定された関数を呼び出します。

const myURL = new URL('https://example.org/?a=b&c=d')
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams)
})
// 出力：
//   a b true
//   c d true

`urlSearchParams.get(name)`

name <string>
戻り値: <string> | <null> nameと一致する名前と値のペアが存在しない場合、nullを返します。

nameと一致する最初の名前と値のペアの値を返します。そのようなペアが存在しない場合は、nullを返します。

`urlSearchParams.getAll(name)`

name <string>
戻り値: <string[]>

nameと一致する名前と値のペアのすべての値を返します。そのようなペアが存在しない場合は、空の配列を返します。

`urlSearchParams.has(name[, value])`

[履歴]

バージョン	変更
v20.2.0, v18.18.0	オプションの`value`引数のサポートを追加

name <string>
value <string>
戻り値: <boolean>

nameとオプションのvalue引数に基づいて、URLSearchParamsオブジェクトにキーと値のペアが含まれているかどうかを確認します。

valueが指定されている場合、nameとvalueが同じ名前と値のペアが存在するときにtrueを返します。

valueが指定されていない場合、nameと一致する名前と値のペアが少なくとも 1 つ存在する場合にtrueを返します。

`urlSearchParams.keys()`

戻り値: <Iterator>

各名前と値のペアの名前を反復処理する ES6 Iteratorを返します。

const params = new URLSearchParams('foo=bar&foo=baz')
for (const name of params.keys()) {
  console.log(name)
}
// 出力:
//   foo
//   foo

`urlSearchParams.set(name, value)`

name <string>
value <string>

URLSearchParamsオブジェクトにおいて、nameに関連付けられた値をvalueに設定します。nameと同じ名前を持つ既存の名前と値のペアがある場合、そのようなペアの最初の値をvalueに設定し、他のすべてのペアを削除します。存在しない場合は、名前と値のペアをクエリ文字列に追加します。

const params = new URLSearchParams()
params.append('foo', 'bar')
params.append('foo', 'baz')
params.append('abc', 'def')
console.log(params.toString())
// foo=bar&foo=baz&abc=defと出力

params.set('foo', 'def')
params.set('xyz', 'opq')
console.log(params.toString())
// foo=def&abc=def&xyz=opqと出力

`urlSearchParams.size`

追加されたバージョン: v19.8.0, v18.16.0

パラメータエントリの総数。

`urlSearchParams.sort()`

追加されたバージョン: v7.7.0, v6.13.0

既存の名前と値のペアをすべて、その名前でインプレースにソートします。ソートは安定ソートアルゴリズムを使用して行われるため、同じ名前を持つ名前と値のペア間の相対的な順序は保持されます。

このメソッドは、特にキャッシュヒット率を高めるために使用できます。

const params = new URLSearchParams('query[]=abc&type=search&query[]=123')
params.sort()
console.log(params.toString())
// query%5B%5D=abc&query%5B%5D=123&type=searchと出力

`urlSearchParams.toString()`

戻り値: <string>

必要に応じて文字をパーセントエンコードして、文字列としてシリアル化された検索パラメータを返します。

`urlSearchParams.values()`

戻り値: <Iterator>

各名前と値のペアの値に対する ES6 Iteratorを返します。

`urlSearchParams[Symbol.iterator]()`

戻り値: <Iterator>

クエリ文字列内の各名前と値のペアに対する ES6 Iteratorを返します。イテレータの各項目は JavaScript Arrayです。Arrayの最初の項目はname、2 番目の項目はvalueです。

urlSearchParams.entries()のエイリアスです。

const params = new URLSearchParams('foo=bar&xyz=baz')
for (const [name, value] of params) {
  console.log(name, value)
}
// 出力:
//   foo bar
//   xyz baz

`url.domainToASCII(domain)`

[履歴]

バージョン	変更点
v20.0.0, v18.17.0	ICU の要件が削除されました。
v7.4.0, v6.13.0	追加: v7.4.0, v6.13.0

domain <string>
戻り値: <string>

domainのPunycode ASCII シリアライゼーションを返します。domainが無効なドメインの場合、空文字列が返されます。

url.domainToUnicode()とは逆の処理を実行します。

ESMCJS

import url from 'node:url'

console.log(url.domainToASCII('español.com'))
// 出力 xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// 出力 xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// 空文字列を出力

const url = require('node:url')

console.log(url.domainToASCII('español.com'))
// 出力 xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// 出力 xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// 空文字列を出力

`url.domainToUnicode(domain)`

[履歴]

バージョン	変更点
v20.0.0, v18.17.0	ICU の要件が削除されました。
v7.4.0, v6.13.0	追加: v7.4.0, v6.13.0

domain <string>
戻り値: <string>

domainの Unicode シリアライゼーションを返します。domainが無効なドメインの場合、空文字列が返されます。

url.domainToASCII()とは逆の処理を実行します。

ESMCJS

import url from 'node:url'

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// 出力 español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// 出力 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// 空文字列を出力

const url = require('node:url')

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// 出力 español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// 出力 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// 空文字列を出力

`url.fileURLToPath(url[, options])`

[履歴]

バージョン	変更内容
v22.1.0, v20.13.0	`options`引数を使用して`path`引数の解析方法を決定できるようになりました。
v10.12.0	追加: v10.12.0

url <URL> | <string> パスに変換するファイル URL 文字列または URL オブジェクト。
options <Object>
- windows <boolean> | <undefined> pathを Windows ファイルパスとして返す場合はtrue、POSIX の場合はfalse、システムのデフォルトの場合はundefined。デフォルト: undefined。
戻り値: <string> 完全解決されたプラットフォーム固有の Node.js ファイルパス。

この関数は、パーセントエンコードされた文字の正しいデコードと、クロスプラットフォームで有効な絶対パス文字列の確保を保証します。

ESMCJS

import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // 正しくない: /C:/path/
fileURLToPath('file:///C:/path/') // 正しい:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // 正しくない: /foo.txt
fileURLToPath('file://nas/foo.txt') // 正しい:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // 正しくない: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // 正しい:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // 正しくない: /hello%20world
fileURLToPath('file:///hello world') // 正しい:   /hello world (POSIX)

const { fileURLToPath } = require('node:url')
new URL('file:///C:/path/').pathname // 正しくない: /C:/path/
fileURLToPath('file:///C:/path/') // 正しい:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // 正しくない: /foo.txt
fileURLToPath('file://nas/foo.txt') // 正しい:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // 正しくない: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // 正しい:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // 正しくない: /hello%20world
fileURLToPath('file:///hello world') // 正しい:   /hello world (POSIX)

`url.format(URL[, options])`

追加バージョン: v7.6.0

URL <URL> WHATWG URL オブジェクト
options <Object>
- auth <boolean> シリアライズされた URL 文字列にユーザー名とパスワードを含める場合はtrue、それ以外の場合はfalse。デフォルト: true。
- fragment <boolean> シリアライズされた URL 文字列にフラグメントを含める場合はtrue、それ以外の場合はfalse。デフォルト: true。
- search <boolean> シリアライズされた URL 文字列に検索クエリを含める場合はtrue、それ以外の場合はfalse。デフォルト: true。
- unicode <boolean> URL 文字列のホストコンポーネントに表示される Unicode 文字を、Punycode でエンコードするのではなく、直接エンコードする場合はtrue。デフォルト: false。
戻り値: <string>

WHATWG URLオブジェクトの URLString表現のカスタマイズ可能なシリアライゼーションを返します。

URL オブジェクトには、URL の文字列シリアライゼーションを返すtoString()メソッドとhrefプロパティの両方があります。ただし、これらは何らかの方法でカスタマイズできません。url.format(URL[, options])メソッドを使用すると、出力の基本的なカスタマイズが可能です。

ESMCJS

import url from 'node:url'
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// https://a:b@xn--g6w251d/?abc#fooを出力

console.log(myURL.toString())
// https://a:b@xn--g6w251d/?abc#fooを出力

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// 'https://測試/?abc'を出力

const url = require('node:url')
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// https://a:b@xn--g6w251d/?abc#fooを出力

console.log(myURL.toString())
// https://a:b@xn--g6w251d/?abc#fooを出力

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// 'https://測試/?abc'を出力

`url.pathToFileURL(path[, options])`

[履歴]

バージョン	変更
v22.1.0, v20.13.0	`options`引数を使用して`path`値の戻り方を決定できるようになりました。
v10.12.0	追加: v10.12.0

path <string> ファイル URL に変換するパス。
options <Object>
- windows <boolean> | <undefined> pathを Windows ファイルパスとして扱う場合はtrue、POSIX の場合はfalse、システムのデフォルトの場合はundefined。 デフォルト: undefined。
戻り値: <URL> ファイル URL オブジェクト。

この関数は、pathが絶対パスとして解決され、ファイル URL に変換する際に URL 制御文字が正しくエンコードされることを保証します。

ESMCJS

import { pathToFileURL } from 'node:url'

new URL('/foo#1', 'file:') // 正しくない: file:///foo#1
pathToFileURL('/foo#1') // 正しい:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // 正しくない: file:///some/path%.c
pathToFileURL('/some/path%.c') // 正しい:   file:///some/path%25.c (POSIX)

const { pathToFileURL } = require('node:url')
new URL(__filename) // 正しくない: エラー発生 (POSIX)
new URL(__filename) // 正しくない: C:\... (Windows)
pathToFileURL(__filename) // 正しい:   file:///... (POSIX)
pathToFileURL(__filename) // 正しい:   file:///C:/... (Windows)

new URL('/foo#1', 'file:') // 正しくない: file:///foo#1
pathToFileURL('/foo#1') // 正しい:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // 正しくない: file:///some/path%.c
pathToFileURL('/some/path%.c') // 正しい:   file:///some/path%25.c (POSIX)

`url.urlToHttpOptions(url)`

[履歴]

バージョン	変更点
v19.9.0, v18.17.0	返されるオブジェクトには、`url`引数のすべての列挙可能な固有プロパティも含まれるようになりました。
v15.7.0, v14.18.0	追加: v15.7.0, v14.18.0

url <URL> WHATWG URLオブジェクトをオプションオブジェクトに変換します。
戻り値: <Object> オプションオブジェクト
- protocol <string> 使用するプロトコル。
- hostname <string> リクエストを送信するサーバーのドメイン名または IP アドレス。
- hash <string> URL のフラグメント部分。
- search <string> URL のシリアライズされたクエリ部分。
- pathname <string> URL のパス部分。
- path <string> リクエストパス。クエリ文字列がある場合は含める必要があります。例: '/index.html?page=12'。リクエストパスに不正な文字が含まれている場合、例外がスローされます。現在、スペースのみが拒否されますが、将来的に変更される可能性があります。
- href <string> シリアライズされた URL。
- port <number> リモートサーバーのポート。
- auth <string> 基本認証、例: 'user:password'。Authorization ヘッダーを計算するために使用します。

このユーティリティ関数は、URL オブジェクトをhttp.request()およびhttps.request()API で期待される通常のオプションオブジェクトに変換します。

ESMCJS

import { urlToHttpOptions } from 'node:url'
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(urlToHttpOptions(myURL))
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

const { urlToHttpOptions } = require('node:url')
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(urlToHttpOptions(myURL))
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

従来の URL API

[履歴]

バージョン	変更
v15.13.0, v14.17.0	非推奨の取り消し。ステータスが「レガシー」に変更されました。
v11.0.0	この API は非推奨となりました。

[安定度: 3 - レガシー]

安定度: 3 安定性: 3 - レガシー: WHATWG URL API を代わりに使用してください。

従来の `urlObject`

[履歴]

バージョン	変更
v15.13.0, v14.17.0	非推奨の取り消し。ステータスが「レガシー」に変更されました。
v11.0.0	従来の URL API は非推奨です。WHATWG URL API を使用してください。

[安定度: 3 - レガシー]

安定度: 3 安定性: 3 - レガシー: WHATWG URL API を代わりに使用してください。

従来の urlObject (require('node:url').Url または import { Url } from 'node:url') は、url.parse() 関数によって作成および返されます。

`urlObject.auth`

auth プロパティは、URL のユーザー名とパスワードの部分であり、userinfo とも呼ばれます。この文字列の部分集合は、protocol と二重スラッシュ（存在する場合）の後に続き、host コンポーネントの前にあり、@ で区切られています。文字列はユーザー名のみであるか、またはコロン : で区切られたユーザー名とパスワードです。

例: 'user:pass'。

`urlObject.hash`

hash プロパティは、先頭の # 文字を含む URL のフラグメント識別子部分です。

例: '#hash'。

`urlObject.host`

host プロパティは、指定されている場合は port を含む、URL の完全な小文字のホスト部分です。

例: 'sub.example.com:8080'。

`urlObject.hostname`

hostname プロパティは、port を含まない host コンポーネントの小文字のホスト名部分です。

例: 'sub.example.com'。

`urlObject.href`

href プロパティは、protocol と host コンポーネントが小文字に変換された、解析された完全な URL 文字列です。

例: 'http://user:[email protected]:8080/p/a/t/h?query=string#hash'。

`urlObject.path`

path プロパティは、pathname と search コンポーネントの連結です。

例えば：'/p/a/t/h?query=string'。

path のデコードは行われません。

`urlObject.pathname`

pathname プロパティは、URL のパスセクション全体からなります。これは、host（port を含む）の後に続き、query または hash コンポーネントの開始前にあるもので、ASCII の疑問符（?）またはハッシュ（#）文字によって区切られます。

例えば：'/p/a/t/h'。

パス文字列のデコードは行われません。

`urlObject.port`

port プロパティは、host コンポーネントの数値ポート部分です。

例えば：'8080'。

`urlObject.protocol`

protocol プロパティは、URL の小文字の protocol スキームを識別します。

例えば：'http:'。

`urlObject.query`

query プロパティは、先頭の ASCII の疑問符（?）を除いたクエリ文字列、または querystring モジュールの parse() メソッドによって返されるオブジェクトのいずれかです。query プロパティが文字列かオブジェクトかは、url.parse() に渡される parseQueryString 引数によって決まります。

例えば：'query=string' または {'query': 'string'}。

文字列として返された場合、クエリ文字列のデコードは行われません。オブジェクトとして返された場合、キーと値の両方がデコードされます。

`urlObject.search`

search プロパティは、先頭の ASCII の疑問符（?）文字を含む、URL の「クエリ文字列」部分全体からなります。

例えば：'?query=string'。

クエリ文字列のデコードは行われません。

`urlObject.slashes`

slashes プロパティは、protocol のコロンの後に 2 つの ASCII のスラッシュ文字（/）が必要な場合に true の値を持つ boolean です。

`url.format(urlObject)`

[履歴]

バージョン	変更
v17.0.0	ホスト名の Punycode 変換によって、URL が異なる方法で再解析される可能性のある変更が導入された場合、`ERR_INVALID_URL` 例外をスローするようになりました。
v15.13.0, v14.17.0	非推奨の取り消し。ステータスが「レガシー」に変更されました。
v11.0.0	レガシー URL API は非推奨になりました。WHATWG URL API を使用してください。
v7.0.0	`file:` スキームを持つ URL は、`slashes` オプションに関係なく、常に正しい数のスラッシュを使用するようになりました。プロトコルがない場合の偽の `slashes` オプションも、常に尊重されるようになりました。
v0.1.25	追加されました: v0.1.25

[安定版: 3 - レガシー]

安定版: 3 安定性: 3 - レガシー: 代わりに WHATWG URL API を使用してください。

urlObject <Object> | <string> URL オブジェクト（url.parse() によって返されるか、またはそれ以外で構築されます）。文字列の場合、url.parse() に渡すことによってオブジェクトに変換されます。

url.format() メソッドは、urlObject から派生したフォーマットされた URL 文字列を返します。

const url = require('node:url')
url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json',
  },
})

// => 'https://example.com/some/path?page=1&format=json'

urlObject がオブジェクトまたは文字列でない場合、url.format() は TypeError をスローします。

フォーマット処理は次のように動作します。

空の新しい文字列 result が作成されます。
urlObject.protocol が文字列の場合、そのまま result に追加されます。
そうでない場合、urlObject.protocol が undefined ではなく、文字列でない場合、Error がスローされます。
ASCII コロン（: ）文字で終わらないurlObject.protocol のすべての文字列値に対して、リテラル文字列 : が result に追加されます。
次のいずれかの条件が true の場合、リテラル文字列 // が result に追加されます。
- urlObject.slashes プロパティが true です。
- urlObject.protocol は http、https、ftp、gopher、または file で始まります。
urlObject.auth プロパティの値が真であり、urlObject.host または urlObject.hostname が undefined でない場合、urlObject.auth の値は文字列に変換され、リテラル文字列 @ の後に result に追加されます。
urlObject.host プロパティが undefined の場合：
- urlObject.hostname が文字列の場合、result に追加されます。
- そうでない場合、urlObject.hostname が undefined ではなく、文字列でない場合、Error がスローされます。
- urlObject.port プロパティの値が真であり、urlObject.hostname が undefined でない場合：
- リテラル文字列 : が result に追加され、
- urlObject.port の値が文字列に変換され、result に追加されます。
そうでない場合、urlObject.host プロパティの値が真の場合、urlObject.host の値は文字列に変換され、result に追加されます。
urlObject.pathname プロパティが空でない文字列である場合：
- urlObject.pathname が ASCII のスラッシュ（/）で始まらない場合、リテラル文字列 / が result に追加されます。
- urlObject.pathname の値が result に追加されます。
そうでない場合、urlObject.pathname が undefined ではなく、文字列でない場合、Error がスローされます。
urlObject.search プロパティが undefined であり、urlObject.query プロパティが Object の場合、リテラル文字列 ? が result に追加され、その後に querystring モジュールの stringify() メソッドを呼び出して urlObject.query の値を渡した結果が続きます。
そうでない場合、urlObject.search が文字列の場合：
- urlObject.search の値が ASCII の疑問符（?）文字で始まらない場合、リテラル文字列 ? が result に追加されます。
- urlObject.search の値が result に追加されます。
そうでない場合、urlObject.search が undefined ではなく、文字列でない場合、Error がスローされます。
urlObject.hash プロパティが文字列の場合：
- urlObject.hash の値が ASCII のハッシュ（#）文字で始まらない場合、リテラル文字列 # が result に追加されます。
- urlObject.hash の値が result に追加されます。
そうでない場合、urlObject.hash プロパティが undefined ではなく、文字列でない場合、Error がスローされます。
result が返されます。

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

[履歴]

バージョン	変更点
v19.0.0, v18.13.0	ドキュメントのみの非推奨化。
v15.13.0, v14.17.0	非推奨化の取り消し。「レガシー」ステータスに変更。
v11.14.0	返される URL オブジェクトの`pathname`プロパティは、パスがなくプロトコルスキームが`ws:`または`wss:`の場合、`/`になります。
v11.0.0	レガシー URL API は非推奨になりました。WHATWG URL API を使用してください。
v9.0.0	クエリ文字列が存在しない場合、返される URL オブジェクトの`search`プロパティは`null`になります。
v0.1.25	追加：v0.1.25

[安定版: 0 - 非推奨]

安定版: 0 安定性: 0 - 非推奨: 代わりに WHATWG URL API を使用してください。

urlString <string> パースする URL 文字列。
parseQueryString <boolean> trueの場合、queryプロパティは常にquerystringモジュールのparse()メソッドによって返されるオブジェクトに設定されます。falseの場合、返される URL オブジェクトのqueryプロパティは、パースされていない、デコードされていない文字列になります。デフォルト: false。
slashesDenoteHost <boolean> trueの場合、リテラル文字列//の後、次の/の前にある最初のトークンはhostとして解釈されます。例えば、//foo/barの場合、結果は{host: 'foo', pathname: '/bar'}になり、{pathname: '//foo/bar'}にはなりません。デフォルト: false。

url.parse()メソッドは URL 文字列を受け取り、それをパースして URL オブジェクトを返します。

urlStringが文字列でない場合、TypeErrorがスローされます。

authプロパティが存在するがデコードできない場合、URIErrorがスローされます。

url.parse()は、URL 文字列をパースするための寛容な非標準アルゴリズムを使用します。ホスト名スプーフィングや、ユーザー名とパスワードの誤った処理などのセキュリティ問題を起こしやすいです。信頼できない入力には使用しないでください。url.parse()の脆弱性については CVE は発行されません。代わりにWHATWG URL API を使用してください。

`url.resolve(from, to)`

[履歴]

バージョン	変更点
v15.13.0, v14.17.0	非推奨の取り消し。ステータスが「レガシー」に変更されました。
v11.0.0	レガシー URL API は非推奨となりました。WHATWG URL API を使用してください。
v6.6.0	`from`と`to`が同じホストを参照する場合、`auth`フィールドはそのまま保持されるようになりました。
v6.0.0	`to`パラメータにホスト名が含まれる場合、`auth`フィールドはクリアされるようになりました。
v6.5.0, v4.6.2	`port`フィールドが正しくコピーされるようになりました。
v0.1.25	追加：v0.1.25

[安定版: 3 - レガシー]

安定版: 3 安定性: 3 - レガシー: WHATWG URL API を使用してください。

from <string> toが相対 URL の場合に使用するベース URL。
to <string> 解決する対象 URL。

url.resolve()メソッドは、ウェブブラウザがアンカータグを解決する方法と同様に、ベース URL を基準にして対象 URL を解決します。

const url = require('node:url')
url.resolve('/one/two/three', 'four') // '/one/two/four'
url.resolve('http://example.com/', '/one') // 'http://example.com/one'
url.resolve('http://example.com/one', '/two') // 'http://example.com/two'

WHATWG URL API を使用して同じ結果を得るには：

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'))
  if (resolvedUrl.protocol === 'resolve:') {
    // `from`は相対URLです。
    const { pathname, search, hash } = resolvedUrl
    return pathname + search + hash
  }
  return resolvedUrl.toString()
}

resolve('/one/two/three', 'four') // '/one/two/four'
resolve('http://example.com/', '/one') // 'http://example.com/one'
resolve('http://example.com/one', '/two') // 'http://example.com/two'

URL のパーセントエンコーディング

URL は、特定の範囲の文字しか含めることができません。その範囲外の文字はエンコードする必要があります。文字をどのようにエンコードするか、どの文字をエンコードするかは、URL の構造内で文字がどこに位置するかによって完全に異なります。

従来の API

従来の API では、スペース（' '）と以下の文字は、URL オブジェクトのプロパティ内で自動的にエスケープされます。

text

< > " ` \r \n \t { } | \ ^ '

例えば、ASCII スペース文字（' '）は%20としてエンコードされ、ASCII スラッシュ文字（/）は%3Cとしてエンコードされます。

WHATWG API

WHATWG URL 標準は、従来の API で使用されているものよりも、エンコードされる文字を選択する際に、より選択的で詳細なアプローチを採用しています。

WHATWG アルゴリズムは、パーセントエンコードする必要がある文字の範囲を記述する 4 つの「パーセントエンコードセット」を定義しています。

C0 制御パーセントエンコードセットには、U+0000 から U+001F（を含む）の範囲のコードポイントと、U+007E（~）より大きいすべてのコードポイントが含まれます。
フラグメントパーセントエンコードセットには、C0 制御パーセントエンコードセットと、コードポイント U+0020 SPACE、U+0022 (")、U+003C (<)、U+003E (>)、U+0060 (`)が含まれます。
パスパーセントエンコードセットには、C0 制御パーセントエンコードセットと、コードポイント U+0020 SPACE、U+0022 (")、U+0023 (#)、U+003C (<)、U+003E (>)、U+003F (?)、U+0060 (`)、U+007B ({)、U+007D (})が含まれます。
userinfo エンコードセットには、パスパーセントエンコードセットと、コードポイント U+002F (/)、U+003A (😃、U+003B (😉、U+003D (=)、U+0040 (@)、U+005B ([)から U+005E(^)、U+007C (|)が含まれます。

userinfo パーセントエンコードセットは、URL 内にエンコードされたユーザー名とパスワードにのみ使用されます。パスパーセントエンコードセットは、ほとんどの URL のパスに使用されます。フラグメントパーセントエンコードセットは、URL フラグメントに使用されます。C0 制御パーセントエンコードセットは、他のすべてのケースに加えて、特定の条件下でのホストとパスに使用されます。

ホスト名に非 ASCII 文字が現れる場合、ホスト名はPunycodeアルゴリズムを使用してエンコードされます。ただし、ホスト名は Punycode エンコード文字とパーセントエンコード文字の両方を含む可能性があります。

const myURL = new URL('https://%CF%80.example.com/foo')
console.log(myURL.href)
// https://xn--1xa.example.com/fooと出力
console.log(myURL.origin)
// https://xn--1xa.example.comと出力

URL ​

URL 文字列と URL オブジェクト ​

コンポーネントから URL を構築し、構築された文字列を取得する ​

WHATWG URL API ​

クラス: URL ​

new URL(input[, base]) ​

url.hash ​

url.host ​

url.hostname ​

url.href ​

url.origin ​

url.password ​

url.pathname ​

url.port ​

url.protocol ​

特殊なスキーム ​

url.search ​

url.searchParams ​

url.username ​

url.toString() ​

url.toJSON() ​

URL.createObjectURL(blob) ​

URL.revokeObjectURL(id) ​

URL.canParse(input[, base]) ​

URL.parse(input[, base]) ​

Class: URLSearchParams ​

new URLSearchParams() ​

new URLSearchParams(string) ​

new URLSearchParams(obj) ​

new URLSearchParams(iterable) ​

urlSearchParams.append(name, value) ​

urlSearchParams.delete(name[, value]) ​

urlSearchParams.entries() ​

urlSearchParams.forEach(fn[, thisArg]) ​

urlSearchParams.get(name) ​

urlSearchParams.getAll(name) ​

urlSearchParams.has(name[, value]) ​

urlSearchParams.keys() ​

urlSearchParams.set(name, value) ​

urlSearchParams.size ​

urlSearchParams.sort() ​

urlSearchParams.toString() ​

urlSearchParams.values() ​

urlSearchParams[Symbol.iterator]() ​

url.domainToASCII(domain) ​

url.domainToUnicode(domain) ​

url.fileURLToPath(url[, options]) ​

url.format(URL[, options]) ​

url.pathToFileURL(path[, options]) ​

url.urlToHttpOptions(url) ​

従来の URL API ​

従来の urlObject ​

urlObject.auth ​

urlObject.hash ​

urlObject.host ​

urlObject.hostname ​

urlObject.href ​

urlObject.path ​

urlObject.pathname ​

urlObject.port ​

urlObject.protocol ​

urlObject.query ​

urlObject.search ​

urlObject.slashes ​

url.format(urlObject) ​

url.parse(urlString[, parseQueryString[, slashesDenoteHost]]) ​

url.resolve(from, to) ​

URL のパーセントエンコーディング ​

従来の API ​

WHATWG API ​

URL

URL 文字列と URL オブジェクト

コンポーネントから URL を構築し、構築された文字列を取得する

WHATWG URL API

クラス: `URL`

`new URL(input[, base])`

`url.hash`

`url.host`

`url.hostname`

`url.href`

`url.origin`

`url.password`

`url.pathname`

`url.port`

`url.protocol`

特殊なスキーム

`url.search`

`url.searchParams`

`url.username`

`url.toString()`

`url.toJSON()`

`URL.createObjectURL(blob)`

`URL.revokeObjectURL(id)`

`URL.canParse(input[, base])`

`URL.parse(input[, base])`

Class: `URLSearchParams`

`new URLSearchParams()`

`new URLSearchParams(string)`

`new URLSearchParams(obj)`

`new URLSearchParams(iterable)`

`urlSearchParams.append(name, value)`

`urlSearchParams.delete(name[, value])`

`urlSearchParams.entries()`

`urlSearchParams.forEach(fn[, thisArg])`

`urlSearchParams.get(name)`

`urlSearchParams.getAll(name)`

`urlSearchParams.has(name[, value])`

`urlSearchParams.keys()`

`urlSearchParams.set(name, value)`

`urlSearchParams.size`

`urlSearchParams.sort()`

`urlSearchParams.toString()`

`urlSearchParams.values()`

`urlSearchParams[Symbol.iterator]()`

`url.domainToASCII(domain)`

`url.domainToUnicode(domain)`

`url.fileURLToPath(url[, options])`

`url.format(URL[, options])`

`url.pathToFileURL(path[, options])`

`url.urlToHttpOptions(url)`

従来の URL API

従来の `urlObject`

`urlObject.auth`

`urlObject.hash`

`urlObject.host`

`urlObject.hostname`

`urlObject.href`

`urlObject.path`

`urlObject.pathname`

`urlObject.port`

`urlObject.protocol`

`urlObject.query`

`urlObject.search`

`urlObject.slashes`

`url.format(urlObject)`

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

`url.resolve(from, to)`

URL のパーセントエンコーディング

従来の API

WHATWG API