JavaScript 七基础学习系列五千四百一十二：用 openCursor 与 IDBKeyRange 设置游标方向

1. 为什么你的 IndexedDB 游标总是不听话很多人第一次用 IndexedDB 查数据都会遇到一个很别扭的现象明明插入了 5 条记录游标却只吐出来 3 条或者想从最新一条往前读结果还是从最旧的开始。问题往往不在数据本身而在openCursor()的两个参数上——键范围和方向。openCursor()能接收两个参数第一个是IDBKeyRange实例用来限定读取范围第二个是方向字符串决定游标怎么走。默认方向是next也就是从对象存储的第一条记录开始每次continue()往后挪一条。如果你不显式传方向它就永远按这个顺序走遇到重复键也不会帮你跳过。这篇就围绕openCursor的方向参数和IDBKeyRange的组合展开把next、nextunique、prev、prevunique四个方向讲清楚再配合索引上的游标用法最后给一段可以直接粘到浏览器控制台验证的代码。适合已经会建库建表、但对游标顺序和去重还拿不准的 JavaScript 学习者。2. 先把环境准备好TaoToken 与本地调试入口IndexedDB 是浏览器原生能力不需要额外服务就能跑。但如果你想把游标逻辑接到真实的大模型对话或编码场景里做联调可以先用 TaoToken 把 API Key 准备好省得后面来回切工具。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注册后在控制台创建 Key就能在本地脚本里调用模型对话或编码能力。具体几个常用入口模型对话调试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码 / Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCode / Anthropic 相关https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite注意IndexedDB 的游标调试完全在浏览器本地完成TaoToken 只是后续把查询结果接到模型侧时的可选通道两者不冲突。3. openCursor 方向参数与 IDBKeyRange 的可复制配置3.1 四个方向参数到底差在哪openCursor(range, direction)的第二个参数只有四个合法值方向值移动方式是否去重典型场景next从第一条到最后一条否默认顺序遍历nextunique从第一条到最后一条是跳过重复键按索引去重读取prev从最后一条到第一条否倒序取最新记录prevunique从最后一条到第一条是跳过重复键倒序去重去重只对「键相同」的记录生效。如果你在对象存储上直接用主键开游标主键本身唯一nextunique和next看起来没区别真正体现价值的是在索引上开游标因为索引键可能重复。3.2 基础游标初始化片段先建一个users对象存储主键是id再在username上建唯一索引。下面这段可以直接放进控制台const request indexedDB.open(demoDB, 1); request.onupgradeneeded (event) { const db event.target.result; const store db.createObjectStore(users, { keyPath: id }); store.createIndex(username, username, { unique: true }); }; request.onsuccess (event) { const db event.target.result; const tx db.transaction(users, readwrite); const store tx.objectStore(users); store.add({ id: 1, username: alice, age: 20 }); store.add({ id: 2, username: bob, age: 22 }); store.add({ id: 3, username: carol, age: 24 }); tx.oncomplete () console.log(初始化完成); };数据准备好后用nextunique在索引上开游标跳过重复索引键const tx db.transaction(users); const store tx.objectStore(users); const index store.index(username); const cursorReq index.openCursor(null, nextunique); cursorReq.onsuccess (event) { const cursor event.target.result; if (cursor) { console.log(索引键:, cursor.key, 主键:, cursor.primaryKey); cursor.continue(); } else { console.log(遍历结束); } };这里第一个参数传null表示键范围是全部值。第二个参数nextunique让游标在遇到相同索引键时只保留第一条。3.3 用 IDBKeyRange 限定范围再叠加方向IDBKeyRange提供only、lowerBound、upperBound、bound四个静态方法。把它和方向组合才能精确控制读取区间和顺序// 只读 id 在 2 到 3 之间的记录倒序 const range IDBKeyRange.bound(2, 3); const req store.openCursor(range, prev); req.onsuccess (event) { const cursor event.target.result; if (cursor) { console.log(倒序读到:, cursor.value); cursor.continue(); } };bound(2, 3)默认包含两端。如果想去掉上界传第三个参数trueIDBKeyRange.bound(2, 3, false, true)。范围越小游标要扫的记录越少性能越好。3.4 索引上的 openKeyCursor 与 get如果只想要主键、不想要整条记录用openKeyCursor()它的参数和openCursor()完全一样const keyReq index.openKeyCursor(null, prevunique); keyReq.onsuccess (event) { const cursor event.target.result; if (cursor) { console.log(索引键:, cursor.key, 主键:, cursor.value); cursor.continue(); } };注意区别openCursor里cursor.value是整条记录cursor.key是索引键openKeyCursor里cursor.value变成了主键。想按索引键取单条记录用index.get(alice)只取主键用index.getKey(alice)。4. 在浏览器控制台验证游标方向是否生效打开 Chrome 或 Edge 的开发者工具切到 Console把第 3 节的建库和插入代码依次执行。然后跑下面这段验证脚本它会分别用四个方向遍历并打印结果function walk(direction) { const tx db.transaction(users); const store tx.objectStore(users); const index store.index(username); const req index.openCursor(null, direction); const out []; req.onsuccess (event) { const cursor event.target.result; if (cursor) { out.push(cursor.primaryKey); cursor.continue(); } else { console.log(direction, , out.join(,)); } }; } walk(next); walk(nextunique); walk(prev); walk(prevunique);预期结果next输出1,2,3prev输出3,2,1nextunique和prevunique在索引键不重复时与next、prev一致。如果你把某条记录的username改成和另一条相同记得先删掉唯一索引否则会报错再跑一次就能看到nextunique跳过了重复项。再验证范围叠加方向const range IDBKeyRange.lowerBound(2); const req store.openCursor(range, prev); req.onsuccess (event) { const cursor event.target.result; if (cursor) { console.log(范围倒序:, cursor.value.id); cursor.continue(); } };这段应该只输出3和2且顺序是 3 在前。5. 本篇常见错误排查报错InvalidStateError: The object store uses in-line keys建索引时keyPath写错或者createIndex的第二个参数和实际属性名对不上。检查store.createIndex(username, username, ...)里两个username是否一致。游标只读到一条就停了忘了在onsuccess里调用cursor.continue()。游标不会自动前进每次拿到cursor后必须手动继续。nextunique没去重去重针对的是游标所在存储或索引的键。如果你在对象存储上开游标主键唯一自然看不出效果。要在有重复键的索引上开游标才能验证。prev读出来还是正序检查第二个参数是不是写成了next或者被变量覆盖了。方向字符串必须是小写Prev不合法。IDBKeyRange.bound报DataError下界大于上界或者类型和键类型不匹配。主键是数字就别传字符串。事务提前结束游标是异步的如果tx.oncomplete在游标遍历完之前触发说明你没有在事务里保持游标活跃。把游标逻辑放在同一个事务回调内不要跨事务复用。6. 把游标结果接到模型侧时的入口选择本地游标调通之后如果你想把查询结果丢给模型做总结、分类或生成代码可以按场景选入口。只是验证模型输出用模型对话页最直接https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果是长期编码、Agent 循环调用走 Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入过程中遇到鉴权或参数问题先看 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 大部分报错都能对上号。游标方向这块实测下来最容易踩的坑就是「以为默认会去重」。记住一句话去重靠unique后缀顺序靠next/prev前缀范围靠第一个参数。三者拆开调基本不会乱。