Глобальная функция JavaScript encodeURI()

Определение и применение

Глобальная функция encodeURI() кодирует URI (англ. Uniform Resource Identifier — унифицированный идентификатор ресурса). Символы, требующие кодирования, представляются байтами UTF-8 (формата записи текста в байтах). Каждый байт записывается как %XX, где XX — две шестнадцатеричные цифры. Один символ может занимать от одного до четырёх байтов. Для обратного преобразования используйте decodeURI().

Функция encodeURI() не кодирует зарезервированные символы, имеющие особое значение в 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. См. пример с эмодзи и повреждённой строкой.

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

// Символы, которые функция не кодирует (A-Z, a-z и 0-9 обозначают диапазоны).
"A-Z a-z 0-9 - _ . ! ~ * ' ( )";

Если компоненты URI могут содержать такие символы как ? и # (например, строка запроса), то в этом случае необходимо кодировать каждый компонент отдельно с помощью функции encodeURIComponent().

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

Поддержка браузерами

Спецификация: ecma262

✓Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры

ВсеКомпьютерыМобильные

Совместимостьjavascript.builtins.encodeURI

Возможность	Компьютеры					Мобильные
	ChromeChrome	EdgeEdge	FirefoxFirefox	OperaOpera	SafariSafari	Chrome AndroidChromeAndroid	Firefox for AndroidFirefoxAndroid	Opera AndroidOperaAndroid	Safari on iOSSafariiOS	Samsung BrowserSamsungAndroid	WebView AndroidWebViewAndroid	WebView on iOSWebViewiOS
encodeURI	✓1	✓12	✓1	✓7	✓1.1	✓18	✓4	✓10.1	✓1	✓1.0	✓4.4	✓1

✓поддерживается◐с ограниченияминет поддержки?нет данных≤31 — не позднее версии 31

JavaScript синтаксис:

encodeURI(URI);

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

ECMAScript — encodeURI().

Значения параметров

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

Новая строка с закодированным текстом. Исходная строка не изменяется. Перед обработкой аргумент преобразуется в строку; например, число 123 станет "123".

Исключения

Примеры, попробуйте сами

Базовое использование

Как закодировать адрес с кириллицей

Измените текст параметра q. Обратите внимание: разделители адреса сохраняются.

index.html

HTML

<p>Результат выполнения выводится в консоль.</p>

main.js

JavaScript

const uri = 'https://basicweb.ru/?q=справочник'
const encoded = encodeURI(uri) // кодируем URI
console.log(encoded) // "https://basicweb.ru/?q=%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA"

const decoded = decodeURI(encoded) // декодируем URI
console.log(decoded) // "https://basicweb.ru/?q=справочник"

Отличие работы функций encodeURIComponent() и encodeURI()

Какие разделители сохраняет encodeURI()

Измените строку разделителей и сравните результат двух функций.

index.html

HTML

<p>Результат выполнения выводится в консоль.</p>

main.js

JavaScript

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

HTML

<p>Результат выполнения выводится в консоль.</p>

main.js

JavaScript

console.log(encodeURI('я 😀')) // %D1%8F%20%F0%9F%98%80
// Одиночная кодовая единица суррогатной пары не задаёт самостоятельный символ.
try {
    console.log(encodeURI('\uD800'))
} catch (error) {
    console.log(error.name)
} // URIError