База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

String.prototype.matchAll — итератор на съвпадения с групи за улавяне

String.prototype.matchAll връща итератор на съвпаденията на регулярен израз, включително групите за улавяне и позициите. При обикновен RegExp е задължителен флагът g, а lastIndex на оригиналния шаблон остава непроменен.

Версия: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Синтаксис

string.matchAll(regexp)

String.prototype.matchAll позволява да обхождате съвпаденията на шаблон в текст. При стандартното поведение на RegExp връща ленив итератор: всяка стъпка дава масив, в който [0] съдържа цялото съвпадение, а [1], [2] и следващите елементи съдържат групите за улавяне. Незадължителна група без съвпадение има стойност undefined. Свойството index указва позицията в UTF-16 кодови единици, input съдържа входния текст, а groups предоставя именуваните групи, ако има такива.

Ако аргументът е разпознат като регулярен израз, matchAll проверява за флага g, преди да потърси Symbol.matchAll. Ако флагът липсва, извикването хвърля TypeError. Търсенето обхваща и наследените свойства: ако намерената стойност може да бъде извикана, matchAll я извиква и връща резултата ѝ. Ако свойството липсва или стойността му е undefined или null, matchAll създава от аргумента RegExp с флага g. В този случай низът се тълкува като шаблон на регулярен израз, а не като буквален текст. Всяка друга стойност на Symbol.matchAll, която не може да бъде извикана, води до TypeError.

Стандартната реализация на RegExp създава копие на шаблона и задава началната стойност на lastIndex на копието, като прилага операцията ToLength към lastIndex на оригинала. Например -1 става 0, а 2.9 става 2. Стойността на lastIndex на оригинала остава непроменена. Затова не приемайте, че търсенето винаги започва от нула. Итераторът може да се използва само веднъж: след изчерпване не започва отначало. Липсата на съвпадения означава празна итерация, а не null; използвайте for...of, за да обработите резултатите, или [...iterator], за да ги запазите в масив.

За разлика от match с флага g, matchAll запазва групите за улавяне за всяко съвпадение. Методът е част от ECMAScript 2020, а не от Web APIs. Самата спецификация не доказва поддръжка в конкретен браузър; наличието на Node 24 в хранилище също не е доказателство. Наличността в целевата среда може да се провери с typeof String.prototype.matchAll === "function".

Примери

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}`);

Резултат

x=12 | x | 12 | 0
y=7 | y | 7 | 5
lastIndex=0
remaining=0

Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.

Източници