Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

String.prototype.matchAll — un iterador de coincidencias con grupos de captura

String.prototype.matchAll devuelve un iterador de coincidencias de una expresión regular, incluidos los grupos de captura y las posiciones. Con un RegExp normal se requiere la bandera g y no se modifica el lastIndex del patrón original.

Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxis

string.matchAll(regexp)

String.prototype.matchAll permite recorrer las coincidencias de un patrón en un texto. Con el comportamiento estándar de RegExp, devuelve un iterador perezoso: cada paso produce un array cuyo [0] contiene la coincidencia completa y cuyos [1], [2], etc. contienen los grupos de captura. Un grupo opcional sin coincidencia tiene el valor undefined. La propiedad index indica la posición en unidades de código UTF-16, input contiene el texto de entrada y groups expone los grupos con nombre, si los hay.

Si el argumento se reconoce como una expresión regular, matchAll comprueba que tenga la bandera g antes de buscar Symbol.matchAll. Si falta la bandera, la llamada lanza un TypeError. La búsqueda también tiene en cuenta las propiedades heredadas: si el valor encontrado se puede invocar, matchAll lo invoca y devuelve su resultado. Si la propiedad no existe o su valor es undefined o null, matchAll crea un RegExp a partir del argumento con la bandera g. En este caso, una cadena se interpreta como un patrón de expresión regular, no como texto literal. Cualquier otro valor de Symbol.matchAll que no se pueda invocar provoca un TypeError.

La implementación estándar de RegExp crea una copia del patrón y establece su lastIndex inicial en el resultado de aplicar ToLength al lastIndex del original. Por ejemplo, -1 se convierte en 0 y 2.9 se convierte en 2. El lastIndex del original no cambia. Por tanto, no supongas que la búsqueda siempre empieza en cero. El iterador solo se puede usar una vez: cuando se agota, no vuelve a empezar. Si no hay coincidencias, se obtiene una iteración vacía, no null; usa for...of para procesar los resultados o [...iterator] para guardarlos en un array.

A diferencia de match con la bandera g, matchAll conserva los grupos de captura de cada coincidencia. El método forma parte de ECMAScript 2020, no de las Web APIs. La especificación por sí sola no demuestra que sea compatible con un navegador concreto; la presencia de Node 24 en un repositorio tampoco lo demuestra. En el entorno de destino, se puede comprobar su disponibilidad con typeof String.prototype.matchAll === "function".

Ejemplos

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

Resultado

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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes