IDBObjectStore: add() 方法
注意:此功能在 Web Workers 中可用。
add() 方法是 IDBObjectStore 介面的一部分,它返回一個 IDBRequest 物件,並在單獨的執行緒中建立值的 結構化克隆,然後將克隆後的值儲存在物件儲存區中。此方法用於向物件儲存區新增新記錄。
為了確定 add 操作是否已成功完成,除了監聽 IDBObjectStore.add 請求的 success 事件之外,還需要監聽事務的 complete 事件,因為事務可能在 success 事件觸發後仍然失敗。換句話說,success 事件僅在事務成功排隊時觸發。
add 方法是一個僅插入方法。如果物件儲存區中已存在一個鍵(key)與 key 引數相同的記錄,則會在返回的請求物件上觸發一個 ConstraintError 錯誤事件。要更新現有記錄,您應該改用 IDBObjectStore.put 方法。
語法
add(value)
add(value, key)
引數
返回值
一個 IDBRequest 物件,後續與此操作相關的事件會在此物件上觸發。
如果操作成功,請求的 result 屬性的值是新記錄的鍵。
異常
此方法可能會丟擲以下型別之一的DOMException:
ReadOnlyErrorDOMException-
如果與此操作關聯的事務處於只讀 模式下,則丟擲此異常。
TransactionInactiveErrorDOMException-
如果此
IDBObjectStore的事務不活躍,則會丟擲此異常。 DataErrorDOMException-
如果出現以下任一情況,則丟擲此異常
- 物件儲存區使用內聯鍵(in-line keys)或具有鍵生成器(key generator),並且提供了 key 引數。
- 物件儲存區使用外部鍵(out-of-line keys)且沒有鍵生成器,並且未提供 key 引數。
- 物件儲存區使用內聯鍵但沒有鍵生成器,並且物件儲存區的鍵路徑(key path)沒有產生有效的鍵。
- 提供了 key 引數,但它不包含一個有效的鍵。
InvalidStateErrorDOMException-
如果
IDBObjectStore已被刪除或移除,則會丟擲此異常。 DataCloneErrorDOMException-
如果正在儲存的資料無法透過內部結構化克隆演算法進行克隆,則會丟擲此異常。
ConstraintErrorDOMException-
如果由於已存在具有相同主鍵值的記錄而導致插入操作失敗(違反主鍵約束),則丟擲此異常。
示例
在以下程式碼片段中,我們開啟資料庫的讀/寫事務,並使用 add() 向物件儲存區新增一些資料。同時,注意附加到事務事件處理程式上的函式,用於在事務成功或失敗時報告事務開啟的結果。如需完整的可執行示例,請參閱我們的 待辦事項通知 應用(即時檢視示例)。
// 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① |
瀏覽器相容性
載入中…
另見
- 使用 IndexedDB
- 開始事務:
IDBDatabase - 使用事務:
IDBTransaction - 設定鍵的範圍:
IDBKeyRange - 檢索和修改資料:
IDBObjectStore - 使用遊標:
IDBCursor - 參考示例:待辦事項通知(檢視即時示例)。