String.prototype.replaceAll()

Метод replaceAll() (замінити все) значень String повертає новий рядок, в якому всі збіги з патерном pattern замінені переданим значенням replacement. Значенням pattern може бути як рядок, так і RegExp, а replacement може бути рядком або функцією, яка буде викликана для кожного знайденого збігу.Початковий рядок залишається незмінним.

Спробуйте його в дії

Синтаксис

replaceAll(pattern, replacement)

Параметри

pattern (патерн)

може бути рядком чи об'єктом з методом Symbol.replace – типовим зразком чого є регулярні вирази. Будь-яке значення, котре не має метода Symbol.replace, буде зведено до рядка.

Якщо pattern є регулярним виразом, то він мусить мати позначку глобальності (g), інакше – буде викинуто TypeError.

replacement (заміна)

Може бути рядком чи функцією. Заміна має таку само семантику, як для String.prototype.replace().

Повернене значення

Новий рядок, в якому всі збіги з патерном замінені вказаним значенням.

Винятки

TypeError

Викидається, якщо pattern є регулярним виразом, котрий не має позначки глобальності (g), тобто його властивість flags не містить "g".

Опис

Цей метод не видозмінює рядкове значення, на котрому його викликали. Він повертає новий рядок.

На відміну від replace(), цей метод замінює всі входження рядка, а не тільки перше. Це особливо зручно, коли рядок не є статично відомим, оскільки виклик конструктора RegExp() без екранування спеціальних символів може мимоволі змінити його семантику.

function unsafeRedactName(text, name) {
  return text.replace(new RegExp(name, "g"), "[ВИДАЛЕНО]");
}
function safeRedactName(text, name) {
  return text.replaceAll(name, "[ВИДАЛЕНО]");
}
const report =
  "Хакер на ім'я ха.*ер використав спеціальні символи в своєму імені для зламу сервера.";
console.log(unsafeRedactName(report, "ха.*ер")); // "Хакер на ім'я [ВИДАЛЕНО]а."
console.log(safeRedactName(report, "ха.*ер")); // "Хакер на ім'я [ВИДАЛЕНО] використав спеціальні символи в своєму імені для зламу сервера."

Якщо pattern є об'єктом з методом Symbol.replace (в т.ч. об'єктом RegExp), то такий метод викликається з цільовим рядком та replacement як аргументами. Повернене значення стає поверненим значенням replaceAll(). У такому випадку логіка replaceAll() повністю закодована у методі @@replace, а отже – матиме такий само результат, як replace() (окрім додаткової валідації введення – перевірки того, що регулярний вираз є глобальним).

Якщо pattern є порожнім рядком, то заміна буде вставлена між кожними двома кодовими одиницями UTF-16, подібно до поведінки split().

"xxx".replaceAll("", "_"); // "_x_x_x_"

Для отримання подробиць про те, як властивості регулярних виразів (особливо позначку липкості) взаємодіють із replaceAll() – дивіться RegExp.prototype[@@replace]().

Приклади

Застосування методу replaceAll()

"aabbcc".replaceAll("b", ".");
// 'aa..cc'

Регулярний вираз без глобального пошуку викидає виняток

Якщо шукане значення вказано як регулярний вираз, то такий вираз повинен бути глобальним. Наступний підхід не спрацює:

"aabbcc".replaceAll(/b/, ".");
// TypeError: replaceAll must be called with a global RegExp

Проте такий варіант працюватиме:

'aabbcc'.replaceAll(/b/g, '.');
"aa..cc"

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

Сумісність з браузерами

Дивіться також

• Поліфіл методу String.prototype.replaceAll доступний у core-js
• String.prototype.replace()
• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()