IDBObjectStore: createIndex() 方法

Baseline 已廣泛支援

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

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

IDBObjectStore 介面的 createIndex() 方法會在連線的資料庫中建立並返回一個新的 IDBIndex 物件。它會建立一個新的欄位/列,為每個資料庫記錄定義一個新的資料點以包含。

請注意,IndexedDB 索引可以包含任何 JavaScript 資料型別;IndexedDB 使用 結構化克隆演算法 來序列化儲存的物件,這允許儲存簡單和複雜的物件。

請注意,此方法只能從 VersionChange 事務模式回撥中呼叫。

語法

js
createIndex(indexName, keyPath)
createIndex(indexName, keyPath, options)

引數

indexName

要建立的索引的名稱。請注意,可以建立一個空名稱的索引。

keyPath

索引要使用的鍵路徑。請注意,可以建立具有空 keyPath 的索引,也可以將序列(陣列)作為 keyPath 傳遞。

options 可選

一個可以包含以下屬性的物件

unique

如果為 true,則對於單個鍵,索引不允許重複值。預設為 false

multiEntry

如果為 true,則當 keyPath 解析為陣列時,索引將為陣列中的每個元素新增一個條目。如果為 false,則會新增一個包含該陣列的單個條目。預設為 false

locale 非標準 已棄用

允許您為索引指定一個區域設定。然後,透過鍵範圍對資料執行的任何排序操作都將遵循該區域設定的排序規則。您可以透過以下三種方式之一指定其值

  • string:一個包含特定區域設定程式碼的字串,例如 en-USpl
  • auto:將使用平臺的預設區域設定(可能由使用者代理設定更改)。
  • nullundefined:如果未指定區域設定,則將使用正常的 JavaScript 排序 — 不區分割槽域設定。

返回值

一個 IDBIndex 物件:新建立的索引。

異常

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

ConstraintError DOMException

如果資料庫中已存在同名的索引,則會丟擲此錯誤。索引名稱區分大小寫。

InvalidAccessError DOMException

如果提供的鍵路徑是序列,並且在 objectParameters 物件中將 multiEntry 設定為 true,則會丟擲此錯誤。

InvalidStateError DOMException

在以下情況下丟擲

  • 該方法不是從 versionchange 事務模式回撥(即在 onupgradeneeded 處理程式中)呼叫的。
  • 物件儲存已被刪除。
SyntaxError DOMException

如果提供的 keyPath 不是 有效鍵路徑,則會丟擲此錯誤。

TransactionInactiveError DOMException

如果此 IDBObjectStore 所屬的事務不處於活動狀態(例如,已被刪除或移除),則會丟擲此錯誤。在 Firefox 41 之前的版本中,在這種情況下也會引發 InvalidStateError,這具有誤導性;現在已修復(請參閱 Firefox bug 1176165)。

示例

在以下示例中,您可以看到 onupgradeneeded 處理程式用於在載入版本號更高的資料庫時更新資料庫結構。createIndex() 用於在物件儲存上建立新索引。有關完整的示例,請參閱我們的 待辦事項通知 應用(線上檢視示例)。

js
let db;

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

// Two event handlers for opening the database.
DBOpenRequest.onerror = (event) => {
  note.appendChild(document.createElement("li")).textContent =
    "Error loading database.";
};

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 = request.result;

  // Run the displayData() function to populate the task list with
  // all the to-do list data already in the IDB
  displayData();
};

// This handler fires when a new database is created and indicates
// either that one has not been created before, or a new version
// was submitted with window.indexedDB.open(). (See above.)
// It is only implemented in recent browsers.
DBOpenRequest.onupgradeneeded = (event) => {
  const db = event.target.result;

  db.onerror = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Error loading database.";
  };

  // Create an objectStore for this database
  const objectStore = db.createObjectStore("toDoList", {
    keyPath: "taskTitle",
  });

  // define what data items the objectStore will contain

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });
  objectStore.createIndex("notified", "notified", { unique: false });
};

規範

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

瀏覽器相容性

另見