前端 IndexedDB 本地数据库使用指南

IDB 完整使用指南

1. 安装与基础操作

安装

yarn add idb

四个核心方法

import { openDB } from 'idb';
// 1. 打开/创建数据库（首次运行时会自动创建）
const db = await openDB('MyAppDB', 1, {
  // 参数：数据库名，版本号
  upgrade(db) {
    // 只在版本更新或初次创建时执行
    // 创建对象仓库（相当于数据库表）
    db.createObjectStore('tasks', { keyPath: 'id' // 指定主键为 id 字段 });
  }
});
// 2. 添加或更新数据
await db.put('tasks', { id: 1, // 必须有 id 字段，作为主键 title: '学习 IDB', completed: false });
// 3. 查询所有数据
const allTasks = await db.getAll('tasks');
// 4. 根据 id 查询单条
const task = await db.get('tasks', 1);
// 5. 根据 id 删除
await db.delete('tasks', 1);

2. 完整工具类封装

import { openDB } from 'idb';
class TaskDB {
  constructor() {
    this.dbName = 'TaskDatabase';
    this.storeName = 'tasks';
    this.version = 1;
  }
  // 初始化数据库连接
  async connect() {
    return openDB(this.dbName, this.version, {
      upgrade(db) {
        // 如果 tasks 表不存在就创建
        if (!db.objectStoreNames.contains('tasks')) {
          db.createObjectStore('tasks', { keyPath: 'id' // 主键字段 });
        }
      }
    });
  }
  // 增/改：保存任务
  async saveTask(task) {
    const db = await this.connect();
    // put 方法：id 存在则更新，不存在则新增
    return db.put(this.storeName, task);
  }
  // 删：删除任务
  async deleteTask(id) {
    const db = await this.connect();
    return db.delete(this.storeName, id);
  }
  // 查：获取所有任务
  async getAllTasks() {
    const db = await this.connect();
    return db.getAll(this.storeName);
  }
  // 查：根据 id 获取单个任务
  async getTask(id) {
    const db = await this.connect();
    return db.get(this.storeName, id);
  }
}
export default new TaskDB(); // 导出单例实例

3. React 组件中使用

import React, { useState, useEffect } from 'react';
import taskDB from './taskDB'; // 导入上面封装的数据库工具

function TaskManager() {
  const [tasks, setTasks] = useState([]);
  const [newTaskTitle, setNewTaskTitle] = useState('');

  // 组件加载时从数据库读取所有任务
  useEffect(() => {
    loadTasks();
  }, []);

  // 从数据库加载任务
  const loadTasks = async () => {
    const savedTasks = await taskDB.getAllTasks();
    setTasks(savedTasks || []); // 处理空数据情况
  };

  // 添加新任务
  const handleAddTask = async () => {
    if (!newTaskTitle.trim()) return;
    const newTask = {
      id: Date.now(), // 使用时间戳作为唯一 ID
      title: newTaskTitle,
      completed: false,
      createdAt: new Date().toISOString()
    };
    // 1. 保存到数据库
    await taskDB.saveTask(newTask);
    // 2. 更新界面状态
    setTasks([...tasks, newTask]);
    setNewTaskTitle('');
  };

  // 切换任务完成状态
  const handleToggleTask = async (task) => {
    const updatedTask = { ...task, completed: !task.completed };
    // 1. 更新数据库
    await taskDB.saveTask(updatedTask);
    // 2. 更新界面状态
    setTasks(tasks.map(t => t.id === task.id ? updatedTask : t));
  };

  // 删除任务
  const handleDeleteTask = async (taskId) => {
    // 1. 从数据库删除
    await taskDB.deleteTask(taskId);
    // 2. 从界面状态删除
    setTasks(tasks.filter(task => task.id !== taskId));
  };

  return (
    <div className="task-manager">
      <h1>任务管理器</h1>
      {/* 添加任务表单 */}
      <div className="add-task">
        <input type="text" value={newTaskTitle} onChange={(e) => setNewTaskTitle(e.target.value)} placeholder="输入新任务..." />
        <button onClick={handleAddTask}>添加</button>
      </div>
      {/* 任务列表 */}
      <ul className="task-list">
        {tasks.map(task => (
          <li key={task.id} className={task.completed ? 'completed' : ''}>
            <input type="checkbox" checked={task.completed} onChange={() => handleToggleTask(task)} />
            <span>{task.title}</span>
            <button onClick={() => handleDeleteTask(task.id)} className="delete-btn">删除</button>
          
        ))}
      
      {/* 统计信息 */}
      总计：{tasks.length} 个任务 | 已完成：{tasks.filter(t => t.completed).length} | 未完成：{tasks.filter(t => !t.completed).length}
    
  );
}
export default TaskManager;

4. 关键概念说明

📌 必知要点

1. keyPath: 'id'：指定数据的主键字段，每条数据必须有唯一的 id
2. put() vs add()：
   • put()：id 存在则更新，不存在则新增
   • add()：只能新增，id 重复会报错
3. 版本控制：修改数据库结构时需增加版本号

// 版本升级示例
openDB('MyDB', 2, { // 版本从 1 升到 2
  upgrade(db, oldVersion) {
    if (oldVersion < 1) {
      // 初始创建
      db.createObjectStore('tasks', { keyPath: 'id' });
    }
    if (oldVersion < 2) {
      // 新增索引（可按标题搜索）
      const store = db.transaction.objectStore('tasks');
      store.createIndex('title', 'title');
    }
  }
});

5. 官方资源

• GitHub 仓库：jakearchibald/idb
• 完整 API 文档：仓库中的 README 文件
• 在线体验：IDB 示例

6. 故障排除

// 1. 确保所有操作都是异步的
try {
  const db = await openDB(...);
  await db.put(...);
} catch (error) {
  console.error('数据库错误:', error);
}
// 2. 检查浏览器兼容性
if (!window.indexedDB) {
  alert('您的浏览器不支持 IndexedDB');
}
// 3. 清除缓存（开发时有用）
indexedDB.deleteDatabase('MyAppDB');

💡 一句话总结：openDB 打开数据库，put 保存数据，get 查询数据，delete 删除数据，所有操作都要加 await.