Querying with Cursors

Transactions can be used directly to retrieve a single item with a known key. When you want to retrieve multiple items, you need to create a cursor within the transaction. A cursor is a pointer into a result set. Unlike traditional database queries, a cursor doesn’t gather all of the result set up front. Instead, a cursor points to the fi rst result and doesn’t try to find the next until instructed to do so. 

翻译：

事务能直接取出已知主键的单一条目。当你想要取出多个条目是，你需要在事务里面创建一个光标。一个光标就是结果集中的一个指针。

Cursors are created using the openCursor() method on an object store. As with other operations with IndexedDB, the return value of openCursor() is a request, so you must assign onsuccess and onerror event handlers. For example:

翻译：

使用对象存储上的openCursor()来创建光标。和IndexDB上的其他操作一样，方法openCursor()的返回值是一个请求，所以你必须实现onsuccess和onerror时间。如下：

var store = db.transaction(“users”).objectStore(“users”), request = store.openCursor();

request.onsuccess = function(event){

//handle success };

request.onfailure = function(event){

//handle failure };

When the onsuccess event handler is called, the next item in the object store is accessible via event.target.result, which holds an instance of IDBCursor when there is a next item or null when there are no further items. The IDBCursor instance has several properties:

翻译：

当成功事件被调用的时候，通过event.target.result你可以访问对象存储中的条目。如果还有下一条，event.target.result返回IDBCursor的实例；如果没有下一条，则返回null；IDBCursor实例有一些属性：

direction — A numeric value indicating the direction the cursor should travel in. The default is IDBCursor.NEXT (0) for next. Other values include IDBCursor.NEXT_ NO_DUPLICATE (1) for next without duplicates, IDBCursor.PREV (2) for previous, and IDBCursor.PREV_NO_DUPLICATE (3) for previous without duplicates.

key — The key for the object.

value — The actual object.

primaryKey — The key being used by the cursor. Could be the object key or an index key (discussed later).

翻译：

direction — 一个数字，指示光标行进的方向。默认值是IDBCursor.NEXT (0)，向前进。其他的值包含IDBCursor.NEXT_ NO_DUPLICATE (1) 向前进排除重复值。IDBCursor.PREV (2)，向后退；IDBCursor.PREV_NO_DUPLICATE (3)向后退排除重复的。

key — 对象的主键。

value — 对象本身。’

primaryKey — 光标使用的主键。可以是对象的主键或者一个索引键（稍后讨论）。

You can retrieve information about a single result using the following:

翻译：

使用如下代码，你能获得一个单一结果的信息：

request.onsuccess = function(event){

var cursor = event.target.result;

if (cursor){ //always check

console.log(“Key: “ + cursor.key + “, Value: “ + JSON.stringify(cursor.value));

} };

Keep in mind that cursor.value in this example is an object, which is why it is JSON encoded before being displayed.

翻译：

注意此示例中cursor.value是一个对象，所以显示前需要JSON编码。

A cursor can be used to update an individual record. The update() method updates the current cursor value with the specified object. As with other such operations, the call to update() creates a new request, so you need to assign onsuccess and onerror if you want to know the result:

翻译：

一个光标能被用来更新某条记录。 方法update()更新指定对象的光标值。和其他操作一样，方法update()的调用创建了一个新的请求，因此如果你想知道结果，你需要给onsuccess和onerror事件柄赋值：

request.onsuccess = function(event){

var cursor = event.target.result, value, updateRequest;

if (cursor){ //always check

if (cursor.key == “foo”){

value = cursor.value; //get current value

value.password = “magic!”; //update the password

updateRequest = cursor.update(value); //request the update be saved

updateRequest.onsuccess = function(){ //handle success; };

updateRequest.onfailure = function(){ //handle failure }; } } };

You can also delete the item at that position by calling delete(). As with update(), this also creates a request:

翻译：

通过调用方法delete()，你也能删除那个位置的条目。和update()一样，这样也会创建一个请求：

request.onsuccess = function(event){

var cursor = event.target.result, value, deleteRequest;

if (cursor){ //always check

if (cursor.key == “foo”){

deleteRequest = cursor.delete(); //request the value be deleted

deleteRequest.onsuccess = function(){ //handle success; };

deleteRequest.onfailure = function(){ //handle failure }; } } };

Both update() and delete() will throw errors if the transaction doesn’t have permission to modify the object store.

翻译：

假如事务没有权限修改对象，udpate()和delete()都将抛出异常。

Each cursor makes only one request by default. To make another request, you must call one of the following methods:

每个光标默认只产生一次请求。为了产生其他的请求，你必须调用下列方法之一：

continue(key) — Moves to the next item in the result set. The argument key is optional. When not specified, the cursor just moves to the next item; when provided, the cursor will move to the specified key.

advance(count) — Moves the cursor ahead by count number of items.

翻译： 

continue(key) — 移动到结果集的下个条目。参数可选。如果不指定，光标就移往下个条目；如果提供，光标则移往指定主键。

advance(count) — 往前移动光标跳过指定数量的条目。

Each of these methods causes the cursor to reuse the same request, so the same onsuccess and onfailure event handlers are reused until no longer needed. For example, the following iterates over all items in an object store:

上述方法都使得光标重用相同的请求。因此，相同的onsuccess和onfailure事件被重用直到不再需要。例如，下面代码遍历了对象存储中的所有条目。

request.onsuccess = function(event){

var cursor = event.target.result;

if (cursor){ //always check

console.log(“Key: “ + cursor.key + “, Value: “ + JSON.stringify(cursor.value));

cursor.continue(); //go to the next one

} else {

console.log(“Done!”); } };

The call to continue() triggers another request and onsuccess is called again. When there are no more items to iterate over, onsuccess is called one last time with event.target.result equal to null.

翻译： 

continue()的调用触发了另一个请求，然后onsuccess被再次调用。当遍历结束之后，onsuccess被最后一次调用，此时，event.target.result为空。