String.prototype.codePointAt() — Methode · JavaScript-Referenz

Signatur

String.prototype.codePointAt(index)

Beschreibung

codePointAt() liest den vollständigen Unicode-Codepunkt an einer Position eines Strings. Anders als charCodeAt(), das immer nur eine einzelne UTF-16-Codeeinheit (0–65535) liefert, erkennt codePointAt() Surrogatpaare und setzt sie zum echten Codepunkt zusammen. Dadurch erhält man z. B. für Emojis oder seltene CJK-Zeichen (Werte über 0xFFFF) den korrekten Wert.

Wichtig: Der index bezieht sich weiterhin auf UTF-16-Codeeinheiten, nicht auf Zeichen. Steht der Index auf einem führenden (hohen) Surrogat, wird das ganze Paar ausgewertet. Steht er auf dem nachfolgenden (niedrigen) Surrogat, wird nur dieses einzelne Surrogat zurückgegeben. Liegt der Index außerhalb des Strings, ist das Ergebnis undefined.

Typische Einsatzgebiete sind Zeichenklassifizierung (z. B. „Ist das ein Emoji?“), Hex-Ausgabe von Codepunkten wie U+1F600, eigene Encoder/Parser sowie das Gegenstück zu String.fromCodePoint(). Um über alle Zeichen eines Strings zu iterieren, kombiniert man die Methode am besten mit for...of oder dem Spread-Operator, die bereits Codepunkt-weise iterieren.

Parameter

Name	Typ	Default	Beschreibung
$index	number	0	Nullbasierter Index der UTF-16-Codeeinheit, an der das Zeichen beginnt. Wird in eine Ganzzahl umgewandelt; `undefined` und `NaN` werden zu `0`.

Rückgabewert

Typ

number | undefined

Beschreibung

Der Codepunkt (0 bis 0x10FFFF) am angegebenen Index. Bei einem führenden Surrogat mit gültigem Partner der kombinierte Wert, bei einem einzelnen Surrogat dessen Codeeinheit. undefined, wenn index kleiner als 0 oder größer/gleich length ist.

Beispiele

Unterschied zu charCodeAt() bei Emojis

const smiley = '😀';

console.log(smiley.length);            // 2 Codeeinheiten
console.log(smiley.charCodeAt(0));     // hohes Surrogat
console.log(smiley.codePointAt(0));    // echter Codepunkt
console.log(smiley.codePointAt(1));    // nur niedriges Surrogat
console.log(smiley.codePointAt(5));    // außerhalb

2 55357 128512 56832 undefined

Codepunkte aller Zeichen als U+XXXX ausgeben

const toCodePoints = (text) =>
  [...text].map((char) =>
    'U+' + char.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')
  );

console.log(toCodePoints('Aä€🚀'));

[ 'U+0041', 'U+00E4', 'U+20AC', 'U+1F680' ]

Zeichen außerhalb der BMP erkennen (z. B. für Validierung)

const hasAstralChars = (text) => {
  for (const char of text) {
    if (char.codePointAt(0) > 0xFFFF) return true;
  }
  return false;
};

console.log(hasAstralChars('Hallo Welt'));
console.log(hasAstralChars('Party 🎉'));

false true

Roundtrip mit String.fromCodePoint()

const original = '𝄞';
const cp = original.codePointAt(0);
const restored = String.fromCodePoint(cp);

console.log(cp, restored === original);

119070 true

// Wichtig · Fallstricke

Index zählt Codeeinheiten, nicht Zeichen: Eine klassische for (let i = 0; i < str.length; i++)-Schleife trifft bei Surrogatpaaren zusätzlich das niedrige Surrogat und liefert dafür einen „kaputten“ Wert. Besser for...of bzw. [...str] nutzen oder i bei Werten > 0xFFFF um 2 erhöhen.
Kein Graphem-Cluster: Zusammengesetzte Emojis (z. B. 👨‍👩‍👧 oder Flaggen) und Zeichen mit kombinierenden Akzenten bestehen aus mehreren Codepunkten. Für „sichtbare Zeichen“ ist Intl.Segmenter das richtige Werkzeug.
Negativer Index: Anders als at() unterstützt codePointAt() keine negativen Indizes – das Ergebnis ist undefined.
Einzelne (verwaiste) Surrogate werden ohne Fehler als Wert zwischen 0xD800 und 0xDFFF zurückgegeben; mit String.prototype.isWellFormed() (ES2024) lässt sich das vorab prüfen.
Kompatibilität: Seit ES2015 in allen modernen Browsern und Node.js verfügbar; nur der Internet Explorer benötigt ein Polyfill.

Siehe auch

String.prototype.charCodeAt() String.fromCodePoint() String.fromCharCode() String.prototype.at() String.prototype.isWellFormed() Intl.Segmenter