CKTIS / JavaScript
Element.matches — testar um seletor CSS
Element.matches verifica se um determinado elemento corresponde a um seletor CSS. Devolve um valor booleano, não um elemento; uma sintaxe de seletor inválida provoca uma exceção.
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
element.matches(selectors)element.matches(selectors) testa o próprio element. O argumento selectors é uma cadeia de seletor CSS ou uma lista de seletores separados por vírgulas. O resultado é true se o elemento corresponder, ou false caso contrário.
O método não pesquisa os descendentes como querySelector() nem encontra um antepassado correspondente como closest(). O elemento não tem de estar ligado a um documento; ainda assim, os seletores que dependem das relações na árvore têm em conta o seu contexto real.
Um seletor inválido lança uma DOMException com o nome SyntaxError, em vez de devolver false.
Esta é uma API DOM definida pelo DOM Standard, não uma funcionalidade de ECMAScript. A presença de Node 24, por si só, não comprova que esta API de browser seja suportada.
Exemplos
const element = document.createElement('button');
element.className = 'action';
console.log(element.matches('button.action'));
console.log(element.matches('.missing'));
console.log(element.matches('.missing, .action'));
try {
element.matches('[');
} catch (error) {
console.log(error.name);
}Resultado
true false true SyntaxError
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.