IDBObjectStore: add() 方法

Baseline 已廣泛支援

此特性已相當成熟,可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來,各瀏覽器均已提供此特性。

注意:此功能在 Web Workers 中可用。

add() 方法是 IDBObjectStore 介面的一部分,它返回一個 IDBRequest 物件,並在單獨的執行緒中建立值的 結構化克隆,然後將克隆後的值儲存在物件儲存區中。此方法用於向物件儲存區新增新記錄。

為了確定 add 操作是否已成功完成,除了監聽 IDBObjectStore.add 請求的 success 事件之外,還需要監聽事務的 complete 事件,因為事務可能在 success 事件觸發後仍然失敗。換句話說,success 事件僅在事務成功排隊時觸發。

add 方法是一個僅插入方法。如果物件儲存區中已存在一個鍵(key)與 key 引數相同的記錄,則會在返回的請求物件上觸發一個 ConstraintError 錯誤事件。要更新現有記錄,您應該改用 IDBObjectStore.put 方法。

語法

js
add(value)
add(value, key)

引數

value

要儲存的值。

key 可選

用於標識記錄的鍵。如果未指定,則為 null。

返回值

一個 IDBRequest 物件,後續與此操作相關的事件會在此物件上觸發。

如果操作成功,請求的 result 屬性的值是新記錄的鍵。

異常

此方法可能會丟擲以下型別之一的DOMException

ReadOnlyError DOMException

如果與此操作關聯的事務處於只讀 模式下,則丟擲此異常。

TransactionInactiveError DOMException

如果此 IDBObjectStore 的事務不活躍,則會丟擲此異常。

DataError DOMException

如果出現以下任一情況,則丟擲此異常

  • 物件儲存區使用內聯鍵(in-line keys)或具有鍵生成器(key generator),並且提供了 key 引數。
  • 物件儲存區使用外部鍵(out-of-line keys)且沒有鍵生成器,並且未提供 key 引數。
  • 物件儲存區使用內聯鍵但沒有鍵生成器,並且物件儲存區的鍵路徑(key path)沒有產生有效的鍵。
  • 提供了 key 引數,但它不包含一個有效的鍵。
InvalidStateError DOMException

如果 IDBObjectStore 已被刪除或移除,則會丟擲此異常。

DataCloneError DOMException

如果正在儲存的資料無法透過內部結構化克隆演算法進行克隆,則會丟擲此異常。

ConstraintError DOMException

如果由於已存在具有相同主鍵值的記錄而導致插入操作失敗(違反主鍵約束),則丟擲此異常。

示例

在以下程式碼片段中,我們開啟資料庫的讀/寫事務,並使用 add() 向物件儲存區新增一些資料。同時,注意附加到事務事件處理程式上的函式,用於在事務成功或失敗時報告事務開啟的結果。如需完整的可執行示例,請參閱我們的 待辦事項通知 應用(即時檢視示例)。

js
// Let us open our database
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.appendChild(document.createElement("li")).textContent =
    "Database initialized.";

  // store the result of opening the database in the db variable.
  // This is used a lot below
  db = DBOpenRequest.result;

  // Run the addData() function to add the data to the database
  addData();
};

function addData() {
  // Create a new object ready to insert into the IDB
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // open a read/write db transaction, ready for adding the data
  const transaction = db.transaction(["toDoList"], "readwrite");

  // report on the success of the transaction completing, when everything is done
  transaction.oncomplete = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Transaction completed.";
  };

  transaction.onerror = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Transaction not opened due to error. Duplicate items not allowed.";
  };

  // create an object store on the transaction
  const objectStore = transaction.objectStore("toDoList");

  // Make a request to add our newItem object to the object store
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // report the success of our request
    note.appendChild(document.createElement("li")).textContent =
      "Request successful.";
  };
}

規範

規範
Indexed Database API 3.0
# ref-for-dom-idbobjectstore-add①

瀏覽器相容性

另見