CKTIS / JavaScript
String.prototype.matchAll — iterator dopasowań z grupami
String.prototype.matchAll zwraca iterator dopasowań wyrażenia regularnego wraz z grupami przechwytującymi i pozycjami. Dla zwykłego RegExp wymaga flagi g i nie zmienia lastIndex oryginalnego wzorca.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
string.matchAll(regexp)String.prototype.matchAll pozwala przeglądać dopasowania wzorca w tekście. Przy standardowej obsłudze RegExp zwraca leniwy iterator: każde przejście daje tablicę, w której [0] zawiera całe dopasowanie, a [1], [2] itd. — grupy przechwytujące. Niedopasowana opcjonalna grupa ma wartość undefined. Właściwość index wskazuje pozycję w jednostkach kodowych UTF-16, input zawiera tekst wejściowy, a groups udostępnia grupy nazwane, jeśli istnieją.
Jeśli argument zostanie rozpoznany jako wyrażenie regularne, sprawdzenie flagi g następuje przed wyszukaniem metody Symbol.matchAll. Brak tej flagi powoduje zgłoszenie TypeError. Wyszukiwanie uwzględnia również właściwości odziedziczone: jeśli znaleziona wartość jest wywoływalna, matchAll ją wywołuje i zwraca jej wynik. Jeśli właściwość nie istnieje lub ma wartość undefined albo null, matchAll tworzy z argumentu RegExp z flagą g. W tym przypadku argument tekstowy jest wzorcem wyrażenia regularnego, a nie tekstem dosłownym. Każda inna niewywoływalna wartość właściwości Symbol.matchAll powoduje zgłoszenie TypeError.
Standardowa implementacja RegExp tworzy kopię wzorca i ustawia jej początkowe lastIndex na wynik zastosowania operacji ToLength do lastIndex oryginału. Na przykład -1 daje 0, a 2.9 daje 2. Wartość lastIndex oryginału pozostaje bez zmian. Nie zakładaj więc, że wyszukiwanie zawsze zacznie się od zera. Iterator jest jednorazowy: po wyczerpaniu nie zaczyna od nowa. Brak dopasowań oznacza pustą iterację, nie null; użyj for...of do przetwarzania lub [...iterator] do zapisania wyników w tablicy.
W odróżnieniu od match z flagą g, matchAll zachowuje grupy przechwytujące dla każdego dopasowania. Metoda należy do ECMAScript 2020, nie do Web APIs. Sama specyfikacja nie potwierdza obsługi w konkretnej przeglądarce; obecność Node 24 w repozytorium również tego nie dowodzi. W docelowym środowisku można sprawdzić typeof String.prototype.matchAll === "function".
Przykłady
const text = "x=12 y=7";
const pattern = /([a-z])=(\d+)/g;
const matches = text.matchAll(pattern);
for (const match of matches) {
console.log(`${match[0]} | ${match[1]} | ${match[2]} | ${match.index}`);
}
console.log(`lastIndex=${pattern.lastIndex}`);
console.log(`remaining=${[...matches].length}`);Wynik
x=12 | x | 12 | 0 y=7 | y | 7 | 5 lastIndex=0 remaining=0
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.