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

CKTIS / JavaScript

IndexedDB: adicionar, ler, eliminar e substituir registos

Usa `add()`, `getAll()`, `delete()` e `put()` para manipular registos pela chave primária e distingue o sucesso de um pedido da confirmação da transação.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

store.add(value)
store.add(value, key)
store.getAll()
store.getAll(query)
store.getAll(query, count)
store.getAll(options)
store.delete(keyOrRange)
store.put(value)
store.put(value, key)

Os métodos add(), getAll(), delete() e put() pertencem à interface IDBObjectStore do IndexedDB, não ao ECMAScript. O repositório de objetos obtém-se a partir de uma transação. O acesso aos dados segue a política da mesma origem (esquema, anfitrião e porta); o suporte depende do ambiente de execução.

add(value) apenas insere: se a chave primária já existir, o pedido falha com ConstraintError. put(value) insere ou substitui por inteiro o valor associado à chave; não combina campos. Se a chave estiver no próprio valor, omite o segundo argumento: keyPath indica onde a encontrar. Se for externa ao valor, passa key como segundo argumento, a menos que um gerador de chaves ativado a deva fornecer. Ambos os métodos guardam uma cópia estruturada do valor e, em caso de sucesso, colocam a chave em request.result. Um valor que não pode ser clonado, como uma função, provoca um DataCloneError síncrono.

getAll() coloca em request.result um array de valores clonados, sem chaves anexadas em separado; se não houver correspondências, o resultado é []. A ordem predefinida é crescente pela chave primária, não pela ordem de inserção. getAll(query, count) permite selecionar uma chave ou um IDBKeyRange e limitar os resultados com um count positivo. A forma getAll({ query, count, direction }) também permite definir o sentido, por exemplo "prev" para a ordem decrescente; verifica se os navegadores de destino a suportam.

delete(keyOrRange) elimina um registo pela chave primária ou todos os registos num IDBKeyRange. Se o pedido tiver sucesso, o resultado é undefined, mesmo que não haja correspondências. O método não é o operador delete do JavaScript; usa clear() para esvaziar o repositório.

Os quatro métodos devolvem imediatamente um IDBRequest, não uma Promise. Para ler basta readonly; as escritas normais exigem readwrite. Enfileira os pedidos enquanto a transação está ativa, por exemplo quando a crias ou num gestor de eventos de um pedido, não depois de aguardar uma resposta de rede. Por predefinição, um erro num pedido aborta a transação e desfaz as suas alterações. success diz respeito a um único pedido; complete indica que a transação foi confirmada.

Exemplos

void (async () => {
  const { indexedDB, crypto } = globalThis;
  if (!indexedDB || typeof crypto?.randomUUID !== 'function') {
    throw new Error('Run this example on an HTTPS page in a browser with IndexedDB and crypto.randomUUID() available.');
  }

  const name = `cktis-idb-${crypto.randomUUID()}`;
  const open = indexedDB.open(name, 1);
  open.onupgradeneeded = () => {
    open.result.createObjectStore('tasks', { keyPath: 'id' });
  };
  const db = await new Promise((resolve, reject) => {
    open.onsuccess = () => resolve(open.result);
    open.onerror = () => reject(open.error);
  });

  try {
    const tx = db.transaction('tasks', 'readwrite');
    const store = tx.objectStore('tasks');
    store.add({ id: 2, title: 'Draft', tag: 'temporary' });
    store.add({ id: 1, title: 'Remove me' });
    const before = store.getAll();
    store.put({ id: 2, title: 'Published' });
    store.delete(1);
    const after = store.getAll();

    await new Promise((resolve, reject) => {
      tx.oncomplete = () => resolve();
      tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
    });
    console.log(JSON.stringify(before.result));
    console.log(JSON.stringify(after.result));
  } finally {
    db.close();
    const cleanup = indexedDB.deleteDatabase(name);
    await new Promise((resolve, reject) => {
      cleanup.onsuccess = () => resolve();
      cleanup.onerror = () => reject(cleanup.error);
    });
  }
})().catch((error) => console.error(error));

Resultado

[{"id":1,"title":"Remove me"},{"id":2,"title":"Draft","tag":"temporary"}]
[{"id":2,"title":"Published"}]

Executa o código na consola de desenvolvimento de uma página HTTPS onde IndexedDB e `crypto.randomUUID()` estejam disponíveis e o armazenamento seja permitido. Após a confirmação da transação, a primeira linha mostra os dois registos pela ordem das chaves. A segunda mostra que `put()` não manteve `tag` e que `delete()` eliminou o registo com a chave `1`. O código fecha a ligação e pede a eliminação da base de dados temporária.

Lições relacionadas

  • JavaScript · Lição 20 · Intermédio · Versão: 3

Fontes