Signatur
Beschreibung
Die Funktion encodeURI() kodiert einen URI, indem sie jedes Vorkommen bestimmter Zeichen durch eine, zwei, drei oder vier Escape-Sequenzen ersetzt, die die UTF-8-Kodierung des Zeichens repräsentieren (vier Escape-Sequenzen nur bei Zeichen, die aus zwei Surrogate-Zeichen bestehen). Im Vergleich zu encodeURIComponent() kodiert diese Funktion weniger Zeichen und bewahrt jene, die Teil der URI-Syntax sind.
Beschreibung
encodeURI() ist eine Funktionseigenschaft des globalen Objekts.
Die Funktion encodeURI() escaped Zeichen anhand von UTF-8-Codeeinheiten, wobei jedes Oktett im Format %XX kodiert und bei Bedarf links mit 0 aufgefüllt wird. Da einzelne (lone) Surrogates in UTF-16 kein gültiges Unicode-Zeichen kodieren, führen sie dazu, dass encodeURI() einen URIError wirft.
encodeURI() escaped alle Zeichen außer:
A–Z a–z 0–9 - _ . ! ~ * ' ( ); / ? : @ & = + $ , #
Die Zeichen in der zweiten Zeile sind Zeichen, die Teil der URI-Syntax sein können, und werden nur von encodeURIComponent() escaped. Sowohl encodeURI() als auch encodeURIComponent() kodieren die Zeichen -.!~*'(), bekannt als "unreserved marks", nicht, welche keinen reservierten Zweck haben, aber "as is" in einem URI erlaubt sind. (Siehe RFC2396)
Die Funktion encodeURI() kodiert keine Zeichen, die für einen URI eine besondere Bedeutung haben (reservierte Zeichen). Das folgende Beispiel zeigt alle Teile, die ein URI möglicherweise enthalten kann. Beachten Sie, wie bestimmte Zeichen verwendet werden, um eine besondere Bedeutung zu signalisieren:
http://username:password@www.example.com:80/path/to/file.php?foo=316&bar=this+has+spaces#anchor
encodeURI wird, wie der Name andeutet, verwendet, um eine URL als Ganzes zu kodieren, unter der Annahme, dass diese bereits wohlgeformt ist. Wenn Sie String-Werte dynamisch zu einer URL zusammensetzen möchten, sollten Sie stattdessen wahrscheinlich encodeURIComponent() auf jedes dynamische Segment anwenden, um URL-Syntaxzeichen an unerwünschten Stellen zu vermeiden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $uri Pflicht | string | — | Ein String, der als URI kodiert werden soll. |
Rückgabewert
URIError, wenn uri ein einzelnes (lone) Surrogate enthält.Beispiele
encodeURI() vs. encodeURIComponent()
const set1 = ";/?:@&=+$,#"; // Reserved Characters
const set2 = "-.!~*'()"; // Unreserved Marks
const set3 = "ABC abc 123"; // Alphanumeric Characters + Space
console.log(encodeURI(set1)); // ;/?:@&=+$,#
console.log(encodeURI(set2)); // -.!~*'()
console.log(encodeURI(set3)); // ABC%20abc%20123 (the space gets encoded as %20)
console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24%23
console.log(encodeURIComponent(set2)); // -.!~*'()
console.log(encodeURIComponent(set3)); // ABC%20abc%20123 (the space gets encoded as %20)Das Kodieren eines einzelnen Surrogates wirft einen Fehler
// High-low pair OK
encodeURI("\uD800\uDFFF"); // "%F0%90%8F%BF"
// Lone high-surrogate code unit throws "URIError: malformed URI sequence"
encodeURI("\uD800");
// Lone low-surrogate code unit throws "URIError: malformed URI sequence"
encodeURI("\uDFFF");Kodierung für RFC3986
function encodeRFC3986URI(str) {
return encodeURI(str)
.replace(/%5B/g, "[")
.replace(/%5D/g, "]")
.replace(
/[!'()*]/g,
(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
);
}Dynamische Segmente sollten mit encodeURIComponent kodiert werden
const name = "Ben & Jerry's";
// This is bad:
const badLink = encodeURI(`https://example.com/?choice=${name}`); // "https://example.com/?choice=Ben%20&%20Jerry's"
console.log([...new URL(badLink).searchParams]); // [['choice', 'Ben '], [" Jerry's", '']]
// Instead:
const goodLink = `https://example.com/?choice=${encodeURIComponent(name)}`;
// "https://example.com/?choice=Ben%20%26%20Jerry's"
console.log([...new URL(goodLink).searchParams]); // [['choice', "Ben & Jerry's"]]// Wichtig · Fallstricke
Isolierte Surrogate: Enthält der Eingabe-String ein einzelnes (nicht gepaartes) Surrogat-Zeichen, wirft encodeURI() einen URIError: URI malformed. Gültige Surrogate-Paare (Emoji, Zeichen > U+FFFF) werden korrekt kodiert.
Nicht kodierte Zeichen: Die Zeichen # $ & + , / : ; = ? @ sowie - _ . ! ~ * ' ( ) und alphanumerische Zeichen bleiben unverändert. Das kann ein Problem sein, wenn ein Fragezeichen oder Raute versehentlich im Pfad vorkommt – hier encodeURIComponent() bevorzugen.
Browser-Kompatibilität: encodeURI() ist seit ES3 standardisiert und in allen relevanten Browsern und Node.js-Versionen ohne Einschränkungen verfügbar.
Dekodierung: Ein mit encodeURI() kodierter URI kann mit decodeURI() wieder dekodiert werden.