encodeURIComponent()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Die Funktion encodeURIComponent()
kodiert eine URI, indem sie jede Instanz bestimmter Zeichen durch eine, zwei, drei oder vier Escape-Sequenzen ersetzt, die die UTF-8-Kodierung des Zeichens darstellen (es werden nur vier Escape-Sequenzen für Zeichen verwendet, die aus zwei Surrogat-Zeichen bestehen). Im Vergleich zu encodeURI()
kodiert diese Funktion mehr Zeichen, einschließlich solcher, die Teil der URI-Syntax sind.
Probieren Sie es aus
// 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"
Syntax
encodeURIComponent(uriComponent)
Parameter
uriComponent
-
Eine Zeichenkette, die als URI-Komponente (ein Pfad, Abfragezeichenfolge, Fragment usw.) kodiert werden soll. Andere Werte werden in Zeichenketten umgewandelt.
Rückgabewert
Eine neue Zeichenkette, die den bereitgestellten uriComponent
als URI-Komponente kodiert darstellt.
Ausnahmen
URIError
-
Wird ausgelöst, wenn
uriComponent
ein einsames Surrogat enthält.
Beschreibung
encodeURIComponent()
ist eine Funktions-Eigenschaft des globalen Objekts.
encodeURIComponent()
verwendet denselben Kodierungsalgorithmus wie in encodeURI()
beschrieben. Es maskiert alle Zeichen außer:
A–Z a–z 0–9 - _ . ! ~ * ' ( )
Im Vergleich zu encodeURI()
maskiert encodeURIComponent()
eine größere Anzahl Zeichen. Verwenden Sie encodeURIComponent()
für von Benutzern ausgefüllte Formularfelder, die mit POST
an den Server gesendet werden. Dies kodiert beispielsweise &
-Symbole, die während der Dateneingabe unbeabsichtigt generiert werden könnten, z. B. bei der Eingabe von Zeichenreferenzen oder anderen Zeichen, die eine Kodierung/Decodierung erfordern. Zum Beispiel, wenn ein Benutzer Jack & Jill
eingibt, könnte das kaufmännische Und-Zeichen ohne encodeURIComponent()
vom Server als Beginn eines neuen Feldes interpretiert werden und die Datenintegrität gefährden.
Für die Kodierung von application/x-www-form-urlencoded
sollten Leerzeichen durch +
ersetzt werden. Daher könnte es sinnvoll sein, nach einem encodeURIComponent()
-Aufruf
durch +
zu ersetzen.
Beispiele
Kodierung für Content-Disposition- und Link-Header
Das folgende Beispiel zeigt die spezielle Kodierung, die innerhalb der UTF-8-Parameter von Content-Disposition
- und Link
-Serverantwort-Headern erforderlich ist (z. B. UTF-8-Dateinamen):
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)),
)
);
}
Kodierung für RFC3986
Die neuere RFC3986 reserviert !
, '
, (
, )
, und *
, obwohl diese Zeichen keine formalisierte Verwendung als URI-Delimitierungszeichen haben. Die folgende Funktion kodiert eine Zeichenkette in ein URI-kompatibles Format gemäß RFC3986. Sie kodiert auch [
und ]
, die Teil der IPv6-URI-Syntax sind. Eine RFC3986-konforme Implementierung von encodeURI
sollte diese Zeichen nicht maskieren, was im Beispiel von encodeURI()
demonstriert wird.
function encodeRFC3986URIComponent(str) {
return encodeURIComponent(str).replace(
/[!'()*]/g,
(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
);
}
Kodierung eines einsamen Surrogats löst Fehler aus
Ein URIError
wird ausgelöst, wenn Sie versuchen, ein Surrogat, das kein Teil eines High-Low-Paares ist, zu kodieren. Zum Beispiel:
// 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");
Sie können String.prototype.toWellFormed()
verwenden, das einsame Surrogate durch das Unicode-Ersatzzeichen (U+FFFD) ersetzt, um diesen Fehler zu vermeiden. Sie können auch String.prototype.isWellFormed()
verwenden, um zu überprüfen, ob eine Zeichenkette einsame Surrogate enthält, bevor sie an encodeURIComponent()
übergeben wird.
Spezifikationen
Specification |
---|
ECMAScript® 2025 Language Specification # sec-encodeuricomponent-uricomponent |
Browser-Kompatibilität
Report problems with this compatibility data on GitHubdesktop | mobile | server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
encodeURIComponent |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support