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

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

Модуль 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.)

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

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

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

Модули MJS

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

Модули CJS

const url = require('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';

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

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

console.log(myURL.href);

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

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

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

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

Модули MJS

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

Модули CJS

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

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

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

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

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

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

В случаях, когда заранее неизвестно, является ли 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/

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

Недействительные символы 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

Недействительные значения хоста, присвоенные свойству 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:82';
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

Недействительные значения имени хоста, присвоенные свойству 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

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

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

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

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

Недействительные символы 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

Недействительные символы 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

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

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

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/

Недействительные значения протокола 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

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

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

Также изменение от неспециального протокола к специальному протоколу не разрешено:

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

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

url.search

• <строка>

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

Любые недопустимые символы 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

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/

Любые недопустимые символы 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/"]

URL.createObjectURL(blob)

• blob <Объект Blob>
• Возвращает: <строка>

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

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

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

// later...

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

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

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

URL.revokeObjectURL(id)

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

Удаляет хранящийся объект <Объект Blob>, идентифицированный данным идентификатором.

Класс: 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

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'

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'

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

urlSearchParams.append(name, value)

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

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

urlSearchParams.delete(name)

• name <строка>

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

urlSearchParams.entries()

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

Возвращает ES6 итератор по каждой паре имя-значение в запросе. Каждый элемент итератора — 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

urlSearchParams.get(name)

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

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

urlSearchParams.getAll(name)

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

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

urlSearchParams.has(name)

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

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

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

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

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

url.domainToASCII(domain)

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

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

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

Эта функция доступна только в том случае, если исполняемый файл node был скомпилирован с включённым ICU. В противном случае имена доменов передаются без изменений.

Модули MJS

import url from '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('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().

Эта функция доступна только в том случае, если исполняемый файл node был скомпилирован с включённым ICU. В противном случае имена доменов передаются без изменений.

Модули MJS

import url from '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('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 файла, который требуется преобразовать в путь.
• Возвращает: <строка> Полностью разрешённый путь к файлу Node.js, специфичный для платформы.

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

Модули MJS

import { fileURLToPath } from '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('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 <объект>
  • auth <логическое значение> true если сериализованная строка URL должна включать имя пользователя и пароль, false в противном случае. По умолчанию: true.
  • fragment <логическое значение> true если сериализованная строка URL должна включать фрагмент, false в противном случае. По умолчанию: true.
  • search <логическое значение> true если сериализованная строка URL должна включать строку поиска, false в противном случае. По умолчанию: true.
  • unicode <логическое значение> true если символы Юникода, встречающиеся в компоненте хоста строки URL, должны быть закодированы напрямую, а не в Punycode. По умолчанию: false.
• Возвращает: <строка>

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

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

Модули MJS

import url from '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('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 <строка> Путь для преобразования в URL файла.
• Возвращает: <объект URL> Объект URL файла.

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

Модули MJS

import { pathToFileURL } from '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('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 для преобразования в объект опций.
• Возвращает: <Объект> Объект опций
  • protocol <строка> Протокол для использования.
  • hostname <строка> Имя домена или IP-адрес сервера, которому нужно отправить запрос.
  • hash <строка> Часть фрагмента URL.
  • search <строка> Сериализованная часть запроса URL.
  • pathname <строка> Путь части URL.
  • path <строка> Путь запроса. Должен содержать строку запроса, если она есть. Пример: '/index.html?page=12'. Исключение выбрасывается, когда путь запроса содержит недопустимые символы. В настоящее время отклоняются только пробелы, но это может измениться в будущем.
  • href <строка> Сериализованный URL.
  • port <число> Порт удаленного сервера.
  • auth <строка> Базовая аутентификация, например, 'user:password' для вычисления заголовка Authorization.

Эта служебная функция преобразует объект URL в обычный объект опций, как ожидается от API http.request() и https.request().

Модули MJS

import { urlToHttpOptions } from '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('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 (legacy)

Legacy urlObject

Legacy urlObject (require('url').Url или import { Url } from '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 компонентов, ограниченных символами вопросительного знака (?) или решётки (#) соответственно.

Например: '/p/a/t/h'.

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

urlObject.port

Свойство port — это числовой порт host компонента.

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

urlObject.protocol

Свойство protocol идентифицирует схему протокола URL в нижнем регистре.

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

urlObject.query

Свойство query — это либо строка запроса без ведущего знака вопроса (?), либо объект, возвращённый методом 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('url');
url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json'
  }
});

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

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

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

• Создается новая пустая строка result.
• Если urlObject.protocol является строкой, она добавляется как есть к result.
• В противном случае, если urlObject.protocol не undefined и не является строкой, выбрасывается Error.
• Для всех строковых значений 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.

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

Выбрасывается URIError, если свойство auth присутствует, но его невозможно декодировать.

Использование устаревшего метода url.parse() не рекомендуется. Пользователи должны использовать API WHATWG URL. Поскольку метод url.parse() использует мягкий, нестандартный алгоритм анализа строк URL, могут возникнуть проблемы с безопасностью. В частности, были выявлены проблемы с подделкой имени хоста host name spoofing и неправильной обработкой имен пользователей и паролей.

url.resolve(from, to)

• from <строка> Базовый URL, относительно которого разрешается целевой URL.
• to <строка> URL HREF, который разрешается.

Метод url.resolve() разрешает целевой URL относительно базового URL аналогично тому, как веб-браузер разрешает тег якоря HREF.

const url = require('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'

Вы можете достичь того же результата с помощью API URL WHATWG:

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'

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

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

API Legacy

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

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

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

API WHATWG

Стандарт URL WHATWG WHATWG URL Standard использует более избирательный и точный подход к выбору кодируемых символов по сравнению с Legacy 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