Строки URL и объекты URL

Строка URL — это структурированная строка, содержащая несколько значимых компонентов. При разборе возвращается объект URL, содержащий свойства для каждого из этих компонентов.

Модуль node:url предоставляет два API для работы с URL-адресами: устаревший API, специфичный для Node.js, и новый API, который реализует тот же стандарт WHATWG URL, используемый веб-браузерами.

Сравнение API WHATWG и устаревшего API приведено ниже. Выше URL 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash', показаны свойства объекта, возвращаемого устаревшим url.parse() API. Ниже него — свойства объекта WHATWG URL API.

Свойство origin WHATWG URL включает protocol и host, но не username или password.

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              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 │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(All spaces in the "" line should be ignored. They are purely for formatting.) copy

Разбор строки URL с помощью API WHATWG:

const myURL =
  new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'); copy

Разбор строки URL с помощью устаревшего API:

модули MJS

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

модули CJS

const url = require('node:url');
const myURL =
  url.parse('https://user:pass@sub.example.com: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'; copy

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

Для получения сформированной строки URL используйте свойство доступа href:

console.log(myURL.href); copy

API URL WHATWG

Класс: URL

Совместимый с браузерами класс URL, реализованный в соответствии со стандартом WHATWG URL. Примеры парсинга URL можно найти в самом стандарте. Класс URL также доступен на глобальном объекте.

В соответствии с соглашениями браузеров, все свойства объектов URL реализованы как геттеры и сеттеры на прототипе класса, а не как свойства данных самого объекта. Таким образом, в отличие от старых urlObject, использование ключевого слова delete для любых свойств объектов URL (например, delete myURL.protocol, delete myURL.pathname, и т.д.) не оказывает влияния, но всё равно вернёт true.

new URL(input[, base])

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

Модули MJS

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

Модули CJS

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

• <строка>

Получение и установка фрагмента 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

• <строка>

Получение и установка хоста 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

• <строка>

Получение и установка имени хоста 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

• <строка>

Получение и установка сериализованного 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

• <строка>

Получает только для чтения сериализацию источника 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

• <строка>

Получение и установка пароля 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

• <строка>

Получение и установка пути 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

• <строка>

Получение и установка порта 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

• <строка>

Получение и установка протокола 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, игнорируются.

Специальные схемы

Стандарт 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/ copy

Однако, изменение со схемы http на гипотетическую схему fish не работает, поскольку новая схема не является специальной.

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

Согласно стандарту WHATWG URL, специальными схемами протоколов являются ftp, file, http, https, ws, и wss.

url.search

• <строка>

Получает и устанавливает сериализованную часть запроса 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, будут кодированы по схеме percent-encoding. Выбор символов для кодирования может незначительно отличаться от того, что производят методы url.parse() и url.format().

url.searchParams

• <URLSearchParams>

Получает объект URLSearchParams, представляющий параметры запроса URL. Это свойство является только для чтения, но предоставленный объект URLSearchParams может использоваться для изменения экземпляра URL; для замены всей части параметров запроса URL используйте установщик url.search. Подробности см. в документации URLSearchParams.

Будьте внимательны, используя .searchParams для изменения URL, так как, согласно спецификации WHATWG, объект URLSearchParams использует другие правила для определения символов, которые следует кодировать по схеме percent-encoding. Например, объект 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

• <строка>

Получает и устанавливает часть имени пользователя 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, будут кодированы по схеме percent-encoding. Выбор символов для кодирования может незначительно отличаться от того, что производят методы url.parse() и url.format().

url.toString()

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

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

url.toJSON()

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

Метод 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>
• Возвращает: <строка>

Создаёт строку 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 регистрируются в текущей нити. Если используются потоки Worker, объекты Blob зарегистрированные в одном Worker, недоступны для других worker или основной нити.

URL.revokeObjectURL(id)

• id <строка> Возвращённая строка URL 'blob:nodedata:... с предыдущего вызова URL.createObjectURL().

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

URL.canParse(input[, base])

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

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

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

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

Класс: URLSearchParams

API URLSearchParams предоставляет чтение и запись в часть запроса URL. Класс URLSearchParams также может использоваться автономно с одним из четырёх конструкторов. Класс URLSearchParams также доступен в глобальном объекте.

Интерфейс WHATWG URLSearchParams и модуль querystring имеют схожую цель, но цель модуля querystring более общая, так как он позволяет настраивать символы разделителей (& и =). С другой стороны, данное API предназначено только для строк запросов URL.

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

myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
// Prints https://example.org/?abc=123&abc=xyz

myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
// Prints https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c');
console.log(myURL.href);
// Prints https://example.org/?a=b
console.log(newSearchParams.toString());
// Prints a=b&a=c

// newSearchParams.toString() is implicitly called
myURL.search = newSearchParams;
console.log(myURL.href);
// Prints https://example.org/?a=b&a=c
newSearchParams.delete('a');
console.log(myURL.href);
// Prints https://example.org/?a=b&a=c copy

new URLSearchParams()

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

new URLSearchParams(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 <Объект> Объект, представляющий коллекцию пар ключ-значение

Создаёт новый объект 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 <Итерируемый объект> Итерируемый объект, чьи элементы являются парами ключ-значение

Создаёт новый объект 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 <строка>
• value <строка>

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

urlSearchParams.delete(name[, value])

• name <строка>
• value <строка>

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

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

urlSearchParams.entries()

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

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

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

urlSearchParams.forEach(fn[, thisArg])

• fn <Функция> Вызывается для каждой пары имя-значение в запросе
• thisArg <Объект> Используется в качестве значения 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 <строка>
• Возвращает: <строка> или null в случае отсутствия пары имя-значение с указанным name.

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

urlSearchParams.getAll(name)

• name <строка>
• Возвращает: <массив строк>

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

urlSearchParams.has(name[, value])

• name <строка>
• value <строка>
• Возвращает: <логическое значение>

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

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

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

urlSearchParams.keys()

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

Возвращает 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 <строка>
• value <строка>

Устанавливает значение в объекте 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());
// 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()

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

Возвращает сериализованные параметры поиска в виде строки, с символами, закодированными в процентах, где необходимо.

urlSearchParams.values()

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

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

urlSearchParams[Symbol.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

url.domainToASCII(domain)

• domain <строка>
• Возвращает: <строка>

Возвращает ASCII-сериализацию domain в формате Punycode. Если domain — недопустимый домен, возвращается пустая строка.

Выполняет обратную операцию к url.domainToUnicode().

Модули MJS

import url from 'node:url';

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string

Модули CJS

const url = require('node:url');

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string

url.domainToUnicode(domain)

• domain <строка>
• Возвращает: <строка>

Возвращает Unicode-сериализацию domain. Если domain — недопустимый домен, возвращается пустая строка.

Выполняет обратную операцию к url.domainToASCII().

Модули MJS

import url from 'node:url';

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string

Модули CJS

const url = require('node:url');

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string

url.fileURLToPath(url)

• url <URL> | <строка> Строка URL файла или объект URL для преобразования в путь.
• Возвращает: <строка> Полностью разрешенный путь к файлу в формате Node.js, специфичный для платформы.

Эта функция гарантирует правильную декодировку символов, закодированных в процентах, а также обеспечивает платформенно-независимый допустимый абсолютный путь.

Модули MJS

import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);

new URL('file:///C:/path/').pathname;      // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/');         // Correct:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correct:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correct:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrect: /hello%20world
fileURLToPath('file:///hello world');      // Correct:   /hello world (POSIX)

Модули CJS

const { fileURLToPath } = require('node:url');
new URL('file:///C:/path/').pathname;      // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/');         // Correct:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correct:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correct:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrect: /hello%20world
fileURLToPath('file:///hello world');      // Correct:   /hello world (POSIX)

url.format(URL[, options])

• URL <URL> Объект WHATWG URL
• options <Object>
  • auth <boolean> true указывать ли имя пользователя и пароль в сериализованной строке URL, false в противном случае. По умолчанию: true.
  • fragment <boolean> true указывать ли фрагмент в сериализованной строке URL, false в противном случае. По умолчанию: true.
  • search <boolean> true указывать ли строку запроса в сериализованной строке URL, false в противном случае. По умолчанию: true.
  • unicode <boolean> true кодировать ли символы Юникода в компоненте хоста строки URL непосредственно, а не с помощью Punycode. По умолчанию: false.
• Возвращает: <string>

Возвращает настраиваемую сериализацию URL String представления объекта WHATWG URL.

Объект URL имеет как toString() метод, так и href свойство, которые возвращают строковые сериализации URL. Однако они никак не настраиваются. Метод url.format(URL[, options]) позволяет настроить вывод.

MJS модули

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

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

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

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

CJS модули

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

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

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

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

url.pathToFileURL(path)

• path <string> Путь для преобразования в URL файла.
• Возвращает: <URL> Объект URL файла.

Эта функция гарантирует, что path разрешается абсолютно и что управляющие символы URL правильно закодированы при преобразовании в URL файла.

MJS модули

import { pathToFileURL } from 'node:url';

new URL('/foo#1', 'file:');           // Incorrect: file:///foo#1
pathToFileURL('/foo#1');              // Correct:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:');    // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correct:   file:///some/path%25.c (POSIX)

CJS модули

const { pathToFileURL } = require('node:url');
new URL(__filename);                  // Incorrect: throws (POSIX)
new URL(__filename);                  // Incorrect: C:\... (Windows)
pathToFileURL(__filename);            // Correct:   file:///... (POSIX)
pathToFileURL(__filename);            // Correct:   file:///C:/... (Windows)

new URL('/foo#1', 'file:');           // Incorrect: file:///foo#1
pathToFileURL('/foo#1');              // Correct:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:');    // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correct:   file:///some/path%25.c (POSIX)

url.urlToHttpOptions(url)

• 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 в обычный объект параметров, как ожидается API http.request() и https.request().

MJS модули

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'
}
*/

CJS модули

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'
}
*/

API URL-ов старого образца

urlObject

Объект старого образца 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 — это полное имя хоста 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 (/).

url.format(urlObject)

• urlObject <Объект> | <строка> Объект URL (как возвращается url.parse() или создаётся другим способом). Если строка, она преобразуется в объект путём передачи её в url.parse().

Метод url.format() возвращает отформатированную строку URL, полученную из urlObject.

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

Если urlObject не является объектом или строкой, url.format() сгенерирует исключение TypeError.

Процесс форматирования происходит следующим образом:

• Создаётся новая пустая строка result.
• Если urlObject.protocol является строкой, она добавляется как есть к result.
• В противном случае, если urlObject.protocol не является undefined и не является строкой, выбрасывается Error.
• Для всех строковых значений urlObject.protocol, которые не заканчиваются символом ASCII двоеточие (:) к result будет добавлен литеральный строковый :.
• Если выполняется любое из следующих условий, то к 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 добавляется литеральный строковый ?, за которым следует результат вызова метода stringify() модуля querystring с параметром, равным значению 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]])

• urlString <строка> Строка URL для парсинга.
• parseQueryString <логическое> Если true, свойство query всегда будет устанавливаться в объект, возвращаемый методом parse() модуля querystring. Если false, свойство query возвращаемого объекта URL будет необработанной, нерасшифрованной строкой. По умолчанию: false.
• slashesDenoteHost <логическое> Если true, первый токен после литеральной строки // и перед следующим / будет интерпретирован как host. Например, для //foo/bar результатом будет {host: 'foo', pathname: '/bar'} вместо {pathname: '//foo/bar'}. По умолчанию: false.

Метод url.parse() принимает строку URL, парсит её и возвращает объект URL.

Если urlString не является строкой, выбрасывается TypeError.

Если свойство auth присутствует, но не может быть расшифровано, выбрасывается URIError.

url.parse() использует мягкий, нестандартный алгоритм парсинга строк URL. Он подвержен проблемам безопасности, таким как подмена имени хоста и неправильной обработке имён пользователей и паролей. Не используйте с непроверенными данными. CVEs не выдаются для уязвимостей url.parse(). Вместо этого используйте API WHATWG URL.

url.resolve(from, to)

• from <строка> Базовый URL для использования, если to является относительным URL.
• to <строка> Целевой 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' copy

Для достижения того же результата с помощью API WHATWG URL:

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
  if (resolvedUrl.protocol === 'resolve:') {
    // `from` is a relative 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' copy

Кодирование процентов в URL-адресах

URL-адреса разрешено содержать только определённый диапазон символов. Любой символ, выходящий за пределы этого диапазона, должен быть закодирован. Способ кодирования и какие символы кодировать зависит полностью от того, где находится символ в структуре URL-адреса.

API устаревшей версии

В API устаревшей версии пробелы (' ') и следующие символы будут автоматически экранированы в свойствах объектов URL:

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

Например, символ ASCII-пробела (' ') кодируется как %20. Символ ASCII-слеша (/) кодируется как %3C.

API WHATWG

Стандарт WHATWG URL использует более избирательный и детальный подход к выбору кодируемых символов по сравнению с API устаревшей версии.

Алгоритм WHATWG определяет четыре «набора кодирования процентов», которые описывают диапазоны символов, которые необходимо кодировать с помощью процентов:

• Набор C0-контрольных символов для кодирования процентов включает код-точки в диапазоне U+0000 до U+001F (включительно) и все код-точки, большие, чем U+007E.

• Набор символов фрагмента для кодирования процентов включает набор C0-контрольных символов для кодирования процентов и код-точки U+0020, U+0022, U+003C, U+003E и U+0060.

• Набор символов пути для кодирования процентов включает набор C0-контрольных символов для кодирования процентов и код-точки U+0020, U+0022, U+0023, U+003C, U+003E, U+003F, U+0060, U+007B и U+007D.

• Набор символов авторизации для кодирования процентов включает набор символов пути для кодирования процентов и код-точки U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, U+005E и U+007C.

Набор символов авторизации для кодирования процентов используется исключительно для кодирования имён пользователей и паролей, входящих в состав URL-адреса. Набор символов пути для кодирования процентов используется для пути большинства URL-адресов. Набор символов фрагмента для кодирования процентов используется для фрагментов URL-адресов. Набор C0-контрольных символов для кодирования процентов используется для хоста и пути в определённых условиях, а также во всех остальных случаях.

Когда не-ASCII символы появляются в имени хоста, имя хоста кодируется с помощью алгоритма Punycode. Обратите внимание, однако, что имя хоста может содержать как символы, закодированные Punycode, так и символы, закодированные с помощью процентов:

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