path: root/files/pt-br/web/javascript/reference/global_objects/string/replace/index.html

---
title: String.prototype.replace()
slug: Web/JavaScript/Reference/Global_Objects/String/replace
tags:
  - Expressões Regulares
  - JavaScript
  - Prototipo
  - Referencia
  - String
  - replace()
translation_of: Web/JavaScript/Reference/Global_Objects/String/replace
---
<div>{{JSRef("Global_Objects", "String")}}</div>

<h2 id="Resumo">Resumo</h2>

<p>O método <code>replace()</code> retorna uma nova string com algumas ou todas as correspondências de um padrão substituídas por um determinado caractere (ou caracteres). O padrão pode ser uma string ou uma {{jsxref("RegExp")}}, e a substituição pode ser uma string ou uma função a ser chamada para cada correspondência. Se o padrão for uma string, apenas a primeira ocorrência será substituída.</p>

<p>A string original não é modificada.</p>

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

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

<h3 id="Parameters" name="Parameters">Parâmetros</h3>

<dl>
 <dt><code>regexp </code></dt>
 <dd><span class="tlid-translation translation"><span title="">Um objeto {{jsxref ("RegExp")}} ou literal. A correspondência ou correspondências são substituídas por <em><code>newSubStr</code></em> ou o valor retornado pela <code>function</code> especificada.</span></span></dd>
 <dt><code>substr</code></dt>
 <dd><span class="tlid-translation translation"><span title="">Uma {{jsxref ("String")}} que será substituída por <code>newSubStr</code>.</span> <span title="">Ele é tratado como uma string textual e não é interpretado como uma expressão regular.</span> <span title="">Apenas a primeira ocorrência será substituída.</span></span></dd>
 <dt><code>newSubStr</code></dt>
 <dd>A {{jsxref("Global_Objects/String", "String")}} que substitui a <code>substr</code> recebida do parâmetro #1. Uma série de padrões de substituições especiais são suportados. Veja a seção "<a href="#" id="Specifying_a_string_as_a_parameter">Especificando uma string como parâmetro</a>" abaixo.</dd>
 <dt><code>function</code></dt>
 <dd>A função (function) chamada cria uma nova substring (para ser colocada no lugar da substring recebida pelo parametro #1). Os argumentos fornececidos para essa função estão descritos na seção "<a href="#" id="Specifying_a_string_as_a_parameter">Especificando uma função como parâmetro</a>" mais abaixo.</dd>
 <dt><code>flags</code> {{non-standard_inline}}</dt>
 <dd>
 <p>Uma string especificando uma combinação de <a href="https://wiki.developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Regular_Expressions">flags de expressão regular</a>. O uso do parâmetro <code>flags</code> no método <code>String.prototype.replace()</code> é não-padrão. Ao invés de usar este parâmetro, use um objeto {{jsxref("Global_Objects/RegExp", "RegExp")}} com as flags correspondentes. O valor deste parâmetro deve ser uma string consistindo em um ou mais dos seguintes caracteres para afetar a operação, tais como descrito:</p>

 <dl>
  <dt><code>g</code></dt>
  <dd>Combinação global.</dd>
  <dt><code>i</code></dt>
  <dd>Ignora diferenças entre maiúsculas e minúsculas.</dd>
  <dt><code>m</code></dt>
  <dd>Combinação em várias linhas.</dd>
  <dt><code>y</code> {{experimental_inline}}</dt>
  <dd>Sticky</dd>
 </dl>

 <div class="blockIndicator note">
 <p><strong>Nota: </strong>O argumento <code>flags</code> não funciona no v8 Core (Chrome e NodeJs).</p>
 </div>
 </dd>
</dl>

<h3 id="Returns" name="Returns">Valor retornado</h3>

<p>Uma nova string com alguma ou todas as combinações do padrão substituído(s) pelo valor de substituição.</p>

<h2 id="Description" name="Description">Descrição</h2>

<p>Este método não muda o objeto {{jsxref("Global_Objects/String", "String")}}. Ele simplesmente retorna uma nova string.</p>

<p>Para realizar uma pesquisa global e substituir, inclua a flag <code>g</code> na expressão regular ou se o primeiro parâmetro for uma string, inclua <code>g</code> no parâmetro flags.</p>

<h3 id="Specifying_a_string_as_a_parameter" name="Specifying_a_string_as_a_parameter">Especificando uma string como parâmetro</h3>

<p>A string substituidora pode incluir o seguinte padrão de substituição especial:</p>

<table class="fullwidth-table" style="height: 140px; width: 575px;">
 <tbody>
  <tr>
   <td class="header"><strong>Padrão       </strong></td>
   <td class="header"><strong>Insere</strong></td>
  </tr>
  <tr>
   <td><code>$$</code></td>
   <td>Insere um "$".</td>
  </tr>
  <tr>
   <td><code>$&amp;</code></td>
   <td>Insere a string casada.</td>
  </tr>
  <tr>
   <td><code>$`</code></td>
   <td>Insere a porção da string que precede a substring combinada.</td>
  </tr>
  <tr>
   <td><code>$'</code></td>
   <td>Insere a porção da string que segue a substring combinada.</td>
  </tr>
  <tr>
   <td><code>$<em>n</em></code> ou <code>$<em>nn</em></code></td>
   <td>Onde <code><em>n</em></code> ou <code><em>nn</em></code> são dígitos decimais, insere a <em>n</em>-ésima substring entre parêntesis casada, dado o primeiro argumento foi um objeto {{jsxref("Global_Objects/RegExp", "RegExp")}}.</td>
  </tr>
 </tbody>
</table>

<h3 id="Specifying_a_function_as_a_parameter" name="Specifying_a_function_as_a_parameter">Especificando uma função como parâmetro</h3>

<p>Você pode especificar uma função no segundo parâmetro. Neste caso, a função será chamada depois que a correspôndecia for encontrada. O resultado da função (valor retornado) será usado como a string substituta. (Atenção: os padrões de substituição citados acima não se aplicam neste caso). Note que a função será chamada múltiplas vezes para combinação que deve ser substituída se a expressão regular no primeiro parâmetro tiver a regra global.</p>

<p>Os parâmetros da função são:</p>

<table class="fullwidth-table" style="height: 375px; width: 490px;">
 <tbody>
  <tr>
   <td class="header"><strong>Possíveis nomes            </strong></td>
   <td class="header"><strong>Valor fornecido</strong></td>
  </tr>
  <tr>
   <td><code>match</code></td>
   <td>A substring encontrada. Corresponde ao <code>$&amp;</code> acima.</td>
  </tr>
  <tr>
   <td><code>p1, p2, ...</code></td>
   <td>O enésimo parâmetro entre parênteses da RegEx no primeiro parâmetro na função <code>replace()</code> {{jsxref("Global_Objects/RegExp", "RegExp")}}. (Corresponde a <code>$1</code>, <code>$2</code>, etc. acima.) Por exemplo, se <code>/(\a+)(\b+)/</code>, for o primeiro parâmetro, <code>p1</code> é a combinação para <code>\a+</code>, e <code>p2</code> para <code>\b+</code>.</td>
  </tr>
  <tr>
   <td><code>offset</code></td>
   <td>O offset da string encontrada em relação ao resto da string. Por exemplo, se a string for 'abcd' e a string a ser encontrada for 'bc', então este parâmetro terá o valor 1.</td>
  </tr>
  <tr>
   <td>
    <p><code>string</code></p>
   </td>
   <td>
    <p>A string completa que está sendo examinada.</p>
   </td>
  </tr>
 </tbody>
</table>

<p>(O número exato de argumentos dependerá se o primeiro parâmetro for uma {{jsxref("Global_Objects/RegExp", "RegExp")}} e de quantas combinações entre parênteses houver).</p>

<p>O exemplo a seguir irá substituir o valor de <code>newString</code> para <code>'abc - 12345 - #$*%'</code>:</p>

<pre class="brush: js notranslate">function replacer(match, p1, p2, p3, offset, string) {
  // p1 não possui digitos,
  // p2 possui dígitos, e p3 não possui alfanuméricos
  return [p1, p2, p3].join(' - ');
}
var newString = 'abc12345#$*%'.replace(/([^\d]*)(\d*)([^\w]*)/, replacer);

// retorna <span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body"><span class="objectBox objectBox-string">"abc - 12345 - #$*%"</span></span></span></span>
</pre>

<h2 id="Exemplos">Exemplos</h2>

<h3 id="Definindo_uma_expressão_regular_com_replace">Definindo uma expressão regular com <code>replace()</code></h3>

<p>No exemplo a seguir foi definida uma expressão regular com a flag "<code>i</code>" (que ignora diferenças entre maiúsculas e minúsculas) no método <code>replace()</code>.</p>

<pre class="notranslate"><code>var str = 'Twas the night before Xmas...';
var newstr = str.replace(/xmas/i, 'Christmas');

console.log(newstr);
// retorna "Twas the night before Christmas..."</code></pre>

<div class="blockIndicator note">
<p><strong>Nota:</strong> Veja <a href="https://wiki.developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Regular_Expressions">este guia</a> para maiores explicações as sobre expressões regulares.</p>
</div>

<h3 id="Usando_global_e_ignore_com_replace">Usando <code>global</code> e <code>ignore</code> com <code>replace()</code></h3>

<p>Substituir globalmente, "<code>g</code>", só pode ser feito com uma expressão regular. No exemplo a seguir, a expressão regular inclui as flags global e ignore que permitem a função <code>replace()</code> substituir cada "<code>maçãs</code>" por "<code>laranjas</code>" na string.</p>

<pre class="notranslate"><code>var re = /maçãs/gi;
var str = '</code>As maçãs são redondas. As maçãs são suculentas<code>.';
var newstr = str.replace(re, 'laranjas');

console.log(newstr);
// retorna
// "</code>As laranjas são redondas. As laranjas são suculentas<code>."</code></pre>

<h3 id="Trocando_palavras_em_uma_string">Trocando palavras em uma string</h3>

<p>O script a seguir troca as palavras na string. Para o texto que vai substituir, o script usa <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges">grupos de captura</a> e os padrões de substituição <code>$1</code> e <code>$2</code>.</p>

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

<h3 id="Usando_uma_função_que_modifica_os_caracteres_coincidentes">Usando uma função que modifica os caracteres coincidentes</h3>

<div class="tw-ta-container hide-focus-ring tw-nfl" id="tw-target-text-container">
<p><span lang="pt">Neste exemplo, todas as ocorrências de letras maiúsculas na string são convertidas em minúsculas e um hífen é inserido antes do local de correspondência. </span>O importante aqui é que é necessário uma operação adicional no item antes dele ser retornado como substituído.</p>
</div>

<p>A função de substituição aceita a string coincidida como parâmetro e usa ela para transformar os caracteres e concatenar um hífen antes de retornar.</p>

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

<p>Dado o seguinte parâmetro: <code>styleHyphenFormat('borderTop')</code>, o valor retornado é '<code>border-top</code>'.</p>

<p>Como queremos transformar o resultado da coincidencia antes da substituição final, nós devemos usar uma função. Isto força que a transformação seja feita antes da chamada do método {{jsxref("String.prototype.toLowerCase()", "toLowerCase()")}}. Se tivéssemos tentado isto sem a função, o método {{jsxref("String.prototype.toLowerCase()", "toLowerCase()")}} não teria efeito.</p>

<pre class="brush: js example-bad notranslate">let newString = propertyName.replace(/[A-Z]/g, '-' + '$&amp;'.toLowerCase());  // não funciona</pre>

<p>Isso acontece porque <code>'$&amp;'.toLowerCase()</code> será executada antes (resultando no mesmo que <code>'$&amp;'</code>) em vez de usar os caracteres da string a ser transformada.</p>

<h3 id="Substituindo_graus_Fahrenheit_em_Celsius">Substituindo graus Fahrenheit em Celsius</h3>

<p>O exemplo a seguir converte graus Fahrenheit em Celsius. O grau Fahrenheit deve ser um número terminado com "<code>F</code>". A função retorna o número em Celsius terminando em "<code>C</code>". Por exemplo, se o valor de entrada for "<code>212F</code>", a função deve retornar "<code>100C</code>". Se o número for "<code>0F</code>", a função deve retornar "<code>-17.77777777777778C</code>".</p>

<p>A expressão regular <code>test</code> verifica por números que terminem com "<code>F</code>". O número de graus Fahrenheit é acessível pela função pelo segundo parâmetro, <code>p1</code>. A função calcula o Celsius baseado no Fahrenheit passado via string para a função <code>f2c()</code>. A <code>f2c()</code> então retorna o número em Celsius.</p>

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

<h3 id="Use_uma_função_com_expressão_regular_para_evitar_loops_for">Use uma função com expressão regular para evitar loops for</h3>

<p>O exemplo a seguir pega um padrão de string e converte em um array de objetos.</p>

<p><strong>Entrada:</strong></p>

<p>Uma string com caracteres: <code>x</code>, <code>-</code> e <code>_</code></p>

<pre class="notranslate"><code>x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___</code></pre>

<p><strong>Saída:</strong></p>

<p>Um array de objetos. Um <code>'x'</code> denota um estado <code>'on'</code>, um <code>'-'</code> (hífen) denota um estado <code>'off'</code>  e um <code>'_'</code> (underline) denota o comprimento do estado <code>'on'</code>.</p>

<pre class="notranslate"><code>[
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]</code></pre>

<p><strong>Código:</strong></p>

<pre class="notranslate"><code>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);</code></pre>

<p>O código gera um array de 3 objetos como desejado sem usar uma função de loop.</p>

<h2 id="Especificações">Especificações</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Especificação</th>
   <th scope="col">Status</th>
   <th scope="col">Comentário</th>
  </tr>
  <tr>
   <td>ECMAScript 3rd Edition.</td>
   <td>Standard</td>
   <td>Defnição inicial. Implementado no 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>
 </tbody>
</table>

<h2 id="Navegadores_compatíveis">Navegadores compatíveis</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</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>Basic support</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<h3 id="Notas_específicas_do_Firefox">Notas específicas do Firefox</h3>

<ul>
 <li>Começando no Gecko 27 {{geckoRelease(27)}}, esse método foi ajustado conforme as especificações do ECMAScript. Quando <code>replace()</code> é chamado com uma expressão regular global, a propriedade {{jsxref("RegExp.lastIndex")}} (se especificada) será resetada para <code>0</code> ({{bug(501739)}}).</li>
</ul>

<h2 id="See_also" name="See_also">Veja também</h2>

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