Глобальная функция JavaScript encodeURIComponent()
Определение и применение
Глобальная функция encodeURIComponent() кодирует компонент URI (англ. Uniform Resource Identifier —
унифицированный идентификатор ресурса). Символы, требующие кодирования, представляются байтами UTF-8 (формата записи
текста в байтах). Каждый байт записывается как %XX, где XX — две шестнадцатеричные цифры. Один символ
может занимать от одного до четырёх байтов. Для обратного преобразования используйте
decodeURIComponent().
Функция encodeURIComponent() отличается от метода
encodeURI(). Метод encodeURIComponent() предполагает, что её параметром является не весь URI, а лишь
фрагмент URI (например, значение одного параметра запроса или один сегмент пути). По этой причине он
преобразует все символы за исключением следующих:
// Символы, которые функция не кодирует (A-Z, a-z и 0-9 обозначают диапазоны).
"A-Z a-z 0-9 - _ . ! ~ * ' ( )";
Остальные символы (кроме вышеуказанных) заменяются путем преобразования символа в его код UTF-8 и последующего
кодирования каждого из полученных байтов шестнадцатеричной управляющей последовательностью в формате %xx.
Один символ кодируется от одного до четырёх байтов UTF-8 (способа представления текста в байтах), каждый из которых
записывается как %XX. Например, пробел становится %20, буква «я» — %D1%8F, а
эмодзи «😀» — %F0%9F%98%80. См.
пример с эмодзи и повреждённой строкой.
Метод
encodeURI()
не кодирует зарезервированные символы, имеющие особое значение в URI, а именно:
// Символы, которые функция не кодирует (A-Z, a-z и 0-9 обозначают диапазоны).
"A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #";
Если компоненты URI могут содержать такие символы как ? и # (например, строка запроса), то в этом
случае необходимо кодировать каждый компонент отдельно с помощью функции encodeURIComponent().
Отличие работы методов encodeURIComponent() и
encodeURI()
вы можете увидеть в
примере сравнения кодирования.
Поддержка браузерами
Спецификация: ecma262
Поддерживается во всех основных браузерах с 2015 года.
| Возможность | Компьютеры | Мобильные | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
encodeURIComponent | 1 | 12 | 1 | 7 | 1.1 | 18 | 4 | 10.1 | 1 | 1.0 | 4.4 | 1 |
поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31
JavaScript синтаксис:
encodeURIComponent(str);Спецификация
ECMAScript — encodeURIComponent().
Значения параметров
| Параметр | Описание |
|---|---|
str |
Компонент Uniform Resource Identifier (унифицированный идентификатор ресурса). |
Возвращаемое значение
Новая строка с закодированным текстом. Исходная строка не изменяется. Перед обработкой аргумент преобразуется в
строку; например, число 123 станет "123".
Исключения
| Тип исключения | Описание |
|---|---|
URIError |
Возникает, если строка содержит одиночный суррогат — половину пары кодовых единиц UTF-16, которой представлен
символ. UTF-16 — формат хранения строк JavaScript, в котором некоторые символы занимают две кодовые единицы.
Например, "\uD800" не может быть закодирован как самостоятельный символ.
|
TypeError |
Возникает при передаче Symbol (символьного значения) или другого значения, которое невозможно
преобразовать в строку.
|
Примеры, попробуйте сами
Базовое использование
Как передать амперсанд внутри значения
Добавьте в поисковую фразу пробел, амперсанд или решётку. Проверьте, как они кодируются внутри параметра q.
index.html
<p>Результат выполнения выводится в консоль.</p>
main.js
const value = 'чай & кофе #1'
const encoded = encodeURIComponent(value)
console.log(encoded) // %D1%87%D0%B0%D0%B9%20%26%20%D0%BA%D0%BE%D1%84%D0%B5%20%231
console.log('https://basicweb.ru/?q=' + encoded)
console.log(decodeURIComponent(encoded)) // чай & кофе #1
Отличие работы функций encodeURIComponent() и encodeURI()
Чем кодирование компонента отличается от адреса
Измените строку разделителей и сравните результат двух функций.
index.html
<p>Результат выполнения выводится в консоль.</p>
main.js
const str1 = ';,/?:@&=+$' // Разделители адреса
const str2 = "-_.!~*'()" // Символы, которые обе функции оставляют без изменений
const str3 = '#' // Решётка
const str4 = 'Hello world 2024' // Буквы, цифры и пробелы
console.log(encodeURI(str1)) // ;,/?:@&=+$
console.log(encodeURIComponent(str1)) // %3B%2C%2F%3F%3A%40%26%3D%2B%24
console.log(encodeURI(str2)) // -_.!~*'()
console.log(encodeURIComponent(str2)) // -_.!~*'()
console.log(encodeURI(str3)) // #
console.log(encodeURIComponent(str3)) // %23
console.log(encodeURI(str4)) // Hello%20world%202024
console.log(encodeURIComponent(str4)) // Hello%20world%202024
Как кодируются эмодзи и повреждённые строки
Замените эмодзи другим символом. Сравните корректную строку с одиночной половиной пары UTF-16.
index.html
<p>Результат выполнения выводится в консоль.</p>
main.js
console.log(encodeURIComponent('я 😀')) // %D1%8F%20%F0%9F%98%80
// Одиночная кодовая единица суррогатной пары не задаёт самостоятельный символ.
try {
console.log(encodeURIComponent('\uD800'))
} catch (error) {
console.log(error.name)
} // URIError