encodeURI()

Функция encodeURI() кодирует URI, заменяя каждый экземпляр определенных символов одной, двумя, тремя или четырьмя экранирующими последовательностями, представляющими UTF-8 кодировку символа (будет четыре экранирующие последовательности только для символов, состоящих из двух суррогатных символов). По сравнению с encodeURIComponent(), эта функция кодирует меньше символов, сохраняя те, которые являются частью синтаксиса URI.

Попробуйте

const uri = "https://mozilla.org/?x=шеллы";
const encoded = encodeURI(uri);
console.log(encoded);
// Expected output: "https://mozilla.org/?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"

try {
  console.log(decodeURI(encoded));
  // Expected output: "https://mozilla.org/?x=шеллы"
} catch (e) {
  // Catches a malformed URI
  console.error(e);
}

Синтаксис

encodeURI(uri)

Параметры

uri

Строка, которая будет закодирована как URI.

Возвращаемое значение

Новая строка, представляющая предоставленную строку, закодированную как URI.

Исключения

URIError

Выбрасывается, если uri содержит одиночный суррогат.

Описание

encodeURI() является свойством-функцией глобального объекта.

Функция encodeURI() экранирует символы с помощью кодовых единиц UTF-8, при этом каждый октет кодируется в формате %XX, с добавлением 0 слева, если это необходимо. Поскольку одиночные суррогаты в UTF-16 не кодируют действительных символов Unicode, они вызывают выбрасывание URIError функцией encodeURI().

encodeURI() экранирует все символы, кроме:

A–Z a–z 0–9 - _ . ! ~ * ' ( )

; / ? : @ & = + $ , #

Символы на второй строке — это символы, которые могут быть частью синтаксиса URI и экранируются только функцией encodeURIComponent(). Обе функции, encodeURI() и encodeURIComponent(), не кодируют символы -.!~*'(), известные как «незарезервированные метки», которые не имеют зарезервированного назначения, но разрешены в URI «как есть». (См. RFC2396)

Функция encodeURI() не кодирует символы, имеющие особое значение (зарезервированные символы) для URI. Следующий пример показывает все части, которые может содержать URI. Обратите внимание, как определенные символы используются для обозначения особого значения:

http://username:password@www.example.com:80/path/to/file.php?foo=316&bar=this+has+spaces#anchor

encodeURI, как следует из названия, используется для кодирования URL целиком, предполагая, что он уже корректно сформирован. Если вы хотите динамически собирать строковые значения в URL, вам, вероятно, следует использовать encodeURIComponent() для каждого динамического сегмента, чтобы избежать символов синтаксиса URL в нежелательных местах.

const name = "Ben & Jerry's";

// This is bad:
const badLink = encodeURI(`https://example.com/?choice=${name}`); // "https://example.com/?choice=Ben%20&%20Jerry's"
console.log([...new URL(badLink).searchParams]); // [['choice', 'Ben '], [" Jerry's", '']]

// Instead:
const goodLink = `https://example.com/?choice=${encodeURIComponent(name)}`;
// "https://example.com/?choice=Ben%20%26%20Jerry's"
console.log([...new URL(goodLink).searchParams]); // [['choice', "Ben & Jerry's"]]

Примеры

encodeURI() против encodeURIComponent()

encodeURI() отличается от encodeURIComponent() следующим образом:

const set1 = ";/?:@&=+$,#"; // Reserved Characters
const set2 = "-.!~*'()"; // Unreserved Marks
const set3 = "ABC abc 123"; // Alphanumeric Characters + Space

console.log(encodeURI(set1)); // ;/?:@&=+$,#
console.log(encodeURI(set2)); // -.!~*'()
console.log(encodeURI(set3)); // ABC%20abc%20123 (the space gets encoded as %20)

console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24%23
console.log(encodeURIComponent(set2)); // -.!~*'()
console.log(encodeURIComponent(set3)); // ABC%20abc%20123 (the space gets encoded as %20)

Кодирование одиночного суррогата вызывает ошибку

Будет выброшено исключение URIError, если попытаться закодировать суррогат, который не является частью суррогатной пары. Например:

// High-low pair OK
encodeURI("\uD800\uDFFF"); // "%F0%90%8F%BF"

// Lone high-surrogate code unit throws "URIError: malformed URI sequence"
encodeURI("\uD800");

// Lone low-surrogate code unit throws "URIError: malformed URI sequence"
encodeURI("\uDFFF");

Вы можете использовать String.prototype.toWellFormed(), которая заменяет одиночные суррогаты символом замены Unicode (U+FFFD), чтобы избежать этой ошибки. Вы также можете использовать String.prototype.isWellFormed() для проверки, содержит ли строка одиночные суррогаты, прежде чем передавать ее в encodeURI().

Кодирование для RFC3986

Более поздний RFC3986 делает квадратные скобки зарезервированными (для IPv6) и, следовательно, не кодируются при формировании того, что может быть частью URL (например, имени хоста). Он также резервирует символы !, ', (, ), и *, хотя эти символы не имеют формализованного использования в качестве разделителей URI. Следующая функция кодирует строку для формата URL, совместимого с RFC3986.

function encodeRFC3986URI(str) {
  return encodeURI(str)
    .replace(/%5B/g, "[")
    .replace(/%5D/g, "]")
    .replace(
      /[!'()*]/g,
      (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
    );
}

Спецификации

Совместимость с браузерами

Смотрите также

• decodeURI()
• encodeURIComponent()
• decodeURIComponent()