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①

浏览器兼容性

另见