CKTIS / JavaScript
DOMStringList e verificação de pertença com contains()
DOMStringList é uma lista de cadeias de caracteres exposta por algumas APIs Web, que não se modifica diretamente. O método contains() verifica se uma cadeia indicada pertence à lista e devolve um valor booleano. Uma utilização comum é verificar os nomes dos object stores no IndexedDB.
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
list.contains(string)DOMStringList é uma interface antiga de API Web que representa uma lista de cadeias de caracteres. Obtém-se a partir de outra API, em vez de a criar com new DOMStringList(). Um exemplo é IDBDatabase.objectStoreNames, a lista dos nomes dos object stores de uma base de dados IndexedDB. O facto de a interface ser antiga não significa que as APIs que a devolvem estejam obsoletas.
DOMStringList.contains, chamado como list.contains(string), devolve true quando a cadeia indicada está na lista, ou false quando está ausente. O argumento é obrigatório: chamar list.contains() sem argumento lança um TypeError.
Não é um array JavaScript comum. A propriedade length é só de leitura e a interface não disponibiliza métodos de alteração como push() ou splice(). As alterações são feitas através da API proprietária dos dados, não através da própria lista.
Quando utiliza o IndexedDB, o exemplo cria uma base de dados separada com um object store chamado notes, verifica se dois nomes constam da lista e apresenta ambos os resultados na consola: true para notes e false para missing. DOMStringList é uma API do ambiente do navegador, não uma funcionalidade de uma edição específica do ECMAScript. A MDN assinala a interface e contains() como amplamente disponíveis desde julho de 2015; a presença do Node 24 num repositório não comprova a disponibilidade destas APIs.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DOMStringList membership</title>
</head>
<body>
<script>
(() => {
function checkMembership(list, present) {
console.log(list.contains(present));
console.log(list.contains('missing'));
}
function useAncestorOrigins() {
// Chromium also exposes a DOMStringList through Location.ancestorOrigins.
// A local child document has at least one ancestor without using storage.
const frame = document.createElement('iframe');
frame.hidden = true;
frame.title = 'DOMStringList test fixture';
frame.srcdoc = '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Local fixture</title></head><body></body></html>';
frame.addEventListener('load', () => {
const list = frame.contentWindow.location.ancestorOrigins;
if (list?.length) {
checkMembership(list, list.item(0));
} else {
console.warn('Skipping membership checks: IndexedDB could not be opened and Location.ancestorOrigins is unavailable or empty.');
}
frame.remove();
}, { once: true });
document.body.append(frame);
}
const name = `cktis-list-${Date.now()}-${Math.random()}`;
let open;
try {
open = indexedDB.open(name, 1);
} catch {
useAncestorOrigins();
return;
}
open.onerror = useAncestorOrigins;
open.onupgradeneeded = () => open.result.createObjectStore('notes');
open.onsuccess = () => {
const db = open.result;
checkMembership(db.objectStoreNames, 'notes');
db.close();
indexedDB.deleteDatabase(name);
};
})();
</script>
</body>
</html>Resultado
true false
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.