--- title: String.prototype.matchAll() slug: Web/JavaScript/Reference/Global_Objects/String/matchAll tags: - JavaScript - String - Регулярні Вирази - метод translation_of: Web/JavaScript/Reference/Global_Objects/String/matchAll ---
{{JSRef}}

Метод matchAll() повертає ітератор з усіма збігами рядка з регулярним виразом, а також захоплені групи.

{{EmbedInteractiveExample("pages/js/string-matchall.html")}}

Синтаксис

str.matchAll(regexp)

Параметри

regexp

Об'єкт регулярного виразу.

Якщо передано об'єкт obj, який не є регулярним виразом, він неявно перетворюється на {{jsxref("RegExp")}} за допомогою new RegExp(obj).

Об'єкт RegExp повинен мати прапор /g, інакше буде викинуто помилку TypeError.

Значення, що повертається

Ітератор (ітерабельний об'єкт, який не можна повторно запустити).

Приклади

Regexp.exec() та matchAll()

До появи у JavaScript методу matchAll можна було використовувати виклики regexp.exec (а також регулярні вирази з прапором /g) у циклі, щоб отримати усі збіги:

const regexp = RegExp('фу[а-я]*','g');
const str = 'настільний футбол, фусбол';
let match;

while ((match = regexp.exec(str)) !== null) {
  console.log(`Знайдено ${match[0]} початок=${match.index} кінець=${regexp.lastIndex}.`);
  // виведе: "Знайдено футбол початок=11 кінець=17."
  // виведе: "Знайдено фусбол початок=19 кінець=25."
}

З методом matchAll можна уникнути використання циклу {{jsxref("Statements/while", "while")}} та методу exec з g.

Замість цього, використовуючи matchAll, ви отримуєте ітератор, який можна використовувати з більш зручними конструкціями {{jsxref("Statements/for...of", "for...of")}}, {{jsxref("Operators/Spread_syntax", "розкладанням масиву")}} чи {{jsxref("Array.from()")}}:

const regexp = RegExp('фу[а-я]*','g');
const str = 'настільний футбол, фусбол';
const matches = str.matchAll(regexp);

for (const match of matches) {
  console.log(`Знайдено ${match[0]} початок=${match.index} кінець=${match.index + match[0].length}.`);
}
// виведе: "Знайдено футбол початок=11 кінцець=17."
// виведе: "Знайдень фусбол початок=19 кінець=25."

// Ітератор matches є вичерпаним після перебору for..of
// Викличте matchAll ще раз, щоб створити новий ітератор
Array.from(str.matchAll(regexp), m => m[0]);
// Array [ "футбол", "фусбол" ]

Метод matchAll викине виняток, якщо прапор g відсутній.

const regexp = RegExp('[а-в]','');
const str = 'абв';
str.matchAll(regexp);
// TypeError

matchAll робить внутрішній клон regexp, тому, на відміну від {{jsxref("Global_Objects/RegExp/exec", "regexp.exec()")}}, lastIndex не змінюється під час пошуку.

const regexp = RegExp('[а-в]','g');
regexp.lastIndex = 1;
const str = 'абв';
Array.from(str.matchAll(regexp), m => `${regexp.lastIndex} ${m[0]}`);
// Array [ "1 б", "1 в" ]

Кращий доступ до захоплених груп (ніж у String.prototype.match())

Ще одна приваблива причина використовувати matchAll - покращений доступ до захоплених груп.

Захоплені групи ігноруються при використанні {{jsxref("Global_Objects/String/match", "match()")}} з глобальним прапором /g:

let regexp = /т(е)(ст(\d?))/g;
let str = 'тест1тест2';

str.match(regexp);
// Array ['тест1', 'тест2']

Використовуючи matchAll, ви можете легко звертатись до захоплених груп:

let array = [...str.matchAll(regexp)];

array[0];
// ['тест1', 'е', 'ст1', '1', index: 0, input: 'тест1тест2', length: 4]
array[1];
// ['тест2', 'е', 'ст2', '2', index: 5, input: 'тест1тест2', length: 4]

Специфікації

Специфікація
{{SpecName('ESDraft', '#sec-string.prototype.matchall', 'String.prototype.matchAll')}}

Сумісність з веб-переглядачами

{{Compat("javascript.builtins.String.matchAll")}}

Див. також