Segments.prototype.containing() — Methode · JavaScript-Referenz

Signatur

Segments.prototype.containing(codeUnitIndex)

Beschreibung

Die Methode containing() gehört zu dem Segments-Objekt, das Intl.Segmenter.prototype.segment() zurückgibt. Sie findet gezielt das eine Segment, in dem die UTF-16-Code-Einheit an Position codeUnitIndex liegt. Dafür musst du nicht alle Segmente durchlaufen, und als Ergebnis bekommst du dasselbe Datenobjekt, das auch beim Iterieren mit for...of entsteht.

Wie das Ergebnis ausfällt, hängt von der granularity des Segmenters ab: "grapheme" (vom Nutzer wahrgenommene Zeichen, z. B. Emoji mit ZWJ-Folgen), "word" (Wörter, Leerzeichen und Satzzeichen) oder "sentence" (Sätze). Das zurückgegebene Objekt enthält:

segment: den Text des gefundenen Segments,
index: den Index der ersten Code-Einheit dieses Segments im Ausgangstext,
input: den vollständigen segmentierten Text,
isWordLike: nur bei granularity: "word" vorhanden. Der Wert ist true, wenn das Segment ein „echtes“ Wort ist (Buchstaben, Ziffern, Ideogramme), und false bei Leerzeichen oder Satzzeichen.

Typische Einsatzfälle sind das Wort unter dem Cursor in einem Editor (Doppelklick-Auswahl, Rechtschreibprüfung, Autovervollständigung), das sichere Kürzen von Text an Graphemgrenzen und das Bestimmen des Satzes rund um eine Fundstelle.

Parameter

Name	Typ	Default	Beschreibung
$codeUnitIndex	number	0	Index einer UTF-16-Code-Einheit im Ausgangstext. Der Wert wird in eine Ganzzahl umgewandelt (Nachkommastellen werden abgeschnitten, `undefined` und `NaN` werden zu `0`).

Rückgabewert

Typ

{ segment: string, index: number, input: string, isWordLike?: boolean } | undefined

Beschreibung

Ein Segment-Datenobjekt für das Segment, das den Index enthält. Liegt der Index außerhalb des Textes (< 0 oder >= input.length), ist das Ergebnis undefined.

Beispiele

Wort an einer Position bestimmen

const segmenter = new Intl.Segmenter("de", { granularity: "word" });
const segments = segmenter.segment("Das ist ein Test.");

console.log(segments.containing(5));
console.log(segments.containing(3));
console.log(segments.containing(99));

{ segment: 'ist', index: 4, input: 'Das ist ein Test.', isWordLike: true } { segment: ' ', index: 3, input: 'Das ist ein Test.', isWordLike: false } undefined

Grapheme: Emoji-Folgen nicht zerschneiden

const segmenter = new Intl.Segmenter("de", { granularity: "grapheme" });
const text = "👨‍👩‍👧 Familie";
const segments = segmenter.segment(text);

// Index 3 liegt mitten in der ZWJ-Folge
const { segment, index } = segments.containing(3);
console.log(segment, index, segment.length);

👨‍👩‍👧 0 8

Wort unter dem Cursor in einer Textarea

const segmenter = new Intl.Segmenter("de", { granularity: "word" });

const wordAtCursor = (text, cursor) => {
  const segments = segmenter.segment(text);
  // Steht der Cursor am Textende oder direkt hinter einem Wort, eine Position zurückgehen
  let hit = segments.containing(cursor);
  if (!hit?.isWordLike && cursor > 0) hit = segments.containing(cursor - 1);
  return hit?.isWordLike ? hit.segment : null;
};

console.log(wordAtCursor("Hallo Welt", 10));
console.log(wordAtCursor("Hallo Welt", 2));
console.log(wordAtCursor("Hallo, Welt", 6));

Welt Hallo null

Satz rund um eine Fundstelle ermitteln

const segmenter = new Intl.Segmenter("de", { granularity: "sentence" });
const text = "JavaScript ist vielseitig. Intl hilft bei Sprachen. Viel Spaß!";

const pos = text.indexOf("Intl");
const { segment } = segmenter.segment(text).containing(pos);
console.log(segment.trim());

Intl hilft bei Sprachen.

// Wichtig · Fallstricke

Code-Einheiten, keine Zeichen: Der Index bezieht sich auf UTF-16-Code-Einheiten, so wie String.prototype.length und indexOf() zählen. Ein Emoji kann 2 oder mehr Einheiten belegen. Das Ergebnis enthält aber immer das vollständige Segment.
Index am Textende: containing(text.length) liefert undefined. Das betrifft vor allem Cursor-Positionen (selectionStart), die hinter dem letzten Zeichen stehen können. Prüfe daher auch index - 1.
Negative Indizes zählen nicht vom Ende her wie bei Array.prototype.at(), sondern ergeben undefined.
isWordLike gibt es nur bei granularity: "word". Bei "grapheme" und "sentence" fehlt die Eigenschaft.
Die Grenzen hängen von der Locale und von den Unicode- bzw. ICU-Daten der Engine ab (z. B. bei Japanisch, Thai oder Abkürzungen mit Punkt). Die Ergebnisse können sich deshalb zwischen Browsern und Versionen leicht unterscheiden.
Kompatibilität: Intl.Segmenter gibt es in Chrome/Edge 87+, Safari 14.1+, Firefox 125+ und Node.js 16+. Für ältere Umgebungen brauchst du einen Polyfill (z. B. von FormatJS).
Leistung: Wenn du den Text mehrfach abfragst, verwende das Segments-Objekt und den Intl.Segmenter weiter, statt sie bei jedem Aufruf neu zu erzeugen.

Siehe auch

Intl.Segmenter Intl.Segmenter.prototype.segment() String.prototype.at() String.prototype.codePointAt() Segments.prototype[Symbol.iterator]()