Строки 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', показаны свойства объекта, возвращаемого устаревшим API url.parse(). Ниже — свойства объекта WHATWG URL.

Свойство origin URL WHATWG включает 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 не является строкой, она предварительно преобразуется в строку с помощью метода toString().
• base <строка> Базовый URL для разрешения, если input не является абсолютным. Если base не является строкой, она предварительно преобразуется в строку с помощью метода toString().

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

• <строка>

Получает и задаёт часть имени пользователя 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()

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

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

Создаёт строку URL 'blob:nodedata:...', которая представляет данный объект <Файл> и может использоваться для получения 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

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

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

URL.revokeObjectURL(id)

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

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

URL.canParse(input[, base])

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

Проверяет, можно ли проанализировать 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.

Краткое описание итератора

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

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

Псевдоним для 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

Получить имя параметра

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

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

Получить все значения параметра

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

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

Проверка существования пары имя-значение

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

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

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

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

urlSearchParams.keys()

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

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

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

Установить значение параметра

• 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

Количество параметров

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

Сортировка параметров

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

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

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

Преобразование в строку

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

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

Значения параметров

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

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

urlSearchParams[Symbol.iterator]()

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

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

Псевдоним для 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

Преобразование домена в ASCII

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

Возвращает ASCII-сериализацию домена в формате 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

Преобразование домена в Unicode

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

Возвращает сериализацию домена в формате Unicode. Если 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 файла в путь

• url <URL> | <string> Строка URL файла или объект URL для преобразования в путь.
• options <Object>
  • windows <boolean> | <undefined> true если path должно быть возвращено как путь к файлу Windows, false для POSIX и undefined для системного значения по умолчанию. По умолчанию: undefined.
• Возвращает: <string> Полный разрешённый платформоспецифичный путь к файлу 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> Объект URL WHATWG
• options <Object>
  • auth <boolean> true если сериализованная строка URL должна включать имя пользователя и пароль, true в противном случае. По умолчанию: true.
  • fragment <boolean> true если сериализованная строка URL должна включать фрагмент, false в противном случае. По умолчанию: true.
  • search <boolean> true если сериализованная строка URL должна включать поисковый запрос, false в противном случае. По умолчанию: true.
  • unicode <boolean> true если символы Unicode, присутствующие в компонентe хоста строки 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[, options])

• path <string> Путь для преобразования в URL файла.
• options <Object>
  • windows <boolean> | <undefined> true если path должно обрабатываться как путь к файлу Windows, false для POSIX и undefined для системного значения по умолчанию. По умолчанию: undefined.
• Возвращает: <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

Объект 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.
• Возвращается 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. Он уязвим к проблемам безопасности, таким как подмена имени хоста host name spoofing и неправильная обработка имен пользователей и паролей. Не используйте с ненадежными входными данными. 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

Стандарт URL WHATWG (WHATWG URL Standard) использует более избирательный и точный подход к выбору кодируемых символов, чем API устаревшего стандарта.

Алгоритм WHATWG определяет четыре «набора кодирования процентов» (percent-encode sets), которые описывают диапазоны символов, которые должны быть закодированы:

• Набор кодирования процентов 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 (}).

• Набор кодирования процентов 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);
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin);
// Prints https://xn--1xa.example.com copy