このページはコミュニティーの尽力で英語から翻訳されました。MDN Web Docsコミュニティーについてもっと知り、仲間になるにはこちらから。
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 2020年1月.
matchAll() はString 値のメソッドで、この文字列と正規表現を照合したすべての結果を、キャプチャグループを含み、イテレーターで返すメソッドです。
試してみましょう
const regexp = /t(e)(st(\d?))/g;const str = "test1test2";const array = [...str.matchAll(regexp)];console.log(array[0]);// 予想される結果: Array ["test1", "e", "st1", "1"]console.log(array[1]);// 予想される結果: Array ["test2", "e", "st2", "2"]構文
matchAll(regexp)引数
regexp正規表現オブジェクト、または
Symbol.matchAllを持つ任意のオブジェクトです。regexpがRegExp以外のオブジェクトであった場合、暗黙的にRegExpへの変換がnew RegExp(regexp, 'g')を使用して行われます。regexpが正規表現である場合、グローバルフラグ (g) が設定されます。そうでなければTypeErrorが発生します。
返値
一致したものの反復可能なイテレーターオブジェクト（再起動不可能なもの）、または一致するものがなければ空のイテレーターです。イテレーターが生成するそれぞれの値は、RegExp.prototype.exec() の返値と同じ形です。
例外
解説
String.prototype.matchAll の実装は、引数に対応するSymbol.matchAll メソッドを、最初の引数として文字列を指定して呼び出すだけです（正規表現がグローバルであるかどうかを検証する部分を除く）。実際の実装はRegExp.prototype[Symbol.matchAll]() から来ています。
例
Regexp.prototype.exec() と matchAll()
matchAll() が JavaScript に追加される前は、regexp.exec（および/g フラグ付きの正規表現）をループの中で呼び出すことですべての一致結果を取得することができました。
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.matchAll() が使えるようになったことで、while によるループと、g 付きのexec を避けることができます。代わりにイテレーターが取得できるので、for...of、配列スプレッド、Array.from() 構造と効率よく組み合わせることができます。
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.// 一致したイテレーターは for...of の反復処理の後で利用不可になる// 新しいイテレーターを作成するために matchAll を再度呼び出すArray.from(str.matchAll(regexp), (m) => m[0]);// [ "football", "foosball" ]matchAll は、グローバル (g) フラグがない場合は例外が発生します。
const regexp = /[a-c]/;const str = "abc";str.matchAll(regexp);// TypeErrormatchAll では内部的にregexp の複製を作成します。そのためregexp.exec() とは違って文字列をスキャンした際にlastIndex が変わることはありません。
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" ]しかし、これはregexp.exec() をループ内で使うのとは異なり、正規表現を進めたり戻したりするためにlastIndex を変更することができないことを意味します。
キャプチャリンググループへのより良いアクセス（String.prototype.match() との比較）
matchAll はキャプチャグループへのよりよいアクセスを実現します。
match() では、グローバルg フラグを使用するとキャプチャグループが無視されてしまいます。
const regexp = /t(e)(st(\d?))/g;const str = "test1test2";str.match(regexp); // ['test1', 'test2']matchAll を使えば簡単にキャプチャグループにアクセスできます。
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]matchAll() を RegExp ではない[Symbol.matchAll]() を実装しているオブジェクトで使用
オブジェクトにSymbol.matchAll メソッドがあれば、それをカスタムマッチャーとして使うことができます。Symbol.matchAll の返値はmatchAll() の返値となる。
const str = "Hmm, this is interesting.";str.matchAll({ [Symbol.matchAll](str) { return [["Yes, it's interesting."]]; },}); // [["Yes, it's interesting."]] を返す仕様書
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-string.prototype.matchall |