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

CKTIS / JavaScript

IDBObjectStore — um armazenamento de registos IndexedDB

IDBObjectStore expõe registos IndexedDB através de uma referência associada a uma transação. Permite adicionar, substituir, ler, eliminar e contar dados, bem como utilizar índices secundários.

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

const store = transaction.objectStore(name);
store.createIndex(name, keyPath, options); // upgrade transaction only
store.add(value, key); // key may be omitted
store.put(value, key); // key may be omitted
store.getAll(query, count); // query and count are optional
store.delete(query);
store.count(query); // query is optional
store.index(name);

IDBObjectStore é uma referência a um armazenamento de registos IndexedDB, associada a uma transação específica. Cada registo tem uma chave primária e um valor copiado através de clonagem estruturada. keyPath: "id" obtém a chave do campo id; com esta configuração, não passe uma chave separada a add() ou put().

add() insere um registo; uma chave duplicada provoca um erro ConstraintError. put() insere um registo ou substitui o valor completo associado a uma chave existente — não combina campos. delete(query) elimina registos pela chave primária ou por um intervalo de chaves. Estas operações requerem uma transação que permita escritas. getAll(query?, count?) obtém valores, ordenados por chave primária crescente por predefinição; count(query?) conta os registos correspondentes. Se omitir a consulta, é considerado todo o armazenamento.

createIndex(name, keyPath, options) cria um índice apenas durante uma transação de atualização do esquema, normalmente em onupgradeneeded; unique: true exige que as chaves do índice sejam únicas. index(name) devolve um IDBIndex existente para pesquisas pela chave secundária. Ambos os métodos devolvem referências de forma síncrona; os restantes métodos listados devolvem IDBRequest, não Promise.

O sucesso de um pedido não significa que a transação tenha sido confirmada: aguarde por complete e trate abort. Coloque operações na fila enquanto a transação estiver ativa; esperar por tarefas assíncronas não relacionadas pode torná-la inativa. O exemplo utiliza formas da API do IndexedDB 2.0, sem a sobrecarga mais recente de getAll() com um objeto de opções. Esta é uma Web API, não faz parte do ECMAScript; o Node 24 não comprova o suporte nos navegadores. Verifique se indexedDB está disponível no ambiente de destino.

Identificadores de referência abrangidos por esta entrada: IDBObjectStore.createIndex, IDBObjectStore.add, IDBObjectStore.getAll, IDBObjectStore.delete, IDBObjectStore.put, IDBObjectStore.count, IDBObjectStore.index.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IDBObjectStore: working with records</title>
</head>
<body>
  <h1>Working with an IndexedDB object store</h1>
  <script>
    (() => {
      const name = 'cktis-store-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
      const report = error => console.log(error.name === 'SecurityError'
        ? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
      let factory, opening;
      try {
        factory = window.indexedDB;
        if (!factory) {
          console.log('IndexedDB unavailable: API missing');
          return;
        }
        opening = factory.open(name, 1);
      } catch (error) {
        report(error);
        return;
      }
      let created = false;
      opening.onerror = () => report(opening.error);
      opening.onupgradeneeded = () => {
        created = true;
        const store = opening.result.createObjectStore('items', { keyPath: 'id' });
        store.createIndex('byLabel', 'label', { unique: true });
      };
      opening.onsuccess = () => {
        const db = opening.result;
        if (!created) {
          db.close();
          console.log('Fixture name already in use');
          return;
        }
        const tx = db.transaction('items', 'readwrite');
        const store = tx.objectStore('items');
        store.add({ id: 1, label: 'draft' });
        store.add({ id: 2, label: 'spare' });
        store.put({ id: 1, label: 'final' });
        store.delete(2);
        const all = store.getAll();
        const count = store.count();
        const indexed = store.index('byLabel').get('final');
        const cleanup = () => {
          db.close();
          factory.deleteDatabase(name);
        };
        tx.oncomplete = () => {
          console.log(JSON.stringify({ items: all.result, count: count.result, indexedId: indexed.result.id }));
          cleanup();
        };
        tx.onabort = () => {
          report(tx.error);
          cleanup();
        };
      };
    })();
  </script>
</body>
</html>

Resultado

Successful browser run (IndexedDB access permitted):
{"items":[{"id":1,"label":"final"}],"count":1,"indexedId":1}

If the browser blocks IndexedDB access with a SecurityError, as in the isolated environment:
IndexedDB unavailable: SecurityError

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