Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

String.prototype.includes — verificar se existe uma substring

String.prototype.includes verifica se um texto contém uma determinada substring e devolve true ou false. Distingue maiúsculas de minúsculas, permite indicar uma posição inicial e não aceita expressões regulares comuns.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

str.includes(searchString)
str.includes(searchString, position)

String.prototype.includes procura uma substring literal e devolve true ou false sem alterar o texto. Distingue maiúsculas de minúsculas e compara unidades de código UTF-16: não normaliza Unicode nem aplica regras de comparação específicas de cada língua.

O parâmetro opcional position indica o índice inicial mais cedo possível para uma correspondência, contado a partir de zero em unidades de código UTF-16. O valor predefinido é 0; após a conversão para número, a parte fracionária é truncada em direção a zero e o resultado é limitado ao intervalo entre 0 e o comprimento do texto. Se o método chegar à fase de pesquisa, devolve true quando searchString é uma string vazia, mesmo que a posição indicada ultrapasse o comprimento do texto. Contudo, position é convertido antes da pesquisa: passar um BigInt como position lança um TypeError mesmo quando searchString é uma string vazia.

Um objeto RegExp comum usado como searchString provoca um TypeError; formalmente, essa decisão é determinada pelo teste IsRegExp, que tem em conta Symbol.match. Os restantes argumentos de pesquisa são convertidos em texto, pelo que, se o argumento for omitido, é pesquisado "undefined". Chamar o método com null ou undefined como this provoca um TypeError.

Este é um método da biblioteca padrão ECMAScript, não uma Web API. O suporte num determinado navegador deve ser verificado separadamente; a disponibilidade no Node 24 não comprova o suporte nos navegadores.

Exemplos

const text = "JavaScript";
console.log(text.includes("Script"));
console.log(text.includes("script"));
console.log(text.includes("Java", 1));
console.log(text.includes("", 99));

try {
  text.includes(/Script/);
} catch (error) {
  console.log(error.name);
}

Resultado

true
false
false
true
TypeError

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes