最全的 IndexedDB API 操作指南（值得收藏）

这是我参与8月更文挑战的第12天，活动详情查看：8月更文挑战

前言

先说一下背景吧。这两天在封装一些底层的基础库，其中有一个封装就是“通用前端 storage 方法的封装”，需要封装操作 cookie、localStorage、sessionStorage、indexedDB 相关操作。比如新增、查询、删除、清空等操作。之前只是了解过 IndexedDB ，没有真正使用过，也没有去详细了解过它的 API ，所以在封装的时候还有有一些疑惑的，所有花了一个下午，看了 MDN 和很多文章，感觉都写的不是很全，所以自己从众多文章中汇总了一下 IndexedDB 的 API。这篇文章并不是一个技术文章，纯属就是一个 API 的汇总，为了让自己了解多一点 IndexedDB，也方便自己后面写的时候查阅 API，如果你觉得没有意思就可以关闭这篇文章了。当然你也可以点赞收藏方便后续有需要在翻出来看看。

概述

IndexedDB 就是浏览器提供的本地数据库，它可以被网页脚本创建和操作。IndexedDB 允许储存大量数据，提供查找接口，还能建立索引。这些都是 LocalStorage 所不具备的。就数据库类型而言，IndexedDB 不属于关系型数据库（不支持 SQL 查询语句），更接近 NoSQL 数据库。

诞生背景

现有的浏览器存储方法有很多，例如：Cookie、LocalStorage、SessionDtorage，但是都不适合储存大量数据。Cookie 的大小不超过 4KB，且每次请求都会发送回服务器；LocalStorage 在 2.5MB 到 10MB 之间（各家浏览器不同）。而且不提供搜索功能，不能建立自定义的索引。所以，需要一种新的解决方案，这就是 IndexedDB 诞生的背景。

特点

键值对存储：采用对象仓库存储数据，所有类型的数据都可以存储，主键唯一。
异步操作：操作采用异步的方式，防止大量的数据操作影响页面性能。
支持事务：要么全部成功，要么全部失败。
同源限制：不能跨域访问。
存储量大：大小取决于硬件，一般不少于 250M。
支持二进制：支持二进制存储。

indexedDB 对象

1. indexedDB.open(name, version)

打开数据库，是一个异步的操作，但是会同步返回一个 IDBOpenDBRequest 对象。
两个参数
第一个参数：数据库名称，格式为字符串，不可省略
第二个参数：数据库版本，是一个大于 0 的正整数（0 将报错），如果该参数大于当前版本，会触发数据库升级。第二个参数可省略，如果数据库已存在，将打开当前版本的数据库；如果数据库不存在，将创建该版本的数据库，默认版本为 1。
4 种事件
success：数据库打开成功
error：数据库打开失败
upgradeneeded：第一次打开数据库，或者数据库版本更新（第一次打开，先触发 upgradeneeded，在触发 success）
blocked：上一次数据库链接还未关闭

2. indexedDB.deleteDatabase()

删除数据库，是一个异步的操作，但是会同步返回一个 IDBOpenDBRequest 对象。
一个参数：删除的数据库名称
删除结果通过事件通知：
success：删除成功
error：删除失败
当删除时，当前删除的数据库的其他链接会收到 versionchange 事件。

3. indexedDB.cmp()

indexedDB.cmp()方法比较两个值是否为 indexedDB 的相同的主键（不能用来比较任意值）。它返回一个整数，表示比较的结果：
0 表示相同，
1 表示第一个主键大于第二个主键，
-1 表示第一个主键小于第二个主键。

IDBRequest 对象

1. IDBRequest

IDBRequest 表示打开的数据库链接。这个对象的所有操作都是异步操作，要通过 readyState 属性判断是否完成。

IDBRequest.readyState：等于 pending 表示操作正在进行，等于 done 表示操作正在完成。
IDBRequest.result：返回请求的结果。如果请求失败、结果不可用，读取该属性会报错。
IDBRequest.error：请求失败时，返回错误对象。
IDBRequest.source：返回请求的来源（比如索引对象或 ObjectStore）。
IDBRequest.transaction：返回当前请求正在进行的事务，如果不包含事务，返回 null。
IDBRequest.onsuccess：指定 success 事件的监听函数。
IDBRequest.onerror：指定 error 事件的监听函数。

2. IDBOpenDBRequest 对象

IDBOpenDBRequest 对象继承了 IDBRequest 对象，提供了两个额外的事件监听属性。

IDBOpenDBRequest.onblocked：指定 blocked 事件（upgradeneeded 事件触发时，数据库仍然在使用）的监听函数。
IDBOpenDBRequest.onupgradeneeded：upgradeneeded 事件的监听函数

IDBDatabase 对象

打开数据成功以后，可以从 IDBOpenDBRequest 对象的 result 属性上面，拿到一个 IDBDatabase 对象，它表示连接的数据库。后面对数据库的操作，都通过这个对象完成。

var db;
var DBOpenRequest = window.indexedDB.open('test', 1);
DBOpenRequest.onerror = function (event) {
  console.log('Error');
};
DBOpenRequest.onsuccess = function(event) {
  db = DBOpenRequest.result;
  // ...
};

1. IDBDatabase 对象属性

IDBDatabase.name：字符串，数据库名称。
IDBDatabase.version：整数，数据库版本。数据库第一次创建时，该属性为空字符串。
IDBDatabase.objectStoreNames：DOMStringList 对象（字符串的集合），包含当前数据的所有 object store 的名字。
IDBDatabase.onabort：指定 abort 事件（事务中止）的监听函数。
IDBDatabase.onclose：指定 close 事件（数据库意外关闭）的监听函数。
IDBDatabase.onerror：指定 error 事件（访问数据库失败）的监听函数。
IDBDatabase.onversionchange：数据库版本变化时触发（发生 upgradeneeded 事件，或调用 indexedDB.deleteDatabase()）。

2. IDBDatabase 对象方法

IDBDatabase.close()：关闭数据库连接，实际会等所有事务完成后再关闭。
IDBDatabase.createObjectStore()：创建存放数据的对象仓库，类似于传统关系型数据库的表格，返回一个 IDBObjectStore 对象。该方法只能在 versionchange 事件监听函数中调用。
IDBDatabase.deleteObjectStore()：删除指定的对象仓库。该方法只能在 versionchange 事件监听函数中调用。
IDBDatabase.transaction()：返回一个 IDBTransaction 事务对象。

IDBObjectStore 对象

IDBObjectStore 对象对应一个对象仓库（object store）。IDBDatabase.createObjectStore()方法返回的就是一个 IDBObjectStore 对象。 IDBDatabase 对象的 transaction()返回一个事务对象，该对象的 objectStore()方法返回 IDBObjectStore 对象，因此可以采用下面的链式写法。

1. IDBObjectStore 对象属性

IDBObjectStore.indexNames：返回一个类似数组的对象（DOMStringList），包含了当前对象仓库的所有索引。
IDBObjectStore.keyPath：返回当前对象仓库的主键。
IDBObjectStore.name：返回当前对象仓库的名称。
IDBObjectStore.transaction：返回当前对象仓库所属的事务对象。
IDBObjectStore.autoIncrement：布尔值，表示主键是否会自动递增。

2. IDBObjectStore 对象方法

1. IDBObjectStore.add()

IDBObjectStore.add()：添加数据，返回一个 IDBRequest 对象。
两个参数
第一个参数是键值
第二个参数是主键，该参数可选，如果省略默认为 null

objectStore.add(value, key)

2. IDBObjectStore.put()

IDBObjectStore.put()：更新某个主键对应的数据记录，如果键值不存在，插入一条新的记录。返回一个 IDBRequest 对象。
两个参数
第一个参数为新数据
第二个参数为主键，该参数可选，且只在自动递增时才有必要提供，因为那时主键不包含在数据值里面

objectStore.put(item, key)

3. IDBObjectStore.clear()

IDBObjectStore.clear()：删除当前对象仓库的所有记录。返回一个 IDBRequest 对象。

objectStore.clear()

4. IDBObjectStore.delete()

IDBObjectStore.delete()：于删除指定主键的记录。返回一个 IDBRequest 对象。

objectStore.delete(Key)

5. IDBObjectStore.count()

IDBObjectStore.count()：计算记录的数量。返回一个 IDBRequest 对象。
不带参数时，返回当前对象仓库的所有记录数量。
如果主键或 IDBKeyRange 对象作为参数，则返回对应的记录数量。

IDBObjectStore.count(key)

6. IDBObjectStore.getKey()

IDBObjectStore.getKey()：获取主键。返回一个 IDBRequest 对象。
该方法的参数可以是主键值或 IDBKeyRange 对象。

objectStore.getKey(key)

7. IDBObjectStore.get()

IDBObjectStore.get()：获取主键对应的数据记录。返回一个 IDBRequest 对象。

objectStore.get(key)

8. IDBObjectStore.getAll()

DBObjectStore.getAll()：获取对象仓库的记录。返回一个 IDBRequest 对象。

// 获取所有记录
objectStore.getAll()
// 获取所有符合指定主键或 IDBKeyRange 的记录
objectStore.getAll(query)
// 指定获取记录的数量
objectStore.getAll(query, count)

9. IDBObjectStore.getAllKeys()

IDBObjectStore.getAllKeys()：用于获取所有符合条件的主键。该方法返回一个 IDBRequest 对象。

// 获取所有记录的主键
objectStore.getAllKeys()
// 获取所有符合条件的主键
objectStore.getAllKeys(query)
// 指定获取主键的数量
objectStore.getAllKeys(query, count)

10. IDBObjectStore.index()

IDBObjectStore.index()：返回指定名称的索引对象 IDBIndex。
index()方法指定获取 name 属性的索引，然后用 get()方法读取某个 name 属性(foo)对应的数据。
如果 name 属性不是对应唯一值，这时 get()方法有可能取回多个数据对象。
get()是异步方法，读取成功以后，只能在 success 事件的监听函数中处理数据。

var t = db.transaction(['people'], 'readonly');
var store = t.objectStore('people');
var index = store.index('name');
var request = index.get('foo');

11. IDBObjectStore.createIndex()

IDBObjectStore.createIndex()：新建当前数据库的一个索引。
只能在 VersionChange 监听函数里面调用。 objectStore.createIndex(indexName, keyPath, objectParameters)
三个参数
indexName：索引名
keyPath：主键
objectParameters：配置对象（可选）
第三个参数可配置
unique：如果设为 true，将不允许重复的值
multiEntry：如果设为 true，对于有多个值的主键数组，每个值将在索引里面新建一个条目，否则主键数组对应一个条目。

var store = db.createObjectStore('people', { autoIncrement: true });
store.createIndex('name', 'name', { unique: false }); // 表示可以重复
store.createIndex('email', 'email', { unique: true }); // 表示不能重复

12. IDBObjectStore.deleteIndex()

IDBObjectStore.deleteIndex()：用于删除指定的索引。只能在 VersionChange 监听函数里面调用。

objectStore.deleteIndex(indexName)

13. IDBObjectStore.openCursor()

IDBObjectStore.openCursor()：用于获取一个指针对象。
指针对象可以用来遍历数据。该对象也是异步的，有自己的 success 和 error 事件，可以对它们指定监听函数。

var t = db.transaction(['test'], 'readonly');
var store = t.objectStore('test');
var cursor = store.openCursor();
cursor.onsuccess = function (event) {
  var res = event.target.result;
  if (res) {
    console.log('Key', res.key);
    console.dir('Data', res.value);
    res.continue();
  }
}

key：主键
value：键值
continue：移动光标，如果是最后一个数据，返回 null
openCursor 两个参数
第一个参数：如果指定该参数，将只处理包含指定主键的记录；如果省略，将处理所有的记录。
第二个参数：表示遍历方向，默认值为 next，其他可能的值为 prev、nextunique 和 prevunique。后两个值表示如果遇到重复值，会自动跳过。

14. IDBObjectStore.openKeyCursor()

IDBObjectStore.openKeyCursor()：用于获取一个主键指针对象 IDBObjectStore.openKeyCursor()

IDBTransaction 对象

IDBTransaction 对象用来异步操作数据库事务，所有的读写操作都要通过这个对象进行。

1. IDBTransaction 对象属性

IDBTransaction.db：返回当前事务所在的数据库对象 IDBDatabase。
IDBTransaction.error：返回当前事务的错误。如果事务没有结束，或者事务成功结束，或者被手动终止，该方法返回 null。
IDBTransaction.mode：返回当前事务的模式，默认是 readonly（只读），另一个值是 readwrite。
IDBTransaction.objectStoreNames：返回一个类似数组的对象 DOMStringList，成员是当前事务涉及的对象仓库的名字。
IDBTransaction.onabort：指定 abort 事件（事务中断）的监听函数。
IDBTransaction.oncomplete：指定 complete 事件（事务成功）的监听函数。
IDBTransaction.onerror：指定 error 事件（事务失败）的监听函数。

2. IDBTransaction 对象方法

IDBTransaction.abort()：终止当前事务，回滚所有已经进行的变更。
IDBTransaction.objectStore(name)：返回指定名称的对象仓库 IDBObjectStore。

IDBIndex 对象

IDBIndex 对象代表数据库的索引，通过这个对象可以获取数据库里面的记录。数据记录的主键默认就是带有索引，IDBIndex 对象主要用于通过除主键以外的其他键，建立索引获取对象。 IDBIndex 是持久性的键值对存储。只要插入、更新或删除数据记录，引用的对象库中的记录，索引就会自动更新。

1. IDBIndex 对象属性

IDBIndex.name：字符串，索引的名称。
IDBIndex.objectStore：索引所在的对象仓库。
IDBIndex.keyPath：索引的主键。
IDBIndex.multiEntry：布尔值，针对 keyPath 为数组的情况，如果设为 true，创建数组时，每个数组成员都会有一个条目，否则每个数组都只有一个条目。
IDBIndex.unique：布尔值，表示创建索引时是否允许相同的主键。

2. IDBIndex 对象方法

IDBIndex.count()：用来获取记录的数量。它可以接受主键或 IDBKeyRange 对象作为参数，这时只返回符合主键的记录数量，否则返回所有记录的数量。
IDBIndex.get(key)：用来获取符合指定主键的数据记录。
IDBIndex.getKey(key)：用来获取指定的主键。
IDBIndex.getAll()：用来获取所有的数据记录。它可以接受两个参数，都是可选的，第一个参数用来指定主键，第二个参数用来指定返回记录的数量。如果省略这两个参数，则返回所有记录。由于获取成功时，浏览器必须生成所有对象，所以对性能有影响。如果数据集比较大，建议使用 IDBCursor 对象。
IDBIndex.getAllKeys()：该方法与 IDBIndex.getAll()方法相似，区别是获取所有主键。
IDBIndex.openCursor()：用来获取一个 IDBCursor 对象，用来遍历索引里面的所有条目。
IDBIndex.openKeyCursor()：该方法与 IDBIndex.openCursor()方法相似，区别是遍历所有条目的主键。

IDBCursor 对象

IDBCursor 对象代表指针对象，用来遍历数据仓库（IDBObjectStore）或索引（IDBIndex）的记录。 IDBCursor 对象一般通过 IDBObjectStore.openCursor()方法获得。

1. IDBCursor 对象属性

IDBCursor.source：返回正在遍历的对象仓库或索引。
IDBCursor.direction：字符串，表示指针遍历的方向。共有四个可能的值：next（从头开始向后遍历）、nextunique（从头开始向后遍历，重复的值只遍历一次）、prev（从尾部开始向前遍历）、prevunique（从尾部开始向前遍历，重复的值只遍历一次）。该属性通过 IDBObjectStore.openCursor()方法的第二个参数指定，一旦指定就不能改变了。
IDBCursor.key：返回当前记录的主键。
IDBCursor.value：返回当前记录的数据值。
IDBCursor.primaryKey：返回当前记录的主键。对于数据仓库（objectStore）来说，这个属性等同于 IDBCursor.key；对于索引，IDBCursor.key 返回索引的位置值，该属性返回数据记录的主键。

2. IDBCursor 对象方法

IDBCursor.advance(n)：指针向前移动 n 个位置。
IDBCursor.continue()：指针向前移动一个位置。它可以接受一个主键作为参数，这时会跳转到这个主键。
IDBCursor.continuePrimaryKey()：该方法需要两个参数，第一个是 key，第二个是 primaryKey，将指针移到符合这两个参数的位置。
IDBCursor.delete()：用来删除当前位置的记录，返回一个 IDBRequest 对象。该方法不会改变指针的位置。
IDBCursor.update()：用来更新当前位置的记录，返回一个 IDBRequest 对象。它的参数是要写入数据库的新的值。

IDBKeyRange 对象

IDBKeyRange 对象代表数据仓库（object store）里面的一组主键。根据这组主键，可以获取数据仓库或索引里面的一组记录。 IDBKeyRange 可以只包含一个值，也可以指定上限和下限。

1. IDBKeyRange 对象静态方法

它有四个静态方法，用来指定主键的范围。

IDBKeyRange.lowerBound()：指定下限。
IDBKeyRange.upperBound()：指定上限。
IDBKeyRange.bound()：同时指定上下限。
IDBKeyRange.only()：指定只包含一个值。

// All keys ≤ x
var r1 = IDBKeyRange.upperBound(x);
// All keys < x
var r2 = IDBKeyRange.upperBound(x, true);
// All keys ≥ y
var r3 = IDBKeyRange.lowerBound(y);
// All keys > y
var r4 = IDBKeyRange.lowerBound(y, true);
// All keys ≥ x && ≤ y
var r5 = IDBKeyRange.bound(x, y);
// All keys > x &&< y
var r6 = IDBKeyRange.bound(x, y, true, true);
// All keys > x && ≤ y
var r7 = IDBKeyRange.bound(x, y, true, false);
// All keys ≥ x &&< y
var r8 = IDBKeyRange.bound(x, y, false, true);
// The key = z
var r9 = IDBKeyRange.only(z);

IDBKeyRange.lowerBound()、IDBKeyRange.upperBound()、IDBKeyRange.bound()这三个方法默认包括端点值，可以传入一个布尔值，修改这个属性。

2. IDBKeyRange 对象只读属性

IDBKeyRange.lower：返回下限
IDBKeyRange.lowerOpen：布尔值，表示下限是否为开区间（即下限是否排除在范围之外）
IDBKeyRange.upper：返回上限
IDBKeyRange.upperOpen：布尔值，表示上限是否为开区间（即上限是否排除在范围之外） IDBKeyRange 实例对象生成以后，将它作为参数输入 IDBObjectStore 或 IDBIndex 对象的 openCursor()方法，就可以在所设定的范围内读取数据。

var t = db.transaction(['people'], 'readonly');
var store = t.objectStore('people');
var index = store.index('name');
var range = IDBKeyRange.bound('B', 'D');
index.openCursor(range).onsuccess = function (e) {
  var cursor = e.target.result;
  if (cursor) {
    console.log(cursor.key + ':');
    for (var field in cursor.value) {
      console.log(cursor.value[field]);
    }
    cursor.continue();
  }
}

IDBKeyRange 有一个实例方法 includes(key)，返回一个布尔值，表示某个主键是否包含在当前这个主键组之内。

var keyRangeValue = IDBKeyRange.bound('A', 'K', false, false);
keyRangeValue.includes('F') // true
keyRangeValue.includes('W') // false

操作

1. 打开数据库

var request = window.indexedDB.open(databaseName, version);

databaseName：字符串，表示数据库的名字。如果指定的数据库不存在，就会新建数据库
version：整数，表示数据库的版本。如果省略，打开已有数据库时，默认为当前版本；新建数据库时，默认为 1。
indexedDB.open()方法返回一个 IDBRequest 对象。这个对象通过三种事件 error、success、upgradeneeded，处理打开数据库的操作结果。

const request = window?.indexedDB?.open(name, version);
// 数据库创建或升级时触发
request.onupgradeneeded = (event) => {
  // 通过事件对象的target.result属性，拿到数据库实例。
  db = event.target.result;
  console.log('onupgradeneeded');
};
// 数据打开时触发；第一次打开数据库时，会先触发upgradeneeded事件，然后触发success事件。
request.onsuccess = (event) => {
  // 通过request对象的result属性拿到数据库对象。
  db = request.result;
  console.log('success');
};
// 失败时触发
request.onerror = (event) => {
  console.log(error);
};

2. 创建数据库

新建和打开数据库是同一个操作。如果指定的数据库不存在，就会新建。不同之处在于，后续的操作主要在 upgradeneeded 事件的监听函数里面完成，因为这时版本从无到有，所以会触发这个事件。

request.onupgradeneeded = function (event) {
  db = event.target.result;
  var objectStore;
  if (!db.objectStoreNames.contains('person')) {
    // 创建对象仓库，简单说就是建立一张表
    objectStore = db.createObjectStore('person', { keyPath: 'id' });
  }
}

keyPath：主键
autoIncrement: 是否自动生成主键，如果数据记录里面没有合适作为主键的属性，那么可以让 IndexedDB 自动生成主键。

3. 新增数据

var request = db.transaction(['person'], 'readwrite')
    .objectStore('person')
    .add({ id: 1, name: '张三', age: 24, email: 'zhangsan@example.com' });
  request.onsuccess = function (event) {
    console.log('数据写入成功');
  };
  request.onerror = function (event) {
    console.log('数据写入失败');
  }

上面代码中，写入数据需要新建一个事务。新建时必须指定表格名称和操作模式（“只读”或“读写”）。新建事务以后，通过 IDBTransaction.objectStore(name)方法，拿到 IDBObjectStore 对象，再通过表格对象的 add()方法，向表格写入一条记录。写入操作是一个异步操作，通过监听连接对象的 success 事件和 error 事件，了解是否写入成功。

4. 读取数据

var transaction = db.transaction(['person']);
   var objectStore = transaction.objectStore('person');
   var request = objectStore.get(1); // 1 -> keyPath
   request.onerror = function(event) {
     console.log('事务失败');
   };
   request.onsuccess = function( event) {
      if (request.result) {
       // to do
      } else {
        console.log('数据为空');
      }
   };

IDBObjectStore.get()方法用于读取数据，参数是主键的值。

5. 更新数据

var request = db.transaction(['person'], 'readwrite')
    .objectStore('person')
    .put({ id: 1, name: '李四', age: 35, email: 'lisi@example.com' });
  request.onsuccess = function (event) {
    console.log('数据更新成功');
  };
  request.onerror = function (event) {
    console.log('数据更新失败');
  }

IDBObjectStore.put()方法更新指定键值的记录。

6. 删除数据

var request = db.transaction(['person'], 'readwrite')
    .objectStore('person')
    .delete(1);
  request.onsuccess = function (event) {
    console.log('数据删除成功');
  };

IDBObjectStore.delete()方法用于删除记录。

7. 遍历数据

var objectStore = db.transaction('person').objectStore('person');
   objectStore.openCursor().onsuccess = function (event) {
     var cursor = event.target.result;
     if (cursor) {
       // to do
       cursor.continue();
     } else {
       console.log('没有更多数据了！');
    }
  };

指针对象 IDBCursor，遍历数据表格的所有记录

8. 建立索引

索引的意义在于，可以让你搜索任意字段，也就是说从任意字段拿到数据记录。如果不建立索引，默认只能搜索主键（即从主键取值）。总结再次声明，这篇文章并不是一个技术文章，纯属就是一个 API 的汇总，如果觉得可能后续会用到，建议你收藏，如果觉得没撒用，你就可以划过了，skr~~~