因为虽然市面上很多封装库（比如 Dexie.js）简化了开发，但 理解底层原生 API 更利于掌握其原理和限制，特别是在一些高级使用场景下（事务、索引、多表操作等）你迟早会接触到底层。

🧠 IndexedDB 核心概念结构（大局观）

要看接口之前，先弄清楚 IndexedDB 的结构，才能理解 API 之间的关系。

IndexedDB
└── 数据库（Database）
    └── 版本（Version）
        └── 对象仓库（Object Store）  // 相当于表
            └── 数据记录（Record）     // 存储的实际数据
            └── 索引（Index）         // 加快查询

📦 原生 IndexedDB API 总览（按流程分类）

我们从一个应用启动 IndexedDB 的常见操作流程来拆解 API：

1. 打开数据库（`indexedDB.open()`）

const request = indexedDB.open('MyDatabase', 1); // 数据库名 & 版本

返回一个 IDBOpenDBRequest 对象，有这些回调：

request.onerror = (event) => {
  console.error("打开失败", event.target.error);
};

request.onsuccess = (event) => {
  const db = event.target.result; // IDBDatabase 实例
};

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  // 创建 Object Store（相当于一张表）
  if (!db.objectStoreNames.contains('notes')) {
    db.createObjectStore('notes', { keyPath: 'id', autoIncrement: true });
  }
};

2. 操作数据库（通过 `transaction`）

所有增删改查都必须通过事务完成：

const tx = db.transaction('notes', 'readwrite'); // 事务对象
const store = tx.objectStore('notes');           // 表对象

3. 增加数据（`store.add()`）

store.add({ title: '第一篇', content: '你好，世界' });

如果用了 keyPath 就不用显式指定主键。
不存在则新增，存在会报错（替代用 put()）

4. 更新数据（`store.put()`）

store.put({ id: 1, title: '更新后的标题' });

put 和 add 的区别是：有就覆盖、没有就插入。

5. 读取数据（`store.get()` / `store.getAll()`）

store.get(1).onsuccess = (e) => {
  console.log('内容：', e.target.result);
};

全部获取：

store.getAll().onsuccess = (e) => {
  console.log('全部记录：', e.target.result);
};

6. 删除数据（`store.delete()`）

store.delete(1);

7. 使用索引（`store.createIndex()` + `index.get()`）

在 onupgradeneeded 中添加索引：

const store = db.createObjectStore('notes', { keyPath: 'id' });
store.createIndex('by_title', 'title', { unique: false });

查询：

const index = store.index('by_title');
index.get('第一篇').onsuccess = (e) => {
  console.log('通过索引查询到的结果：', e.target.result);
};

8. 范围查询（`IDBKeyRange` + `openCursor()`）

获取 ID 从 1 到 100 的所有数据：

const range = IDBKeyRange.bound(1, 100);
store.openCursor(range).onsuccess = (e) => {
  const cursor = e.target.result;
  if (cursor) {
    console.log(cursor.key, cursor.value);
    cursor.continue();
  }
};

9. 删除 Object Store（表）

只能在 onupgradeneeded 中操作：

db.deleteObjectStore('notes');

10. 关闭数据库连接

db.close();

🌐 主要接口清单一览（快速查阅）

接口	说明
`indexedDB.open(name, version)`	打开或创建数据库
`IDBDatabase.createObjectStore()`	创建表（Object Store）
`IDBDatabase.transaction()`	创建事务
`IDBObjectStore.add()` / `put()`	添加/更新数据
`IDBObjectStore.get()` / `getAll()`	获取数据
`IDBObjectStore.delete()`	删除记录
`IDBObjectStore.index()`	获取索引对象
`IDBIndex.get()` / `openCursor()`	通过索引查询
`IDBKeyRange`	用于范围查询
`IDBTransaction.oncomplete`	事务完成回调
`IDBDatabase.close()`	关闭连接

🧪 示例：完整增删改查 Demo（原生 IndexedDB）

// 打开数据库
const request = indexedDB.open("MyDB", 1);

// 数据库升级或首次创建时
request.onupgradeneeded = function (e) {
  const db = e.target.result;
  const store = db.createObjectStore("notes", { keyPath: "id", autoIncrement: true });
  store.createIndex("by_title", "title", { unique: false });
};

// 操作成功
request.onsuccess = function (e) {
  const db = e.target.result;

  // 添加记录
  const tx = db.transaction("notes", "readwrite");
  const store = tx.objectStore("notes");
  store.add({ title: "Hello", content: "World" });

  // 查询全部
  store.getAll().onsuccess = (ev) => {
    console.log("所有记录：", ev.target.result);
  };
};

🧠 总结

对象	作用
`indexedDB`	全局入口（用于 open）
`IDBDatabase`	数据库对象（操作事务）
`IDBObjectStore`	表（操作数据）
`IDBTransaction`	事务对象
`IDBIndex`	索引
`IDBKeyRange`	范围查询工具

📚 延伸建议

如果你理解了这些接口，下一步建议：

封装一套简单的 db.js 帮助方法（比如 saveNote(note)、getAllNotes()）
或者使用 Dexie.js 简化开发
如果你有具体使用场景（比如 markdown 快照编辑器），我可以帮你写一套原生 API 封装模板

基础封装

好的，咱们来写一个原生 IndexedDB 的封装模板，方便你后续在项目中直接使用。这个封装适用于你之前提到的 “定时存储 markdown 内容 + 快照 timeline” 的场景，也可扩展到任意表。

✅ 特点

纯原生 IndexedDB API（无第三方库）
简单封装常用操作：initDB、add、put、get、getAll、delete 等
支持多个 ObjectStore（相当于表）
支持自定义主键（keyPath）

📦 封装模块：`indexedDBWrapper.js`

const DB_NAME = 'MyMarkdownDB';
const DB_VERSION = 1;
let dbInstance = null;

export const openDB = () => {
  return new Promise((resolve, reject) => {
    if (dbInstance) return resolve(dbInstance);

    const request = indexedDB.open(DB_NAME, DB_VERSION);

    request.onupgradeneeded = (e) => {
      const db = e.target.result;
      // 初始化一个 notes 表（你可以扩展更多表）
      if (!db.objectStoreNames.contains('notes')) {
        const store = db.createObjectStore('notes', {
          keyPath: 'id',
          autoIncrement: true,
        });
        store.createIndex('by_timestamp', 'timestamp', { unique: false });
      }
    };

    request.onsuccess = (e) => {
      dbInstance = e.target.result;
      resolve(dbInstance);
    };

    request.onerror = (e) => reject(e.target.error);
  });
};

const getStore = async (storeName, mode = 'readonly') => {
  const db = await openDB();
  const tx = db.transaction(storeName, mode);
  return tx.objectStore(storeName);
};

// 添加数据
export const addRecord = async (storeName, data) => {
  const store = await getStore(storeName, 'readwrite');
  return store.add(data);
};

// 更新数据（存在则更新）
export const putRecord = async (storeName, data) => {
  const store = await getStore(storeName, 'readwrite');
  return store.put(data);
};

// 获取单条
export const getRecord = async (storeName, key) => {
  const store = await getStore(storeName);
  return new Promise((resolve) => {
    const req = store.get(key);
    req.onsuccess = () => resolve(req.result);
  });
};

// 获取全部
export const getAllRecords = async (storeName) => {
  const store = await getStore(storeName);
  return new Promise((resolve) => {
    const req = store.getAll();
    req.onsuccess = () => resolve(req.result);
  });
};

// 删除某条
export const deleteRecord = async (storeName, key) => {
  const store = await getStore(storeName, 'readwrite');
  return store.delete(key);
};

✅ 使用示例

import {
  addRecord,
  getAllRecords,
  deleteRecord
} from './indexedDBWrapper';

// 定时保存 Markdown 快照
const saveSnapshot = async (markdown) => {
  await addRecord('notes', {
    content: markdown,
    timestamp: Date.now()
  });
};

// 获取所有快照
const loadSnapshots = async () => {
  const list = await getAllRecords('notes');
  console.log('历史记录:', list);
  return list;
};

// 删除某个快照
const deleteSnapshot = async (id) => {
  await deleteRecord('notes', id);
};

🧠 设计说明 & 可扩展建议

🧩 扩展更多 Object Store（表）

可以在 onupgradeneeded 里按需添加：

if (!db.objectStoreNames.contains('users')) {
  db.createObjectStore('users', { keyPath: 'id', autoIncrement: true });
}

🧠 增强点

你可以后续加上：

queryByIndex(store, indexName, value)
clearStore(storeName) 清空某个表
getByRange() 配合 IDBKeyRange
export/import 所有数据

✅ 总结

现在你已经有了一个：

通用的原生 IndexedDB 封装
可用于 markdown 编辑器的“自动快照 + 历史记录”功能
可以用在任意前端框架（React、Vue、原生 JS）