path: root/files/uk/web/javascript/reference/global_objects/string/replace/index.html

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

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

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

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



<h2 id="Синтаксис">Синтаксис</h2>

<pre class="syntaxbox notranslate">const newStr = <var>str</var>.replace(<var>regexp</var>|<var>substr</var>, <var>newSubstr</var>|<var>function</var>)</pre>

<h3 id="Параметри">Параметри</h3>

<dl>
 <dt><code><var>regexp</var></code> (шаблон)</dt>
 <dd>Об'єкт або літерал {{jsxref("RegExp")}}. Збіг чи збіги замінюються рядком <code><var>newSubstr</var></code> або значенням, яке вертає вказана функція <em><code>function</code></em>.</dd>
 <dt><code><var>substr</var></code></dt>
 <dd>{{jsxref("String","Рядок")}}, який потрібно замінити на <code><var>newSubstr</var></code>. Він сприймається як рядковий літерал та <em>не</em> інтерпретується як регулярний вираз. Замінюється лише перше співпадіння.</dd>
 <dt><code><var>newSubstr</var></code> (заміна)</dt>
 <dd>{{jsxref("String","Рядок")}}, який замінює підрядок, вказаний параметром <code><var>regexp</var></code> або <code><var>substr</var></code>. Підтримується можливість задавати декілька спеціальних шаблонів заміни; дивіться розділ "<a href="#Використання_рядка_в_якості_параметра">Використання рядка в якості параметра</a>" нижче.</dd>
 <dt><code><var>function</var></code> (заміна)</dt>
 <dd>Функція, що викликатиметься для створення нового підрядка, який буде використовуватись для заміни збігів з наданим параметром <code><var>regexp</var></code> або <code><var>substr</var></code>. Аргументи, що передаються в цю функцію, описані у розділі "<a href="#Використання_функції_в_якості_параметра">Використання функції в якості параметра</a>" нижче.</dd>
</dl>

<h3 id="Значення_що_повертається">Значення, що повертається</h3>

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

<h2 id="Опис">Опис</h2>

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

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

<h3 id="Використання_рядка_в_якості_параметра">Використання рядка в якості параметра</h3>

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

<table class="standard-table">
 <thead>
  <tr>
   <th class="header" scope="col">Шаблон</th>
   <th class="header" scope="col">Вставляє</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>$$</code></td>
   <td>Вставляє <code>"$"</code>.</td>
  </tr>
  <tr>
   <td><code>$&amp;</code></td>
   <td>Вставляє знайдений підрядок.</td>
  </tr>
  <tr>
   <td><code>$`</code></td>
   <td>Вставляє частину рядка, що передує знайденому підрядку.</td>
  </tr>
  <tr>
   <td><code>$'</code></td>
   <td>Вставляє частину рядка, що розташована за знайденим підрядком.</td>
  </tr>
  <tr>
   <td><code>$<var>n</var></code></td>
   <td>Де <code><var>n</var></code> є додатним цілим числом, меншим за 100, вставляє <code><var>n</var></code>-й підрядок збігів у дужках, за умови, що першим аргументом був об'єкт {{jsxref("RegExp")}}. Зауважте, що вони індексуються з <code>1</code>.</td>
  </tr>
 </tbody>
</table>

<h3 id="Використання_функції_в_якості_параметра">Використання функції в якості параметра</h3>

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

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

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

<table class="standard-table">
 <thead>
  <tr>
   <th class="header" scope="col">Можливе ім'я</th>
   <th class="header" scope="col">Надане значення</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>match</code></td>
   <td>Знайдений підрядок. (Відповідає вищенаведеному <code>$&amp;</code>)</td>
  </tr>
  <tr>
   <td><code>p1, p2, ...</code></td>
   <td><var>n</var>-й рядок, знайдений захопленою групою у дужках, за умови, що першим аргументом методу <code>replace()</code> був об'єкт {{jsxref("RegExp")}}. (Відповідає вищенаведеним <code>$1</code>, <code>$2</code>, і т.д.) Наприклад, якщо був наданий аргумент <code>/(\a+)(\b+)/</code>, то <code>p1</code> є збігом з <code>\a+</code>, а <code>p2</code> - збігом з <code>\b+</code>.</td>
  </tr>
  <tr>
   <td><code>offset</code></td>
   <td>Зсув знайденого підрядка всередині рядка, що перевіряється. (Наприклад, якби цілим рядком був <code>'абвг'</code>, а знайденим підрядком <code>'бв'</code>, то цей аргумент дорівнював би <code>1</code>.)</td>
  </tr>
  <tr>
   <td><code>string</code></td>
   <td>Весь рядок, що перевіряється.</td>
  </tr>
 </tbody>
</table>

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

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

<pre class="brush: js notranslate">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 - #$*%
</pre>

<h2 id="Приклади">Приклади</h2>

<h3 id="Визначення_регулярного_виразу_у_replace">Визначення регулярного виразу у replace()</h3>

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

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

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

<div class="blockIndicator note">
<p><strong>Заувага:</strong> Більше пояснень щодо регулярних виразів дивіться у <a href="/uk/docs/Web/JavaScript/Guide/Regular_Expressions">цьому посібнику</a>.</p>
</div>

<h3 id="Використання_глобального_пошуку_та_ігнорування_регістру_з_replace">Використання глобального пошуку та ігнорування регістру з replace()</h3>

<p>Глобальну заміну можна зробити лише з використанням регулярного виразу. У наступному прикладі регулярний вираз містить <a href="/uk/docs/Web/JavaScript/Guide/Regular_Expressions#Advanced_searching_with_flags_2">прапори глобального пошуку та ігнорування регістру</a>, які дозволяють методу <code>replace()</code> замінити кожний знайдений підрядок <code>'яблука'</code> на <code>'апельсини'</code>.</p>

<pre class="brush: js notranslate">let re = /яблука/gi;
let str = 'Яблука круглі, і яблука сочні.';
let newstr = str.replace(re, 'апельсини');
console.log(newstr);  // апельсини круглі, і апельсини сочні.
</pre>

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

<h3 id="Код_що_міняє_слова_місцями">Код, що міняє слова місцями</h3>

<p>Наступний скрипт міняє місцями слова у рядку. В якості тексту заміни скрипт використовує <a href="/uk/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges">захоплені групи</a> та шаблони заміни <code>$1</code> та <code>$2</code>.</p>

<pre class="brush: js notranslate">let re = /(\w+)\s(\w+)/;
let str = 'John Smith';
let newstr = str.replace(re, '$2, $1');
console.log(newstr);  // Smith, John
</pre>

<p>Цей код виводить <code>'Smith, John'</code>.</p>

<h3 id="Використання_внутрішньої_функції_яка_модифікує_знайдені_символи">Використання внутрішньої функції, яка модифікує знайдені символи</h3>

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

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

<pre class="brush: js notranslate">function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match, offset, string) {
    return (offset &gt; 0 ? '-' : '') + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}
</pre>

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

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

<pre class="brush: js example-bad notranslate">let newString = propertyName.replace(/[A-Z]/g, '-' + '$&amp;'.toLowerCase());  // не спрацює
</pre>

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

<h3 id="Заміна_градусів_Фаренгейта_на_еквівалент_у_градусах_Цельсія">Заміна градусів Фаренгейта на еквівалент у градусах Цельсія</h3>

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

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

<pre class="brush: js notranslate">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);
}
</pre>

<h2 id="Специфікації">Специфікації</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Специфікація</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-string.prototype.replace', 'String.prototype.replace')}}</td>
  </tr>
 </tbody>
</table>

<h2 id="Сумісність_з_веб-переглядачами">Сумісність з веб-переглядачами</h2>

<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>

<p>{{Compat("javascript.builtins.String.replace")}}</p>

<h2 id="Див._також">Див. також</h2>

<ul>
 <li>{{jsxref("String.prototype.replaceAll", "String.prototype.replaceAll()")}}</li>
 <li>{{jsxref("String.prototype.match", "String.prototype.match()")}}</li>
 <li>{{jsxref("RegExp.prototype.exec", "RegExp.prototype.exec()")}}</li>
 <li>{{jsxref("RegExp.prototype.test", "RegExp.prototype.test()")}}</li>
</ul>