IDBObjectStore:createIndex() 方法

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

createIndex()IDBObjectStore 接口的方法,用于创建并返回连接数据库中的一个新的 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①

浏览器兼容性

BCD 表仅在浏览器中加载

另请参阅