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

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

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

<p>O método <code>match()</code> retorna uma correspondência entre uma string com uma <a href="https://wiki.developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Regular_Expressions">expressão regular</a>.</p>

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

<pre class="syntaxbox notranslate"><code><em>str</em>.match(regexp);</code></pre>

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

<dl>
 <dt><code>regexp</code></dt>
 <dd>Um objeto de <a href="https://wiki.developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Regular_Expressions">expressão regular</a>. Se <em><code>regexp</code></em> não for uma <strong><code>RegExp</code></strong>, o mesmo será convertido para uma nova RegExp usando <code>new <strong>RegExp</strong>(<em>regexp</em>)</code>.<br>
 <br>
 Se você não fornecer nenhum parâmetro ao usar o método <code>match()</code>, você obterá um {{jsxref ("Array")}} com uma string vazia: <code>[""]</code>.</dd>
</dl>

<h3 id="Valor_retornado">Valor retornado</h3>

<ul>
 <li>Se o sinalizador <code>g</code> for usado, todos os resultados correspondentes à expressão regular serão retornados, mas a captura de grupos não.</li>
 <li>se o sinalizador <code>g</code> não for usado, apenas a primeira correspondência completa e seus grupos de captura relacionados serão retornados. Nesse caso, o item devolvido terá propriedades adicionais conforme descrito a seguir.</li>
</ul>

<dl>
 <dt><code>array</code></dt>
 <dd>Um {{jsxref ("Array")}} cujo conteúdo depende da presença ou ausência do sinalizador global (<code>g</code>), ou {{jsxref ("null")}} se nenhuma correspondência for encontrada.</dd>
</dl>

<h4 id="Propriedades_adicionais">Propriedades adicionais</h4>

<p>Conforme explicado acima, alguns resultados contêm propriedades adicionais conforme descrito abaixo.</p>

<dl>
 <dt><code>groups</code></dt>
 <dd>Um objeto de grupos de captura nomeados cujas chaves são os nomes, e valores são os grupos de captura ou {{jsxref ("undefined")}} se nenhum grupo de captura nomeado foi definido. Consulte <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges">Grupos e Intervalos</a> para obter mais informações.</dd>
 <dt><code>index</code></dt>
 <dd>O índice da pesquisa em que o resultado foi encontrado.</dd>
 <dt><code>input</code></dt>
 <dd>Uma cópia da string pesquisada.</dd>
</dl>

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

<p>Se a expressão regular não incluir o sinalizador <code>g</code>, <code>str.match()</code> retornará o mesmo resultado que {{jsxref ("RegExp.prototype.exec()", "RegExp.exec()")}}.</p>

<h3 id="Notes" name="Notes">Veja também: métodos RegExp</h3>

<ul>
 <li>Se você precisar saber se uma string corresponde a uma expressão regular, use {{jsxref("RegExp.test()", "RegExp.test()")}}.</li>
 <li>Se você quiser encontrar apenas uma correspondência, você pode querer usar {{jsxref("RegExp.prototype.exec()", "RegExp.exec()")}}.</li>
 <li>Se você deseja obter grupos de captura e o sinalizador global (<code>g</code>) está definido, você precisa usar {{jsxref("RegExp.prototype.exec()", "RegExp.exec()")}} ou {{jsxref("String. prototype.matchAll() ")}} em vez disso.</li>
</ul>

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

<h3 id="Example_Using_match" name="Example:_Using_match">Usando <code>match()</code></h3>

<p>No exemplo a seguir, <code>match()</code> é usado para encontrar "Capítulo", seguido de um ou mais caracteres numéricos, seguido por um ponto decimal e caracteres numéricos 0 ou mais vezes. A expressão inclui a flag <code>i</code> para que diferenças de maiúscula/minúscula sejam ignoradas.</p>

<pre class="brush:js notranslate">var str = "Para maiores informações, veja o Capítulo 3.4.5.1";
var re = /(capítulo \d+(\.\d)*)/i;
var found = str.match(re);

console.log(found);

// retorna ["Capítulo 3.4.5.1",
            "Capítulo 3.4.5.1",
            ".1",
            index: 33,
            input: "Para maiores informações, veja o Capítulo 3.4.5.1"]

// "Capítulo 3.4.5.1" é a primeira correspondência e o primeiro valor
//  capturado a partir de (capítulo \d+(\.\d)*).
// ".1" é o útlimo valor de (\.\d).
// A propriedade "index" (33) é o índice de base zero da correspôndencia inteira.
// A propriedade "input" é a string original que foi analisada.
</pre>

<h3 id="Example_Using_global_and_ignore_case_flags_with_match" name="Example:_Using_global_and_ignore_case_flags_with_match">Usando as bandeiras (flags) global e ignore com<br>
 <code>match()</code></h3>

<p>O exemplo a seguir demonstra o uso das bandeiras (flags) global e ignore com <code>match()</code>. Todas as letras de <code>A</code> a <code>E</code> e <code>a</code> a <code>e</code> são retornadas, com cada letra sendo um elemento no array.</p>

<pre class="brush:js notranslate">var str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var regexp = /[A-E]/gi;
var matches_array = str.match(regexp);

console.log(matches_array);
// <code>['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']</code>
</pre>

<div class="blockIndicator note">
<p><strong>Nota:</strong> Veja também {{jsxref("String.prototype.matchAll()")}} e <a href="https://wiki.developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Regular_Expressions#Pesquisa_avan%C3%A7ada_com_Flags">Pesquisa avançada com sinalizadores</a>.</p>
</div>

<h3 id="Usando_grupos_de_captura_nomeados">Usando grupos de captura nomeados</h3>

<p>Em navegadores que suportam grupos de captura nomeados, o código a seguir captura "<code>fox</code>" ou "<code>cat</code>" em um grupo denominado "<code>animal</code>":</p>

<pre class="brush: js notranslate">const paragraph = 'The quick brown fox jumps over the lazy dog. It barked.';

const capturingRegex = /(?&lt;animal&gt;fox|cat) jumps over/;
const found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}</pre>

<h3 id="Usando_match_sem_parâmetros">Usando <code>match()</code> sem parâmetros</h3>

<pre class="brush: js notranslate">var str = "nada se perde, tudo se transforma";

str.match();  // retorna [""]
</pre>

<h3 id="Um_objeto_não-RegExp_como_parâmetro">Um objeto não-RegExp como parâmetro</h3>

<p>Quando o parâmetro <em><code>regexp</code></em> é uma string ou um número, ele é convertido implicitamente em um {{jsxref("RegExp")}} usando o <code>new <strong>RegExp</strong>(<em>regexp</em>)</code>.<br>
 <br>
 Se for um número positivo com um sinal positivo, <code>RegExp()</code> irá ignorar o sinal positivo.</p>

<pre class="brush: js notranslate"><code>var str1 = "NaN significa 'não é um número'. Infinity contem -Infinity e +Infinity em JavaScript.",
    str2 = "Meu avô tem 65 anos e minha avô tem 63.",
    str3 = "O contrato foi declarado null (nulo) e void (sem efeito)";
str1.match("número");   // "número" é um string. retorna ["número"]
str1.match(NaN);        // o tipo de NaN é um número. retorna ["NaN"]
str1.match(Infinity);   // o tipo de Infinity é um número. retorna ["Infinity"]
str1.match(+Infinity);  // retorna ["Infinity"]
str1.match(-Infinity);  // retorna ["-Infinity"]
str2.match(65);         // retorna ["65"]
str2.match(+65);        // Um número com sinal positivo. retorna ["65"]
str3.match(null);       // retorna ["null"]</code></pre>

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

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Especificações</th>
   <th scope="col">Estado</th>
   <th scope="col">Comentário</th>
  </tr>
  <tr>
   <td>ECMAScript 3rd Edition.</td>
   <td>Standard</td>
   <td>Definição inicial.<br>
    Implementado no JavaScript 1.2</td>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.5.4.10', 'String.prototype.match')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-string.prototype.match', 'String.prototype.match')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td></td>
  </tr>
 </tbody>
</table>

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

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

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>característica</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Suporte Básico</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>Característica</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>Suporte Básico</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="See_also" name="See_also">Veja também</h2>

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