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', показаны свойства объекта, возвращаемого устаревшим 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.)

Разбор URL-строки с использованием API WHATWG:

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

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

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 WHATWG URL

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

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

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/"]

Класс: 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 итератор по именам каждой пары "имя-значение".

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().

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().

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.

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

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 если символы Unicode, присутствующие в компоненте хоста строки URL, должны быть закодированы напрямую, а не с помощью Punycode. По умолчанию: false.
• Возвращает: <строка>

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

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

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 файла.

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)

API URL-ов устаревшей версии

Устаревший urlObject

Устаревший urlObject (require('url').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 имеет значение true, если после двоеточия в protocol требуются две косые черты (/).

url.format(urlObject)

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

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

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.

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

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

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

url.resolve(from, to)

• from <строка> Базовый 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 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'

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

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

API Legacy

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

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

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

API WHATWG

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

Алгоритм 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.

• Набор кодирования процентов userinfo включает набор кодирования процентов пути и кодовые точки U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, 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