---
title: String.prototype.replace()
slug: Web/JavaScript/Reference/Global_Objects/String/replace
tags:
  - Expressions
  - JavaScript
  - Method
  - Prototype
  - Reference
  - Regular
  - String
translation_of: Web/JavaScript/Reference/Global_Objects/String/replace
---
<p>{{JSRef}}<br>
 Die <code><strong>replace()</strong></code>-Methode gibt eine neue Zeichenkette zurück, in der einige oder alle Übereinstimmungen mit einem <code>Muster</code> durch einen <code>Ersatz</code> ausgetauscht wurden. Das <code>Muster</code> kann eine Zeichenkette oder eine RegExp sein, als <code>Ersatz </code>dienen eine Zeichenkette oder eine Funktion, welche für jede Übereinstimmung aufgerufen wird.</p>

<h2 id="Syntax" name="Syntax">Syntax</h2>

<pre class="syntaxbox"><code><em>str</em>.replace(<em>regexp|substr</em>, <em>newSubStr|function</em></code><code>);</code></pre>

<h3 id="Parameters" name="Parameters">Parameter</h3>

<dl>
 <dt><code>regexp</code></dt>
 <dd>Ein {{jsxref("Global_Objects/RegExp", "RegExp")}}-Objekt. Die Übereinstimmung wird durch den Rückgabewert aus Parameter #2 ersetzt.</dd>
</dl>

<dl>
 <dt><code>substr</code></dt>
 <dd>Eine {{jsxref("Global_Objects/String", "Zeichenkette")}}, welche durch <code>newSubStr</code> ersetzt werden soll. Nur das erste Vorkommen wird ersetzt.</dd>
</dl>

<dl>
 <dt><code>newSubStr</code></dt>
 <dd>Die {{jsxref("Global_Objects/String", "Zeichenkette")}}, welche den Substring aus Parameter #1 ersetzt. Eine Anzahl spezieller Ersetzungsmuster wird unterstützt, siehe den "<a href="#Eine_Zeichenkette_als_Parameter_angeben">Eine Zeichenkette als Parameter angeben</a>"-Abschnitt weiter unten.</dd>
</dl>

<dl>
 <dt><code>function</code></dt>
 <dd>Eine Funktion, welche aufgerufen wird, um den neuen Substring zu erzeugen, der an Stelle des gefundenen Substrings aus Parameter #1 stehen soll. Die Argumente für diese Funktion werden im "<a href="#Eine_Funktion_als_Parameter_angeben">Eine Funktion als Parameter angeben</a>"-Abschnitt unten erläutert.</dd>
</dl>

<h3 id="Rückgabe">Rückgabe</h3>

<p>Eine neue Zeichenkette, in der einige oder alle Übereinstimmungen mit einem Muster durch einen Ersatz ausgetauscht wurden.</p>

<h2 id="Description" name="Description">Beschreibung</h2>

<p>Diese Methode ändert nicht das <code>String</code>-Objekt, auf welchem sie aufgerufen wird. Sie gibt lediglich einen neuen String zurück.</p>

<p>Um ein globales Suchen und Ersetzen durchzuführen, setzen Sie den <code>g</code>-Umschalter im Regulären Ausdruck.</p>

<h3 id="Eine_Zeichenkette_als_Parameter_angeben" name="Eine_Zeichenkette_als_Parameter_angeben">Eine Zeichenkette als Parameter angeben</h3>

<p>Die Ersatzzeichenkette kann folgende spezielle Ersetzungsmuster beinhalten:</p>

<table class="fullwidth-table">
 <tbody>
  <tr>
   <td class="header">Pattern</td>
   <td class="header">Inserts</td>
  </tr>
  <tr>
   <td><code>$$</code></td>
   <td>Fügt ein "$" ein.</td>
  </tr>
  <tr>
   <td><code>$&amp;</code></td>
   <td>Fügt den gefundenen Substring ein.</td>
  </tr>
  <tr>
   <td><code>$`</code></td>
   <td>Fügt den Stringteil vor dem gefundenen Substring ein.</td>
  </tr>
  <tr>
   <td><code>$'</code></td>
   <td>Fügt den Stringteil nach dem gefundenen Substring ein.</td>
  </tr>
  <tr>
   <td style="white-space: nowrap;"><code>$<em>n</em></code></td>
   <td>Mit <code><em>n</em></code> als nicht negative ganze Zahl kleiner als 100 wird der <em>n</em>te eingeklammerte Submatch-String eingefügt, der im ersten Argument in der <code>RegExp</code> angegeben wurde.</td>
  </tr>
 </tbody>
</table>

<h3 id="Eine_Funktion_als_Parameter_angeben" name="Eine_Funktion_als_Parameter_angeben">Eine Funktion als Parameter angeben</h3>

<p>Sie können eine Funktion als zweiten Parameter angeben. In diesem Fall wird diese Funktion aufgerufen, nachdem die Suche ausgeführt wurde. Der Rückgabewert der Funktion wird als Ersatz eingesetzt. (Anmerkung: Die oben genannten speziellen Ersetzungsmuster werden in diesem Fall <em>nicht</em> beachtet.) Bedenken Sie, dass die Funktion für jede Übereinstimmung erneut aufgerufen wird, wenn der reguläre Ausdruck im ersten Parameter den global-Flag gesetzt hat.</p>

<p>Die Argumente dieser Funktion lauten wie folgt:</p>

<table class="fullwidth-table">
 <tbody>
  <tr>
   <td class="header">Möglicher Name</td>
   <td class="header">Gelieferter Wert</td>
  </tr>
  <tr>
   <td><code>match</code></td>
   <td>Der gefundene Substring. (Entspricht $&amp; oben.)</td>
  </tr>
  <tr>
   <td><code>p1, p2, ...</code></td>
   <td>Der <em>n</em>th eingeklammerte Submatch-String, fall im ersten Argument ein <code>RegExp-Objekt</code> angegeben wurde. (Entspricht $1, $2, etc. oben.) Wurde zum Beispiel <code>/(\a+)(\b+)/ angegeben, so ist</code> <code>p1</code> die Übereinstimmung für<code> \a+</code>, und <code>p2</code> für <code>\b+</code>.</td>
  </tr>
  <tr>
   <td><code>offset</code></td>
   <td>Die Position, an welcher der gefundene Substring innerhalb der gesamten Zeichenkette gefunden wurde. War zum Beispiel die gesamte Zeichenkette <code>"abcd"</code> und der gefundene Substring <code>"bc"</code>, dann wäre das Argument <code>1</code>.)</td>
  </tr>
  <tr>
   <td style="white-space: nowrap;"><code>string</code></td>
   <td>Die gesamte Zeichenkette, welche durchsucht wird.</td>
  </tr>
 </tbody>
</table>

<p>(Die genaue Anzahl der Argumente hängt davon ab, ob das erste Argument eine <code>RegExp</code> war und wieviele eingeklammerte Submatches in diesem Fall angegeben wurden.)</p>

<p>Das folgende Beispiel wird <code>newString </code>auf <code>"<span class="console-formatted-string source-code">abc - 12345 - #$*%</span>"</code> setzen:</p>

<pre class="brush: js">function replacer(match, p1, p2, p3, offset, string){
  // p1 is nondigits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(' - ');
}
newString = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, replacer);
</pre>

<h2 id="Examples" name="Examples">Beispiele</h2>

<h3 id="Example_Defining_the_regular_expression_in_replace" name="Example:_Defining_the_regular_expression_in_replace">Beispiel: Definieren des regulären Ausdrucks in <code>replace</code></h3>

<p>Globales Ersetzen kann nur mit einem regulären Ausdruck durchgeführt werden. Im folgenden Beispiel wird der reguläre Ausdruck in <code>replace</code> definiert und beinhaltet den Schalter <code>ignore case</code>.</p>

<pre class="brush: js">var str = "Twas the night before Xmas...";
var newstr = str.replace(/xmas/i, "Christmas");
print(newstr);
</pre>

<p>Dies erzeugt die Ausgabe "Twas the night before Christmas..."</p>

<h3 id="Example_Using_global_and_ignore_with_replace" name="Example:_Using_global_and_ignore_with_replace">Beispiel: Nutzung von <code>global</code> und <code>ignore</code> mit <code>replace</code></h3>

<p>Das nachfolgende Beispiel enthält einen regulären Ausdruck, der sowohl das <code>global</code> als auch das <code>ignore</code> Flag gesetzt hat. Dadurch wird von <code>replace</code> jedes Vorkommnis von 'apples' in der Zeichenkette durch 'oranges' ersetzt.</p>

<pre class="brush: js">var re = /apples/gi;
var str = "Apples are round, and apples are juicy.";
var newstr = str.replace(re, "oranges");
print(newstr);
</pre>

<p>Dies erzeugt die Ausgabe "oranges are round, and oranges are juicy."</p>

<h3 id="Beispiel_Vertausche_Wörter_in_Strings">Beispiel: Vertausche Wörter in Strings</h3>

<p>Im folgenden Skript werden die Wörter in dem String getauscht. Für die Vertauschung im Text nutzt das Skript die Ersetzungspatterns <code>$1</code> und <code>$2</code>.</p>

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

<p>Die Ausgabe ist: "Smith, John".</p>

<h3 id="Example_Using_an_inline_function_that_modifies_the_matched_characters" name="Example:_Using_an_inline_function_that_modifies_the_matched_characters">Beispiel: Nutzung von Inline-Funktionen, die die erkannten Zeichen modifizieren</h3>

<p>In diesem Beispiel werden alle Großbuchstaben durch einen Bindestrich und den entsprechenden Kleinbuchstaben ersetzt. Der wichtige Punkt in dem Beispiel ist, dass der Additions-Operator (Konkatination) vor dem Zurückgeben der neuen Zeichenkette erfolgen muss.</p>

<p>Die Ersetzungsfunktion bekommt das erkannte Muster als Parameter übergeben und benutzt diesen, um den Buchstaben zu transformieren und ihn mit dem Bindestrich zu verbinden. Zum Schluss wird das Ergebnis zum Ersetzen zurückgegeben.</p>

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

<p>Gegeben <code>styleHyphenFormat('borderTop')</code>, gibt 'border-top' zurück.</p>

<p>Weil das Ergebnis transformiert werden soll, bevor die finale Ersetzung durchgeführt wird, muss eine Funktion eingesetzt werden. Dieses erzwingt die Ausführung von <code>toLowerCase()</code>. Wenn man das gleiche versucht ohne eine Funktion zu benutzen, wird die toLowerCase() Methode ohne Wirkung sein.</p>

<pre class="brush: js">var newString = propertyName.replace(/[A-Z]/g, '-' + '$&amp;'.toLowerCase());  // won't work
</pre>

<p>Dieses ist weil <code>'$&amp;'.toLowerCase()</code> ausgeführt wird, bevor der String als Pattern genutzt wird.</p>

<h3 id="Example_Replacing_a_Fahrenheit_degree_with_its_Celsius_equivalent" name="Example:_Replacing_a_Fahrenheit_degree_with_its_Celsius_equivalent">Beispiel: Grad Fahrenheit in Celsius-Grad umwandeln</h3>

<p>Das folgende Beispiel ersetzt einen Wert in Grad Fahrenheit durch den entsprechenden Celsius-Wert. Der Fahrenheitwert sollte eine Nummer sein, die mit einem F endet. Die Funktion gibt eine Celsius-Temperatur mit der Endung C aus. Ist zum Beispiel der Eingabewert 212F, so gibt die Funktion 100C zurück. Ist die Nummer 0F, so wird -17,77777777777778C zurück gegeben.</p>

<p>Der reguläre Ausdruck <code>test</code> prüft jede Nummer, die mit F endet. Die Nummer in Grad Fahrenheit ist durch den zweiten Funktionsparameter, <code>p1</code>, ansprechbar. Die Funktion setzt den Celsiuswert basierend auf dem Fahrenheitwert in einer Zeichenkette in der <code>f2c</code>-Funktion. <code>f2c gibt dann den Celsiuswert zurück. Diese Funktion </code>ähnelt dem s///e-Flag in Perl.</p>

<pre class="brush: js">function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1-32) * 5/9) + "C";
  }
  var s = String(x);
  var test = /(\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}
</pre>

<h3 id="Example_Use_an_inline_function_with_a_regular_expression_to_avoid_for_loops" name="Example: Use an inline function with a regular expression to avoid for loops" style="line-height: 24px;">Beispiel: Verwenden einer inline-Funktion mit einem regulärem Ausdruck um Schleifen zu vermeiden</h3>

<p>Das folgende Beispiel nimmt eine Zeichenkettenmuster und konvertiert es in ein Array von Objekten.</p>

<p><strong>Eingabe:</strong><br>
 Eine Zeichenkette, die aus den Zeichen x, - und _ besteht</p>

<pre>x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___</pre>

<div><strong><span style="line-height: 1.5;">Ausgabe:</span></strong></div>

<div><span style="line-height: 1.5;">Ein Array mit Objekten. Ein 'x' zeigt einen 'an'-Status an, ein '-' (Bindestrich) symbolisiert einen 'aus'-Status und ein '_' (Unterstrich) gibt die Länge des 'an'-Status an.</span></div>

<pre class="brush: json"><span style="line-height: 1.5;">[</span>
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]</pre>

<div><strong>Ausschnitt:</strong></div>

<div>
<pre class="brush: js">var str = 'x-x_';
var retArr = [];
str.replace(/(x_*)|(-)/g, function(match, p1, p2){
  if(p1) retArr.push({ on: true, length: p1.length });
  if(p2) retArr.push({ on: false, length: 1 });
});

console.log(retArr);</pre>
</div>

<div>Der Ausschnitt generiert ein Array mit drei Objekten im gewünschten Format, ohne eine Schleife zu verwenden.</div>

<div></div>

<h2 id="Spezifikationen">Spezifikationen</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Spezifikation</th>
   <th scope="col">Status</th>
   <th scope="col">Kommentar</th>
  </tr>
  <tr>
   <td>{{SpecName('ES3')}}</td>
   <td>{{Spec2('ES3')}}</td>
   <td>Initiale Definition.<br>
    Implementiert in JavaScript 1.2</td>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.5.4.11', 'String.prototype.replace')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-string.prototype.replace', 'String.prototype.replace')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-string.prototype.replace', 'String.prototype.replace')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td></td>
  </tr>
 </tbody>
</table>

<h2 id="Browserkompatibilität">Browserkompatibilität</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Eigenschaft</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Grundlegende Unterstützung</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Grundlegende Unterstützung</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="Firefox-spezifische_Bemerkungen">Firefox-spezifische Bemerkungen</h2>

<ul>
 <li>Mit dem Start von Gecko 27 {{geckoRelease(27)}}, wurde diese Methode an die ECMAScript Spezifikation angepasst. Wenn <code>replace()</code> mit einem globalen regulären Ausdruck aufgerufen wird, wird die {{jsxref("RegExp.lastIndex")}} Eigenschaft (wenn sie Spezifiziert wurde) auf 0 zurückgesetzt ({{bug(501739)}}).</li>
 <li>Mit dem Start von Gecko 39 {{geckoRelease(39)}} wurden das nicht standardisierte <code>flags</code> Argument als deprecated markiert und wirft eine Warnung in der Konsole ({{bug(1142351)}}).</li>
 <li>Mit dem Start von Gecko 47 {{geckoRelease(47)}} wurden das nicht standardisierte <code>flags</code> Argument  nicht länger in <span class="short_text" id="result_box" lang="de"><span>Nicht-</span><span>Release-Builds</span></span> unterstützt und wird bald vollständig entfernt ({{bug(1245801)}}).</li>
 <li>Mit dem Start von Gecko 49 {{geckoRelease(49)}} wurden das nicht standardisierte <code>flags</code> Argument nicht mehr unterstützt ({{bug(1108382)}}).</li>
</ul>

<h2 id="See_also" name="See_also">Siehe auch</h2>

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