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

Метод replace() повертає новий рядок, в якому деякі або усі збіги з шаблоном замінені параметром заміни. Шаблон може бути рядком або {{jsxref("RegExp","регулярним виразом")}}, а заміна може бути рядком або функцією, що викликатиметься для кожного збігу. Якщо шаблон є рядком, буде замінений лише перший збіг.

Початковий рядок лишається незміненим.

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

Синтаксис

const newStr = str.replace(regexp|substr, newSubstr|function)

Параметри

regexp (шаблон)
Об'єкт або літерал {{jsxref("RegExp")}}. Збіг чи збіги замінюються рядком newSubstr або значенням, яке вертає вказана функція function.
substr
{{jsxref("String","Рядок")}}, який потрібно замінити на newSubstr. Він сприймається як рядковий літерал та не інтерпретується як регулярний вираз. Замінюється лише перше співпадіння.
newSubstr (заміна)
{{jsxref("String","Рядок")}}, який замінює підрядок, вказаний параметром regexp або substr. Підтримується можливість задавати декілька спеціальних шаблонів заміни; дивіться розділ "Використання рядка в якості параметра" нижче.
function (заміна)
Функція, що викликатиметься для створення нового підрядка, який буде використовуватись для заміни збігів з наданим параметром regexp або substr. Аргументи, що передаються в цю функцію, описані у розділі "Використання функції в якості параметра" нижче.

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

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

Опис

Цей метод не змінює об'єкт {{jsxref("String")}}, що його викликав. Він просто повертає новий рядок.

Щоб виконати глобальний пошук та заміну, використовуйте перемикач g у регулярному виразі.

Використання рядка в якості параметра

Рядок заміни може містити наступні спеціальні шаблони заміни:

Шаблон Вставляє
$$ Вставляє "$".
$& Вставляє знайдений підрядок.
$` Вставляє частину рядка, що передує знайденому підрядку.
$' Вставляє частину рядка, що розташована за знайденим підрядком.
$n Де n є додатним цілим числом, меншим за 100, вставляє n-й підрядок збігів у дужках, за умови, що першим аргументом був об'єкт {{jsxref("RegExp")}}. Зауважте, що вони індексуються з 1.

Використання функції в якості параметра

Ви можете вказати функцію в якості другого параметра. У цьому випадку функція буде викликана після знайдення збігу. Результат функції (повернене значення) буде використаний в якості рядка заміни. (Заувага: Вищезазначені спеціальні шаблони заміни не застосовуються у цьому випадку.)

Зауважте, що функція буде викликатись багаторазово, для кожного повного збігу, що буде замінений, якщо регулярний вираз у першому параметрі є глобальним.

Функція має наступні аргументи:

Можливе ім'я Надане значення
match Знайдений підрядок. (Відповідає вищенаведеному $&)
p1, p2, ... n-й рядок, знайдений захопленою групою у дужках, за умови, що першим аргументом методу replace() був об'єкт {{jsxref("RegExp")}}. (Відповідає вищенаведеним $1, $2, і т.д.) Наприклад, якщо був наданий аргумент /(\a+)(\b+)/, то p1 є збігом з \a+, а p2 - збігом з \b+.
offset Зсув знайденого підрядка всередині рядка, що перевіряється. (Наприклад, якби цілим рядком був 'абвг', а знайденим підрядком 'бв', то цей аргумент дорівнював би 1.)
string Весь рядок, що перевіряється.

(Точна кількість аргументів залежить від того, чи є перший аргумент об'єктом {{jsxref("RegExp")}} — і, якщо є, то скільки збігів, заключених у дужки, він визначає.)

Наступний приклад присвоїть newString значення 'абв - 12345 - #$*%':

function replacer(match, p1, p2, p3, offset, string) {
  // p1 - не цифри, p2 - цифри, а p3 - не літерно-цифрові символи
  return [p1, p2, p3].join(' - ');
}
let newString = 'абв12345#$*%'.replace(/([^\d]*)(\d*)([^\w]*)/, replacer);
console.log(newString);  // абв - 12345 - #$*%

Приклади

Визначення регулярного виразу у replace()

У наступному прикладі регулярний вираз визначається у методі replace() та містить прапор ігнорування регістру.

let str = 'Наближається Різдво у чарівній Миші...';
let newstr = str.replace(/миші/i, 'тиші');
console.log(newstr);  // Наближається Різдво у чарівній тиші...

Цей код виводить 'Наближається Різдво у чарівній тиші...'.

Заувага: Більше пояснень щодо регулярних виразів дивіться у цьому посібнику.

Використання глобального пошуку та ігнорування регістру з replace()

Глобальну заміну можна зробити лише з використанням регулярного виразу. У наступному прикладі регулярний вираз містить прапори глобального пошуку та ігнорування регістру, які дозволяють методу replace() замінити кожний знайдений підрядок 'яблука' на 'апельсини'.

let re = /яблука/gi;
let str = 'Яблука круглі, і яблука сочні.';
let newstr = str.replace(re, 'апельсини');
console.log(newstr);  // апельсини круглі, і апельсини сочні.

Цей код виводить 'апельсини круглі, і апельсини сочні.'.

Код, що міняє слова місцями

Наступний скрипт міняє місцями слова у рядку. В якості тексту заміни скрипт використовує захоплені групи та шаблони заміни $1 та $2.

let re = /(\w+)\s(\w+)/;
let str = 'John Smith';
let newstr = str.replace(re, '$2, $1');
console.log(newstr);  // Smith, John

Цей код виводить 'Smith, John'.

Використання внутрішньої функції, яка модифікує знайдені символи

У цьому прикладі усі великі літери перетворюються на малі, а перед розташуванням збігу вставляється дефіс. Важливим тут є те, що необхідно виконати додаткові операції над збігом перед тим, як він буде повернений в якості заміни.

Функція заміни приймає фрагмент збігу в якості параметра і використовує його для перетворення регістру та приєднання дефісу перед поверненням.

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match, offset, string) {
    return (offset > 0 ? '-' : '') + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}

Наступний код styleHyphenFormat('borderTop') поверне 'border-top'.

Оскільки ми хочемо далі трансформувати результат збігу перед останочною заміною, нам потрібно використовувати функцію. Це запускає обчислення збігу пред викликом методу {{jsxref("String.prototype.toLowerCase()", "toLowerCase()")}}. Якби ми спробували зробити це, використовуючи збіг без функії, метод {{jsxref("String.prototype.toLowerCase()", "toLowerCase()")}} не мав би жодного ефекту.

let newString = propertyName.replace(/[A-Z]/g, '-' + '$&'.toLowerCase());  // не спрацює

Все тому, що '$&'.toLowerCase() спочатку був би обчислений як рядковий літерал (і в результаті повернув би той самий рядок '$&') перед використанням його символів в якості шаблону.

Заміна градусів Фаренгейта на еквівалент у градусах Цельсія

Наступний приклад замінює значення градусів за Фаренгейтом на його еквівалент у градусах Цельсія. Значення градусів Фаренгейта має бути числом, що закінчується літерою "F". Функція повертає число за Цельсієм, що закінчується літерою "C". Наприклад, якщо вхідне число дорівнює "212F", функція повертає "100C". Якщо число дорівнює "0F", функція вертає "-17.77777777777778C".

Регулярний вираз test перевіряє будь-яке число, що закінчується літерою F. Значення градусів Фаренгейта доступне функції через її другий параметр p1. Функція присвоює значення за Цельсієм, базуючись на градусах Фаренгейта, переданих у рядку до функції f2c(). Далі f2c() повертає значення за Цельсієм. Ця функція схожа на прапор мови Perl s///e.

function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1 - 32) * 5/9) + 'C';
  }
  let s = String(x);
  let test = /(-?\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}

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

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

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

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

Див. також