String.prototype.matchAll()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Die matchAll()
-Methode von String
-Werten gibt einen Iterator mit allen Ergebnissen zurück, die mit diesem String und einem regulären Ausdruck übereinstimmen, einschließlich Gruppen für das Erfassen.
Probieren Sie es aus
const regexp = /t(e)(st(\d?))/g;
const str = "test1test2";
const array = [...str.matchAll(regexp)];
console.log(array[0]);
// Expected output: Array ["test1", "e", "st1", "1"]
console.log(array[1]);
// Expected output: Array ["test2", "e", "st2", "2"]
Syntax
matchAll(regexp)
Parameter
regexp
-
Ein reguläres Ausdrucksobjekt oder ein beliebiges Objekt, das eine
Symbol.matchAll
-Methode besitzt.Falls
regexp
keinRegExp
-Objekt ist und keineSymbol.matchAll
-Methode besitzt, wird es implizit in einRegExp
umgewandelt, indemnew RegExp(regexp, 'g')
verwendet wird.Wenn
regexp
ein regulärer Ausdruck ist, dann muss es das globale (g
)-Flag gesetzt haben, ansonsten wird einTypeError
ausgelöst.
Rückgabewert
Ein iterierbares Iterator-Objekt (das nicht erneut gestartet werden kann) mit Übereinstimmungen oder ein leerer Iterator, falls keine Übereinstimmungen gefunden werden. Jeder vom Iterator ausgegebene Wert ist ein Array mit derselben Struktur wie der Rückgabewert von RegExp.prototype.exec()
.
Ausnahmen
TypeError
-
Wird ausgelöst, wenn
regexp
ein regulärer Ausdruck ist, der das globale (g
)-Flag nicht gesetzt hat (seineflags
-Eigenschaft enthält nicht"g"
).
Beschreibung
Die Implementierung von String.prototype.matchAll
führt nicht viel aus, außer, dass sie die Symbol.matchAll
-Methode des Arguments mit dem String als erstem Parameter aufruft (abgesehen von der zusätzlichen Überprüfung, dass der reguläre Ausdruck global ist). Die eigentliche Implementierung stammt von RegExp.prototype[Symbol.matchAll]()
.
Beispiele
Regexp.prototype.exec() und matchAll()
Ohne matchAll()
ist es möglich, durch Aufrufe von regexp.exec()
(und regulären Ausdrücken mit dem g
-Flag) in einer Schleife alle Übereinstimmungen zu erhalten:
const regexp = /foo[a-z]*/g;
const str = "table football, foosball";
let match;
while ((match = regexp.exec(str)) !== null) {
console.log(
`Found ${match[0]} start=${match.index} end=${regexp.lastIndex}.`,
);
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.
Mit matchAll()
können Sie die while
-Schleife und exec
mit g
vermeiden. Stattdessen erhalten Sie einen Iterator, den Sie mit den praktischeren for...of
-, Array-Spreading- oder Array.from()
-Konstrukten nutzen können:
const regexp = /foo[a-z]*/g;
const str = "table football, foosball";
const matches = str.matchAll(regexp);
for (const match of matches) {
console.log(
`Found ${match[0]} start=${match.index} end=${
match.index + match[0].length
}.`,
);
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.
// matches iterator is exhausted after the for...of iteration
// Call matchAll again to create a new iterator
Array.from(str.matchAll(regexp), (m) => m[0]);
// [ "football", "foosball" ]
matchAll
löst eine Ausnahme aus, wenn das g
-Flag fehlt.
const regexp = /[a-c]/;
const str = "abc";
str.matchAll(regexp);
// TypeError
matchAll
erstellt intern eine Kopie des regexp
— im Gegensatz zu regexp.exec()
ändert sich lastIndex
nicht, während der String durchsucht wird.
const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = "abc";
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`);
// [ "1 b", "1 c" ]
Dies bedeutet jedoch, dass Sie im Gegensatz zu der Verwendung von regexp.exec()
in einer Schleife lastIndex
nicht ändern können, um den regulären Ausdruck vor- oder zurückzusetzen.
Besserer Zugriff auf Erfassungsgruppen (als String.prototype.match())
Ein weiterer überzeugender Grund für matchAll
ist der verbesserte Zugriff auf Erfassungsgruppen.
Erfassungsgruppen werden ignoriert, wenn match()
mit dem globalen g
-Flag verwendet wird:
const regexp = /t(e)(st(\d?))/g;
const str = "test1test2";
str.match(regexp); // ['test1', 'test2']
Mit matchAll
können Sie leicht auf Erfassungsgruppen zugreifen:
const array = [...str.matchAll(regexp)];
array[0];
// ['test1', 'e', 'st1', '1', index: 0, input: 'test1test2', length: 4]
array[1];
// ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4]
Verwendung von matchAll() mit einem Nicht-RegExp, das [Symbol.matchAll]()
implementiert
Wenn ein Objekt eine Symbol.matchAll
-Methode besitzt, kann es als benutzerdefinierter Matcher verwendet werden. Der Rückgabewert von Symbol.matchAll
wird dabei der Rückgabewert von matchAll()
.
const str = "Hmm, this is interesting.";
str.matchAll({
[Symbol.matchAll](str) {
return [["Yes, it's interesting."]];
},
}); // returns [["Yes, it's interesting."]]
Spezifikationen
Specification |
---|
ECMAScript® 2025 Language Specification # sec-string.prototype.matchall |
Browser-Kompatibilität
Report problems with this compatibility data on GitHubdesktop | mobile | server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
matchAll |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support