new URL(input[, base])

• input <string> Абсолютный или относительный входной URL для разбора. Если input является относительным, требуется base. Если input является абсолютным, base игнорируется. Если input не является строкой, сначала он преобразуется в строку.
• base <string> Базовый URL, относительно которого выполняется разрешение, если input не является абсолютным. Если base не является строкой, сначала он преобразуется в строку.

Создает новый объект URL, разбирая input относительно base. Если base передан в виде строки, она будет разобрана так же, как new URL(base).

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

Конструктор URL доступен как свойство глобального объекта. Его также можно импортировать из встроенного модуля url:

import { URL } from 'node:url';
console.log(URL === globalThis.URL); // Prints 'true'.

console.log(URL === require('node:url').URL); // Prints 'true'.

Будет выброшено исключение TypeError, если input или base не являются допустимыми URL. Обратите внимание, что переданные значения будут преобразованы в строки. Например:

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

Символы Юникода в имени хоста input автоматически преобразуются в ASCII с помощью алгоритма Punycode.

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

Если заранее неизвестно, является ли input абсолютным URL, и передан base, рекомендуется проверить, что значение origin объекта URL соответствует ожидаемому.

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/ copy

url.hash

• Тип: <string>

Получает и задает часть URL, содержащую фрагмент.

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

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz copy

Недопустимые символы URL, включенные в значение, присвоенное свойству hash, кодируются в процентном представлении. Выбор символов для такого кодирования может несколько отличаться от результата, который дают методы url.parse() и url.format().

url.host

• Тип: <string>

Получает и задает часть URL, содержащую хост.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo copy

Недопустимые значения хоста, присвоенные свойству host, игнорируются.

url.hostname

• Тип: <string>

Получает и задает часть URL, содержащую имя хоста. Основное различие между url.host и url.hostname состоит в том, что url.hostname не включает порт.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo copy

Недопустимые значения имени хоста, присвоенные свойству hostname, игнорируются.

url.href

• Тип: <string>

Получает и задает сериализованный URL.

const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar copy

Получение значения свойства href эквивалентно вызову url.toString().

Присваивание этому свойству нового значения эквивалентно созданию нового объекта URL с помощью new URL(value). При этом изменятся все свойства объекта URL.

Если значение, присвоенное свойству href, не является допустимым URL, будет выброшено исключение TypeError.

url.origin

• Тип: <string>

Получает сериализованное представление источника URL только для чтения.

const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Prints https://example.org copy

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

console.log(idnURL.hostname);
// Prints xn--g6w251d copy

url.password

• Тип: <string>

Получает и задает часть URL, содержащую пароль.

const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/ copy

Недопустимые символы URL, включенные в значение, присвоенное свойству password, кодируются в процентном представлении. Выбор символов для такого кодирования может несколько отличаться от результата, который дают методы url.parse() и url.format().

url.pathname

• Тип: <string>

Получает и задает часть URL, содержащую путь.

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

myURL.pathname = '/abcdef';
console.log(myURL.href);
// Prints https://example.org/abcdef?123 copy

Недопустимые символы URL, включенные в значение, присвоенное свойству pathname, кодируются в процентном представлении. Выбор символов для такого кодирования может несколько отличаться от результата, который дают методы url.parse() и url.format().

url.port

• Тип: <string>

Получает и задает часть URL, содержащую порт.

Значение порта может быть числом или строкой, содержащей число в диапазоне от 0 до 65535 (включительно). Если задано значение порта по умолчанию для объектов URL с учетом protocol, значение port станет пустой строкой ('').

Значение порта может быть пустой строкой; в этом случае порт зависит от протокола/схемы:

При присваивании значения порту оно сначала будет преобразовано в строку с помощью .toString().

Если эта строка недопустима, но начинается с числа, это начальное число присваивается port. Если число выходит за указанный выше диапазон, оно игнорируется.

const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888

// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org/

myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234/

// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234

// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678

// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234

// Out-of-range numbers which are not represented in scientific notation
// will be ignored.
myURL.port = 1e10; // 10000000000, will be range-checked as described below
console.log(myURL.port);
// Prints 1234 copy

Числа с десятичной точкой, например числа с плавающей точкой или числа в экспоненциальной записи, также подпадают под это правило. Начальное число до десятичной точки будет установлено в качестве порта URL, если оно допустимо:

myURL.port = 4.567e21;
console.log(myURL.port);
// Prints 4 (because it is the leading number in the string '4.567e21') copy

url.protocol

• Тип: <string>

Получает и задает часть URL, содержащую протокол.

const myURL = new URL('https://example.org');
console.log(myURL.protocol);
// Prints https:

myURL.protocol = 'ftp';
console.log(myURL.href);
// Prints ftp://example.org/ copy

Недопустимые значения протокола URL, присвоенные свойству protocol, игнорируются.

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

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

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

url.search

• Тип: <string>

Получает и задает сериализованную часть URL, содержащую строку запроса.

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

myURL.search = 'abc=xyz';
console.log(myURL.href);
// Prints https://example.org/abc?abc=xyz copy

Любые недопустимые символы URL, встречающиеся в значении, присвоенном свойству search, будут закодированы в процентном представлении. Выбор символов для такого кодирования может несколько отличаться от результата, который дают методы url.parse() и url.format().

url.searchParams

• Тип: <URLSearchParams>

Получает объект URLSearchParams, представляющий параметры строки запроса URL. Это свойство доступно только для чтения, но предоставленный им объект 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);  // prints ?foo=~bar

// Modify the URL via searchParams...
myURL.searchParams.sort();

console.log(myURL.search);  // prints ?foo=%7Ebar copy

url.username

• Тип: <string>

Получает и задает часть URL, содержащую имя пользователя.

const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username);
// Prints abc

myURL.username = '123';
console.log(myURL.href);
// Prints https://123:xyz@example.com/ copy

Любые недопустимые символы URL, встречающиеся в значении, присвоенном свойству username, будут закодированы в процентном представлении. Выбор символов для такого кодирования может несколько отличаться от результата, который дают методы url.parse() и url.format().

url.toString()

• Возвращает: <string>

Метод toString() объекта URL возвращает сериализованный URL. Возвращаемое значение эквивалентно значениям url.href и url.toJSON().

url.toJSON()

• Возвращает: <string>

Метод toJSON() объекта URL возвращает сериализованный URL. Возвращаемое значение эквивалентно значениям url.href и url.toString().

Этот метод вызывается автоматически, когда объект URL сериализуется с помощью JSON.stringify().

const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"] copy

URL.createObjectURL(blob)

• blob <Blob>
• Возвращает: <string>

Создает строку URL 'blob:nodedata:...', представляющую переданный объект <Blob> и позволяющую впоследствии получить Blob.

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

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

// later...

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

Данные, хранящиеся в зарегистрированном <Blob>, будут оставаться в памяти до вызова URL.revokeObjectURL() для их удаления.

Объекты Blob регистрируются в текущем потоке. При использовании рабочих потоков объекты Blob, зарегистрированные в одном рабочем потоке, будут недоступны другим рабочим потокам и основному потоку.

URL.revokeObjectURL(id)

• id <string> Строка URL 'blob:nodedata:..., возвращенная предыдущим вызовом URL.createObjectURL().

Удаляет сохраненный объект <Blob>, идентифицируемый указанным идентификатором. Попытка отозвать незарегистрированный идентификатор завершается без каких-либо сообщений.

URL.canParse(input[, base])

• input <string> Абсолютный или относительный входной URL для разбора. Если input является относительным, требуется base. Если input является абсолютным, base игнорируется. Если input не является строкой, сначала он преобразуется в строку.
• base <string> Базовый URL, относительно которого выполняется разрешение, если input не является абсолютным. Если base не является строкой, сначала он преобразуется в строку.
• Возвращает: <boolean>

Проверяет, можно ли разобрать input относительно base как URL.

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

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

URL.parse(input[, base])

• input <string> Абсолютный или относительный входной URL для разбора. Если input является относительным, требуется base. Если input является абсолютным, base игнорируется. Если input не является строкой, сначала он преобразуется в строку.
• base <string> Базовый URL, относительно которого выполняется разрешение, если input не является абсолютным. Если base не является строкой, сначала он преобразуется в строку.
• Возвращает: <URL> | <null>

Разбирает строку как URL. Если передан base, он будет использоваться в качестве базового URL для разрешения не абсолютных URL input. Возвращает null, если параметры нельзя разрешить в допустимый URL.

new URLSearchParams()

Создает новый пустой объект URLSearchParams.

new URLSearchParams(string)

• string <string> Строка запроса

Разбирает string как строку запроса и использует ее для создания нового объекта URLSearchParams. Начальный символ '?', если он присутствует, игнорируется.

let params;

params = new URLSearchParams('user=abc&query=xyz');
console.log(params.get('user'));
// Prints 'abc'
console.log(params.toString());
// Prints 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz');
console.log(params.toString());
// Prints 'user=abc&query=xyz' copy

new URLSearchParams(obj)

• obj <Object> Объект, представляющий набор пар «ключ-значение»

Создает новый объект URLSearchParams с хеш-таблицей запроса. Ключ и значение каждого свойства obj всегда приводятся к строкам.

В отличие от модуля querystring, повторяющиеся ключи в виде значений-массивов не допускаются. Массивы преобразуются в строки с помощью array.toString(), которая просто объединяет все элементы массива запятыми.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
});
console.log(params.getAll('query'));
// Prints [ 'first,second' ]
console.log(params.toString());
// Prints 'user=abc&query=first%2Csecond' copy

new URLSearchParams(iterable)

• iterable <Iterable> Итерируемый объект, элементы которого являются парами «ключ-значение»

Создает новый объект URLSearchParams с итерируемой коллекцией аналогично конструктору <Map>. iterable может быть Array или любым итерируемым объектом. Это означает, что iterable может быть другим URLSearchParams; в этом случае конструктор просто создаст копию переданного URLSearchParams. Элементы iterable являются парами «ключ-значение» и сами могут быть любыми итерируемыми объектами.

Повторяющиеся ключи допускаются.

let params;

// Using an array
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
]);
console.log(params.toString());
// Prints 'user=abc&query=first&query=second'

// Using a Map object
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
console.log(params.toString());
// Prints 'user=abc&query=xyz'

// Using a generator function
function* getQueryPairs() {
  yield ['user', 'abc'];
  yield ['query', 'first'];
  yield ['query', 'second'];
}
params = new URLSearchParams(getQueryPairs());
console.log(params.toString());
// Prints 'user=abc&query=first&query=second'

// Each key-value pair must have exactly two elements
new URLSearchParams([
  ['user', 'abc', 'error'],
]);
// Throws TypeError [ERR_INVALID_TUPLE]:
//        Each query pair must be an iterable [name, value] tuple copy

urlSearchParams.append(name, value)

• name <string>
• value <string>

Добавляет новую пару «имя-значение» в строку запроса.

urlSearchParams.delete(name[, value])

• name <string>
• value <string>

Если указан value, удаляет все пары «имя-значение», в которых имя равно name, а значение — value.

Если value не указан, удаляет все пары «имя-значение», имя которых равно name.

urlSearchParams.entries()

• Возвращает: <Iterator>

Возвращает итератор ES6 Iterator для каждой пары «имя-значение» в запросе. Каждый элемент итератора является массивом JavaScript Array. Первый элемент Array — это name, второй элемент Array — это value.

Псевдоним для urlSearchParams[Symbol.iterator]().

urlSearchParams.forEach(fn[, thisArg])

• fn <Function> Вызывается для каждой пары «имя-значение» в запросе
• thisArg <Object> Используется как значение this при вызове fn

Перебирает каждую пару «имя-значение» в запросе и вызывает заданную функцию.

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

urlSearchParams.get(name)

• name <string>
• Возвращает: <string> | <null> Строку или null, если пары «имя-значение» с указанным name нет.

Возвращает значение первой пары «имя-значение», имя которой равно name. Если таких пар нет, возвращается null.

urlSearchParams.getAll(name)

• name <string>
• Возвращает: <string[]>

Возвращает значения всех пар «имя-значение», имя которых равно name. Если таких пар нет, возвращается пустой массив.

urlSearchParams.has(name[, value])

• name <string>
• value <string>
• Возвращает: <boolean>

Проверяет, содержит ли объект URLSearchParams пары «ключ-значение» на основе name и необязательного аргумента value.

Если указан value, возвращает true, когда существует пара «имя-значение» с теми же name и value.

Если value не указан, возвращает true, если существует хотя бы одна пара «имя-значение» с именем name.

urlSearchParams.keys()

• Возвращает: <Iterator>

Возвращает итератор ES6 Iterator по именам каждой пары «имя-значение».

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

urlSearchParams.set(name, value)

• name <string>
• value <string>

Устанавливает в объекте URLSearchParams значение value, связанное с name. Если уже существуют пары «имя-значение» с именем name, значение первой такой пары устанавливается в value, а все остальные удаляются. Если таких пар нет, пара «имя-значение» добавляется в строку запроса.

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

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&abc=def&xyz=opq copy

urlSearchParams.size

Общее количество записей параметров.

urlSearchParams.sort()

Сортирует на месте все существующие пары «имя-значение» по их именам. Сортировка выполняется с помощью устойчивого алгоритма сортировки, поэтому относительный порядок пар «имя-значение» с одинаковым именем сохраняется.

Этот метод можно использовать, в частности, для увеличения числа попаданий в кэш.

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

urlSearchParams.toString()

• Возвращает: <string>

Возвращает параметры поиска в сериализованном виде в виде строки; при необходимости символы кодируются с помощью процентного кодирования.

urlSearchParams.values()

• Возвращает: <Iterator>

Возвращает итератор ES6 Iterator по значениям каждой пары «имя-значение».

urlSearchParams[Symbol.iterator]()

• Возвращает: <Iterator>

Возвращает итератор ES6 Iterator для каждой пары «имя-значение» в строке запроса. Каждый элемент итератора является массивом JavaScript Array. Первый элемент Array — это name, второй элемент Array — это value.

Псевдоним для urlSearchParams.entries().

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

urlObject.auth

Свойство auth представляет собой часть URL с именем пользователя и паролем, также называемую информацией пользователя. Эта часть строки следует за protocol и двойными косыми чертами (если они есть) и предшествует компоненту host, отделённому символом @. Строка содержит либо имя пользователя, либо имя пользователя и пароль, разделённые символом :.

Например: 'user:pass'.

urlObject.hash

Свойство hash представляет собой часть URL с идентификатором фрагмента, включая начальный символ #.

Например: '#hash'.

urlObject.host

Свойство host представляет собой полную часть URL с именем хоста в нижнем регистре, включая port, если он указан.

Например: 'sub.example.com:8080'.

urlObject.hostname

Свойство hostname представляет собой часть компонента host с именем хоста в нижнем регистре, без включённого port.

Например: 'sub.example.com'.

urlObject.href

Свойство href представляет собой полную строку URL, которая была разобрана, причём компоненты protocol и host преобразованы в нижний регистр.

Например: 'http://user:pass@sub.example.com: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 в нижнем регистре.

Например: 'http:'.

urlObject.query

Свойство query содержит либо строку запроса без начального вопросительного знака ASCII (?), либо объект, возвращаемый методом parse() модуля querystring. Является ли свойство query строкой или объектом, определяется аргументом parseQueryString, переданным в url.parse().

Например: 'query=string' или {'query': 'string'}.

Если возвращается строка, декодирование строки запроса не выполняется. Если возвращается объект, декодируются и ключи, и значения.

urlObject.search

Свойство search содержит всю часть URL со «строкой запроса», включая начальный вопросительный знак ASCII (?).

Например: '?query=string'.

Декодирование строки запроса не выполняется.

urlObject.slashes

Свойство slashes — это boolean со значением true, если после двоеточия в protocol должны следовать две косые черты ASCII (/).