encodeURIComponent()

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

Попробуйте

// Encodes characters such as ?,=,/,&,:
console.log(`?x=${encodeURIComponent("test?")}`);
// Expected output: "?x=test%3F"

console.log(`?x=${encodeURIComponent("шеллы")}`);
// Expected output: "?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"

Синтаксис

encodeURIComponent(uriComponent)

Параметры

uriComponent

Строка для кодирования в компоненте URI (путь, строка запроса, фрагмент и т. д.). Другие значения преобразуются в строки.

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

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

Исключения

URIError

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

Описание

encodeURIComponent() — это свойство функции глобального объекта.

encodeURIComponent() использует тот же алгоритм кодирования, что описан в encodeURI(). Он экранирует все символы, кроме:

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

По сравнению с encodeURI(), encodeURIComponent() экранирует больший набор символов. Используйте encodeURIComponent() для полей, вводимых пользователем, из форм, отправляемых на сервер — это будет кодировать символы &, которые могут быть случайно сгенерированы во время ввода данных для ссылок на символы или других символов, требующих кодирования/декодирования. Например, если пользователь вводит Jack & Jill, без encodeURIComponent(), амперсанд может быть интерпретирован на сервере как начало нового поля и поставить под угрозу целостность данных.

Для application/x-www-form-urlencoded пробелы должны заменяться на +, поэтому после замены encodeURIComponent() может потребоваться дополнительная замена %20 на +.

Примеры

Кодирование для заголовков Content-Disposition и Link

Следующий пример предоставляет специальное кодирование, необходимое в параметрах заголовков ответа сервера UTF-8 Content-Disposition и Link (например, имена файлов в UTF-8):

const fileName = "my file(2).txt";
const header = `Content-Disposition: attachment; filename*=UTF-8''${encodeRFC5987ValueChars(
  fileName,
)}`;

console.log(header);
// "Content-Disposition: attachment; filename*=UTF-8''my%20file%282%29.txt"

function encodeRFC5987ValueChars(str) {
  return (
    encodeURIComponent(str)
      // The following creates the sequences %27 %28 %29 %2A (Note that
      // the valid encoding of "*" is %2A, which necessitates calling
      // toUpperCase() to properly encode). Although RFC3986 reserves "!",
      // RFC5987 does not, so we do not need to escape it.
      .replace(
        /['()*]/g,
        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
      )
      // The following are not required for percent-encoding per RFC5987,
      // so we can allow for a little better readability over the wire: |`^
      .replace(/%(7C|60|5E)/g, (str, hex) =>
        String.fromCharCode(parseInt(hex, 16)),
      )
  );
}

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

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

function encodeRFC3986URIComponent(str) {
  return encodeURIComponent(str).replace(
    /[!'()*]/g,
    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
  );
}

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

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

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

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

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

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

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

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

См. также

• decodeURI()
• encodeURI()
• decodeURIComponent()