Spec-Zone.ru › Node.js 12 LTS

URL

Стабильность: 2 - Стабильно

Исходный код: lib/url.js

Модуль url предоставляет инструменты для разрешения и разбора URL-адресов. К нему можно обратиться, используя:

const url = require('url');

URL-строки и объекты URL

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

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

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

Свойство 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:

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

API WHATWG URL

Класс: URL

История
Версия Изменения
v10.0.0

Класс теперь доступен в глобальном объекте.
v7.0.0, v6.13.0

Добавлен в: v7.0.0, v6.13.0

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

myURL.hostname = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:81/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 станет пустой строкой ('').

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

протокол порт
"ftp" 21
"file"
"gopher" 70
"http" 80
"https" 443
"ws" 80
"wss" 443

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

История
Версия Изменения
v10.0.0

Класс теперь доступен в глобальном объекте.
v7.5.0, v6.13.0

Добавлен в: v7.5.0, v6.13.0

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)

Добавлен в: v7.10.0, v6.13.0
  • 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)

Добавлен в: v7.10.0, v6.13.0
  • 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 массив. Первый элемент массива — это name, второй — 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()

Добавлен в: v7.7.0, v6.13.0

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

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

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)

Добавлена в: v7.4.0, v6.13.0
  • 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)

Добавлена в: v7.4.0, v6.13.0
  • 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)

Добавлена в: v10.12.0
  • 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])

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

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

Объект 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)

Добавлена в: v10.12.0
  • 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 (устаревшая версия)

Устарела с версии: v11.0.0

Устаревшая версия urlObject

История
Версия Изменения
v11.0.0

Устаревшая версия API URL. Используйте API WHATWG URL.
Уровень стабильности: 0 - Устаревшая: Используйте вместо этого API WHATWG URL.

Устаревший 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 компонентов, отделённых символом ASCII вопроса (?) или диез (#) соответственно.

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

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

urlObject.port

Свойство port содержит числовой порт из компонента host.

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

urlObject.protocol

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

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

urlObject.query

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

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

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

urlObject.search

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

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

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

urlObject.slashes

Свойство slashes — это boolean со значением true, если после двоеточия в protocol требуются два символа ASCII слеша (/).

url.format(urlObject)

История
Версия Изменения
v11.0.0

API Legacy URL устарел. Используйте WHATWG URL API.
v7.0.0

URL со схемой file: теперь всегда будут использовать правильное количество косых черт независимо от slashes опции. Ложное значение slashes опции без протокола также всегда учитывается.
v0.1.25

Добавлен в: v0.1.25
Устойчивость: 0 - Устаревший: Используйте WHATWG URL API вместо этого.
  • 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]])

История
Версия Изменения
v11.14.0

Свойство pathname возвращаемого объекта URL теперь равно /, когда нет пути и схема протокола ws: или wss:.
v11.0.0

API Legacy URL устарел. Используйте WHATWG URL API.
v9.0.0

Свойство search возвращаемого объекта URL теперь равно null, когда нет строки запроса.
v0.1.25

Добавлен в: v0.1.25
Устойчивость: 0 - Устарел: Используйте WHATWG URL API вместо этого.
  • urlString <строка> Строка URL для парсинга.
  • parseQueryString <логическое значение> Если true, свойство query всегда будет установлено в объект, возвращаемый методом querystring модуля parse(). Если 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() не рекомендуется. Пользователи должны использовать WHATWG URL API. Поскольку метод url.parse() использует мягкий, нестандартный алгоритм для парсинга строк URL, могут возникнуть проблемы с безопасностью. В частности, были выявлены проблемы с подменой имени хоста и некорректной обработкой имён пользователей и паролей.

url.resolve(from, to)

История
Версия Изменения
v11.0.0

API Legacy URL устарел. Используйте WHATWG URL API.
v6.6.0

Поля auth теперь остаются неизменными, когда from и to ссылаются на один и тот же хост.
v6.5.0, v4.6.2

Поле port копируется правильно.
v6.0.0

Поля auth очищаются, когда параметр to содержит имя хоста.
v0.1.25

Добавлен в: v0.1.25
Устойчивость: 0 - Устарел: Используйте WHATWG URL API вместо этого.
  • 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'

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

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

Устаревший API

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

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

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

API WHATWG

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

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

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

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

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

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

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

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

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

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v12.x/docs/api/url.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API