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: вона екранує символи &, що можуть ненавмисно бути додані при введенні даних символьних посилань, та інші символи, що вимагають кодування й розкодування. Наприклад, якщо користувач напише Jack & Jill, то без encodeURIComponent() амперсанд може бути розтлумачений сервером як початок нового поля й поставити під загрозу цілісність даних.

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

Приклади

Наступний приклад демонструє особливе кодування, що вимагається в параметрах заголовків відповідей сервера 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().

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

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

desktop mobile server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet Deno Node.js
encodeURIComponent
Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 5.5
Opera Full support 7
Safari Full support 1.1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0

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