encodeURIComponent()

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

Спробуйте його в дії

Синтаксис

encodeURIComponent(uriComponent)

Параметри

uriComponent

Рядок для кодування як компонента URI (шляху, рядка запиту, фрагмента тощо). Інші значення – перетворюються на рядки.

Повернене значення

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

Винятки

URIError

Викидається, коли uriComponent містить самотній сурогат.

Опис

encodeURIComponent() – це функція, що є властивістю глобального об'єкта.

encodeURIComponent() використовує такий же алгоритм кодування, як описаний для encodeURI(). Він екранує усі символи, окрім:

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

Порівняно з encodeURI(), encodeURIComponent() екранує більшу множину символів. Функцію encodeURIComponent() слід застосовувати на введених користувачем полях форм, що надсилаються на сервер за допомогою POST: вона екранує символи &, що можуть ненавмисно бути додані при введенні даних для певних сутностей HTML, та інші символи, що вимагають кодування й розкодування. Наприклад, якщо користувач напише Jack & Jill, то без encodeURIComponent() амперсанд може бути розтлумачений сервером як початок нового поля й поставити під загрозу цілісність даних.

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

Приклади

Кодування для заголовків Content-Disposition і Link

Наступний приклад демонструє особливе кодування, що вимагається в параметрах заголовків відповідей сервера Content-Disposition і Link в UTF-8 (наприклад, імена файлів у 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)
      // Рядок нижче утворює послідовності %27 %28 %29 %2A (Зверніть увагу, що
      // дійсне кодування "*" – це %2A, з чого випливає потреба викликати
      // toUpperCase() для коректного кодування). І хоча RFC3986 резервує "!",
      // RFC5987 – ні, тому цей символ немає потреби екранувати.
      .replace(
        /['()*]/g,
        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
      )
      // Наступне не обов'язково для процентного кодування згідно з RFC5987,
      // тож можна дозволити трохи кращу прочитність по той бік дроту: |`^
      .replace(/%(7C|60|5E)/g, (str, hex) =>
        String.fromCharCode(parseInt(hex, 16)),
      )
  );
}

Кодування для RFC3986

Новіший стандарт RFC3986 резервує !, ', (, ) і *, навіть попри те, що ці символи не мають формалізованого використання як обмежувачі в URI. Наступна функція кодує рядок у сумісному з RFC3986 форматі компонента URL. Також вона кодує [ і ], котрі є частиною синтаксису URI IPv6. Сумісна з RFC3986 реалізація encodeURI їх екранувати не повинна, що продемонстровано в прикладі encodeURI().

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

Кодування самотнього сурогату викидає помилку

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

// Пара старший-молодший – ОК
encodeURIComponent("\uD800\uDFFF"); // "%F0%90%8F%BF"
// Самотня старшосурогатна кодова одиниця викидає помилку "URIError: malformed URI sequence"
encodeURIComponent("\uD800");
// Самотня старшосурогатна кодова одиниця викидає помилку "URIError: malformed URI sequence"
encodeURIComponent("\uDFFF");

Можна скористатися методом String.prototype.toWellFormed(), котрий замінює самотні сурогати на символ заміни Unicode (U+FFFD), щоб уникнути цієї помилки. Також можна скористатися методом String.prototype.isWellFormed(), щоб перевірити, чи містить рядок самотні сурогати, перед тим, як передати його у encodeURIComponent().

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

Сумісність із браузерами

Дивіться також

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