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

js
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

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):

js
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.

js
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:

js
// 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 GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
encodeURIComponent

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Siehe auch