前端 IndexedDB 实战指南

3. 工具类封装实践

为了复用性，建议将数据库操作封装为单例类。这样既能管理连接状态，又能统一错误处理。

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) {
        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);
  }

  async getTask(id) {
    const db = await this.connect();
    return db.get(this.storeName, id);
  }
}

export default new TaskDB();

React 组件集成

在 React 中使用只需结合 useEffect 和 useState 即可实现数据持久化。下面是一个简单的任务管理器示例：

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(),
      title: newTaskTitle,
      completed: false,
      createdAt: new Date().toISOString()
    };
    await taskDB.saveTask(newTask);
    setTasks([...tasks, newTask]);
    setNewTaskTitle('');
  };

  const handleToggleTask = async (task) => {
    const updatedTask = { ...task, completed: !task.completed };
    await taskDB.saveTask(updatedTask);
    setTasks(tasks.map(t => t.id === task.id ? updatedTask : t));
  };

  const handleDeleteTask = async (taskId) => {
    await taskDB.deleteTask(taskId);
    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)}>删除</>
          
        ))}
      
      
        总计：{tasks.length} | 已完成：{tasks.filter(t => t.completed).length}
      
    
  );
}

export default TaskManager;

关键概念与注意事项

在实际开发中，有几个细节需要特别注意：

1. 主键设置：keyPath: 'id' 意味着每条数据必须有唯一的 id 字段，否则无法正确索引。
2. put vs add：put() 允许更新已存在的记录，而 add() 只能新增，重复会报错。
3. 版本控制：修改数据库结构（如新增索引）时，必须增加版本号并编写 upgrade 逻辑。

// 版本升级示例：从 v1 升级到 v2，新增标题索引
openDB('MyDB', 2, {
  upgrade(db, oldVersion) {
    if (oldVersion < 2) {
      const store = db.transaction.objectStore('tasks');
      store.createIndex('title', 'title');
    }
  }
});

故障排查

如果遇到数据库操作失败，可以尝试以下检查：

• 异步问题：确保所有操作都加了 await，避免回调地狱或状态不同步。
• 兼容性：检查 window.indexedDB 是否存在（IE 不支持）。
• 清除缓存：开发阶段可手动调用 indexedDB.deleteDatabase('MyAppDB') 重置数据。

try {
  const db = await openDB(...);
  await db.put(...);
} catch (error) {
  console.error('数据库错误:', error);
}

参考资料

• GitHub 仓库：jakearchibald/idb
• 在线体验：IDB 示例