Blazor WebAssembly 使用 IndexedDB 离线存储教程

Blazor WebAssembly 可通过 JS 互操作调用 IndexedDB 实现离线结构化存储，需封装 JS API 并在 C# 中用 IJSRuntime 调用；须处理数据库版本升级、降级容错（如 localStorage）、待同步队列及冲突策略。

Blazor WebAssembly 可以通过 JavaScript 互操作调用 IndexedDB，在离线场景下持久化存储结构化数据。核心思路是封装 JS 的 IndexedDB API，再从 C# 侧调用。

准备 JavaScript 封装函数

在 wwwroot/index.html 的 或 底部添加轻量 JS 工具函数，避免依赖第三方库：

• 定义 initDB：打开或创建数据库，设定 objectStore 和索引（如按 id 或 timestamp）
• 提供 saveRecord、getRecordById、getAllRecords、deleteRecord 等方法，返回 Promise
• 所有操作统一返回 { success: true/false, data?: any, error?: string } 格式，便于 C# 解析

在 Blazor 组件中调用 IndexedDB

使用 IJSRuntime 执行 JS 方法，配合 await 处理异步结果：

• 注入 @inject IJSRuntime JSRuntime
• 初始化时调用 await JSRuntime.InvokeVoidAsync("initDB", "MyAppDB", 1);
• 存数据：var result = await JSRuntime.InvokeAsync("saveRecord", "users", userObject);
• 查数据：var users = await JSRuntime.InvokeAsync("getAllRecords", "users");

建议将 JS 调用逻辑抽成服务类（如 IndexedDbService），统一处理错误和类型转换。

处理版本升级与数据迁移

IndexedDB 数据库升级需监听 onupgradeneeded 事件：

• 首次打开或版本号升高时触发，用于新建/修改 objectStore 或索引
• 例如 v2 升级时新增 email 索引：objectStore.createIndex("byEmail", "email", { unique: true });
• C# 侧可封装 upgradeDB(newVersion) 方法，传入目标版本号触发 JS 升级流程

离线状态下的容错与同步策略

IndexedDB 本身不联网，但需设计应用层逻辑应对“暂存→上线同步”场景：

• 写操作失败（如浏览器禁用 IndexedDB）时降级到 localStorage 存 JSON 字符串（仅限简单数据）
• 维护一个 pendingOperations 队列，记录待同步的增删改动作
• 监听 navigator.onLine 或轮询 API 可达性，网络恢复后批量提交并清理队列
• 冲突处理建议用时间戳或版本号（_v 字段），服务端决定是否覆盖

基本上就这些。不复杂但容易忽略版本管理和离线队列设计，实际项目中建议搭配简单的日志记录和用户提示（比如“已离线保存，正在同步…”）提升体验。