diff options
Diffstat (limited to 'files/zh-cn/web/api/idbobjectstore/index.html')
| -rw-r--r-- | files/zh-cn/web/api/idbobjectstore/index.html | 759 |
1 files changed, 759 insertions, 0 deletions
diff --git a/files/zh-cn/web/api/idbobjectstore/index.html b/files/zh-cn/web/api/idbobjectstore/index.html new file mode 100644 index 0000000000..172820799e --- /dev/null +++ b/files/zh-cn/web/api/idbobjectstore/index.html @@ -0,0 +1,759 @@ +--- +title: IDBObjectStore +slug: Web/API/IDBObjectStore +tags: + - API + - IDBObjectStore + - IndexedDB + - Storage + - local storage & cache +translation_of: Web/API/IDBObjectStore +--- +<p>{{APIRef("IndexedDB")}}</p> + +<p> <a href="https://developer.mozilla.org/en/IndexedDB" title="en/IndexedDB">IndexedDB API</a> 的 <strong><code>IDBObjectStore </code></strong>接口表示数据库中的 一个 <a href="https://developer.mozilla.org/en/IndexedDB#gloss_object_store" title="en/IndexedDB#gloss object store">对象库(object store)</a> 。对象库中的记录根据其键值进行排序。这种排序可以实现快速插入，查找和有序检索。</p> + +<p>{{AvailableInWorkers}}</p> + +<p>注：为了方便理解，可以把“对象存储空间”想象成关系数据库的“表”结构，下文也会把对象存储空间称为表。</p> + +<h2 id="方法预览">方法预览</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#add()">add</a> (in any value, in optional any key) raises (<a href="/En/DOM/DOMException" title="en/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#clear()">clear</a> () raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#count()">count</a> (in optional any key) raises</code><code>(<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a> <a href="#createIndex()">createIndex</a> (in <a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a> name, in </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code> keyPath, in optional boolean unique) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#delete()">delete</a> (in any key) raises </code><code>(<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code>void <a href="#deleteIndex()">deleteIndex</a> (in any </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code> indexName) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#get()">get</a> (in any key) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a> <a href="#index()">index</a> (in </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code> name) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#openCursor()">openCursor</a> (in optional <a href="/en/IndexedDB/IDBKeyRange" title="en/IndexedDB/IDBKeyRange">IDBKeyRange</a> range, in optional unsigned short direction) raises(<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></td> + </tr> + <tr> + <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#put()">put</a> (in any value, in optional any key) raises (<a href="/En/DOM/DOMException" title="en/DOM/DOMException">DOMException</a>);</code></td> + </tr> + </tbody> +</table> + +<h2 id="属性">属性</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Attribute</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td id="attr_indexNames"><code>indexNames</code></td> + <td><code>readonly DOMStringList</code></td> + <td>表中对象的<a href="https://developer.mozilla.org/en/IndexedDB#gloss_index" title="https://developer.mozilla.org/en/IndexedDB#gloss_index">索引</a>名列表。</td> + </tr> + <tr> + <td id="attr_keyPath"><code>keyPath</code></td> + <td><code>readonly </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> + <td>表中的<a href="https://developer.mozilla.org/en/IndexedDB#gloss_key_path" title="https://developer.mozilla.org/en/IndexedDB#gloss_key_path">键路径</a>，如果该属性为null，每次操作表时必须提供一个键名。</td> + </tr> + <tr> + <td id="attr_name"><code>name</code></td> + <td><code>readonly </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> + <td>表名</td> + </tr> + <tr> + <td id="transaction"><code>transaction</code></td> + <td><code>readonly <a href="/en-US/docs/IndexedDB/IDBTransaction" title="/en-US/docs/IndexedDB/IDBTransaction">IDBTransaction</a></code></td> + <td>事务的名称，该表属于此事务。</td> + </tr> + <tr> + <td id="autoincrement"><code>autoIncrement</code></td> + <td><code>readonly boolean</code></td> + <td>表中自增字段的值</td> + </tr> + </tbody> +</table> + +<h2 id="方法">方法</h2> + +<h3 id="add">add()</h3> + +<p>返回一个IDBRequest对象，并且在新线程中克隆一个值，该值存储在表中。</p> + +<p>想知道是否成功添加数据，可以在事务的complete事件中进行监听，而不是success，因为事务在success事件之后还有可能失败。</p> + +<p>add方法只能插入数据。如果以key参数作为某记录的关键字，并且该条记录已存在，则其所返回的请求对象会产生ConstrainError错误。</p> + +<pre><a href="/en/IndexedDB/IDBRequest" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/IndexedDB/IDBRequest">IDBRequest</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> </span><a href="#add" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="#add">add</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> (in any value, in optional any key) raises (</span><a href="/En/DOM/DOMException" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/DOM/DOMException">DOMException</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">);</span></pre> + +<h5 id="参数">参数</h5> + +<dl> + <dt>value</dt> + <dd>被存储的值。</dd> + <dt>key</dt> + <dd>标识某条记录的键，如果不指定，它会被设为null。</dd> +</dl> + +<h5 id="返回">返回</h5> + +<dl> + <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> + <dd>一个请求对象，可以在其中绑定事件。</dd> +</dl> + +<h5 id="异常">异常</h5> + +<p>该方法会抛出DOMError类型的DOMException异常。</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>ReadOnlyError</td> + <td>The transaction associated with this operation is in read-only <a href="/en-US/docs/IndexedDB/IDBTransaction#mode_constants" title="/en-US/docs/IndexedDB/IDBTransaction#mode_constants">mode</a>.</td> + </tr> + <tr> + <td>TransactionInactiveError</td> + <td>This IDBObjectStore's transaction is inactive.</td> + </tr> + <tr> + <td><span style="line-height: normal;">DataError</span></td> + <td> + <p>Any of the following conditions apply:</p> + + <ul> + <li>The object store uses in-line keys or has a key generator, and a key parameter was provided.</li> + <li>The object store uses out-of-line keys and has no key generator, and no key parameter was provided.</li> + <li>The object store uses in-line keys but no key generator, and the object store's key path does not yield a valid key.</li> + <li>The key parameter was provided but does not contain a valid key.</li> + </ul> + </td> + </tr> + <tr> + <td><code>InvalidStateError</code></td> + <td>The IDBObjectStore has been deleted or removed.</td> + </tr> + <tr> + <td><code>DataCloneError</code></td> + <td>The data being stored could not be cloned by the internal structured cloning algorithm.</td> + </tr> + </tbody> +</table> + +<h3 id="clear">clear()</h3> + +<p>创建并立即返回一个 <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> 对象, 并且在一个单独的线程中清除这个对象存储. 清除对象存储包括从对象存储中删除所有的记录，并删除对象存储引用的索引中的所有记录。</p> + +<pre><a href="/en/IndexedDB/IDBRequest" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/IndexedDB/IDBRequest">IDBRequest</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> </span><a href="#clear" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="#clear">clear</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> () raises (</span><a href="/en-US/docs/DOM/DOMException" style="font-family: 'Courier New', 'Andale Mono', monospace;" title="/en-US/docs/DOM/DOMException">DOMException</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">);</span></pre> + +<h5 id="Returns">Returns</h5> + +<dl> + <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> + <dd>返回一个request对象，在其上触发与操作相关的事件。</dd> +</dl> + +<h5 id="Exceptions">Exceptions</h5> + +<p>此方法可能会引发domException，其中domError的类型如下：</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>ReadOnlyError</td> + <td>The transaction associated with this operation is in read-only <a href="/en-US/docs/IndexedDB/IDBTransaction#mode_constants" title="/en-US/docs/IndexedDB/IDBTransaction#mode_constants">mode</a>.</td> + </tr> + <tr> + <td>TransactionInactiveError</td> + <td>This IDBObjectStore's transaction is inactive.</td> + </tr> + </tbody> +</table> + +<h3 id="count">count()</h3> + +<p>立即返回一个 <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> 对象，并在新线程中计算符合条件的对象的数量，该方法的参数可以是键，或键范围（key range）。在 <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> 对象中，source属性就是IDBObjectStore对象，result属性持有计算后的数量值。如果参数非法将会抛出异常。</p> + +<pre><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="/en/IndexedDB/IDBObjectStore#count" title="en/IndexedDB/IDBObjectStore#count">count</a> (in optional any key) raises</code><code style="font-size: 14px; color: rgb(51, 51, 51);">(<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></pre> + +<h5 id="参数_2">参数</h5> + +<dl> + <dt>key</dt> + <dd>计算被该键或键范围（key range）所标识的记录数。</dd> +</dl> + +<h5 id="Returns_2">Returns</h5> + +<dl> + <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> + <dd>一个请求对象，可绑定事件。</dd> +</dl> + +<h5 id="异常_2">异常</h5> + +<p>该方法会引发如下异常：</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>TransactionInactiveError</td> + <td>事务已闲置</td> + </tr> + <tr> + <td>DataError</td> + <td> + <p>key参数非法</p> + </td> + </tr> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>IDBObjectStore对象已被删除</td> + </tr> + </tbody> +</table> + +<h3 id="createIndex">createIndex()</h3> + +<dl> +</dl> + +<p>创建并返回新的IDBIndex对象，该方法只能从versionchange事务模式的回调方法中被调用。</p> + +<pre><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a> <a href="#createIndex" title="#createIndex">createIndex</a> (in <a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a> name, in </code><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code style="font-size: 14px; color: rgb(51, 51, 51);"> keyPath, in optional boolean unique) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></pre> + +<h5 id="Parameters">Parameters</h5> + +<dl> + <dt>name</dt> + <dd>The name of the index to create.</dd> + <dt>keyPath</dt> + <dd>The key path for the index to use.</dd> + <dt>optionalParameters</dt> + <dd> + <p class="warning">The IDBIndexParameters object whose attributes are optional parameters to the method. It includes the following properties:</p> + + <table class="standard-table"> + <thead> + <tr> + <th scope="col">Attribute</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>unique</code></td> + <td>If true, the index will not allow duplicate values for a single key.</td> + </tr> + <tr> + <td><code>multiEntry</code></td> + <td>If true, the index will add an entry in the index for each array element when the <em>keypath</em> resolves to an Array. If false, it will add one single entry containing the Array.</td> + </tr> + </tbody> + </table> + </dd> +</dl> + +<h5 id="Returns_3">Returns</h5> + +<dl> + <dt><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a></dt> + <dd>The newly created index.</dd> +</dl> + +<h5 id="Exceptions_2">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>The IDBObjectStore has been deleted or removed or the method was not called from a <code><a href="/en-US/docs/IndexedDB/IDBTransaction#VERSION_CHANGE" title="/en-US/docs/IndexedDB/IDBTransaction#VERSION_CHANGE">versionchange</a></code> transaction mode callback.</td> + </tr> + <tr> + <td><code style="font-size: 14px;">ConstraintError</code></td> + <td>An index with the same name (case-sensitive) already exists in the database.<br> + </td> + </tr> + </tbody> +</table> + +<h3 id="delete">delete()</h3> + +<dl> +</dl> + +<p>Immediately returns an <code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></code> object, and removes the records specified by the given key or key range from this object store, and any indexes that reference it, in a separate thread.</p> + +<pre><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#delete" title="#delete">delete</a> (in any key) raises </code><code style="font-size: 14px; color: rgb(51, 51, 51);">(<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></pre> + +<h5 id="Parameters_2">Parameters</h5> + +<dl> + <dt>key</dt> + <dd>The key or key range that identifies the records.</dd> +</dl> + +<h5 id="Returns_4">Returns</h5> + +<dl> + <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> + <dd>A request object on which subsequent events related to this operation are fired. As <a href="http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation" title="http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation">per spec</a> the result of the Object Store Deletion Operation algorithm is <code>undefined</code>, so it's not possible to know if some records were actually deleted by looking at the request result.</dd> +</dl> + +<h5 id="Exceptions_3">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>TransactionInactiveError</td> + <td>This IDBObjectStore's transaction is inactive.</td> + </tr> + <tr> + <td>ReadOnlyError</td> + <td> + <p>The transaction associated with this operation is in read-only <a href="/en-US/docs/IndexedDB/IDBTransaction#mode_constants" title="/en-US/docs/IndexedDB/IDBTransaction#mode_constants">mode</a>.</p> + </td> + </tr> + <tr> + <td><code>DataError</code></td> + <td>The key or key range provided contains an invalid key.</td> + </tr> + </tbody> +</table> + +<dl> +</dl> + +<div class="note"> +<p>If the key that identifies the record is a Number, the key passed to the delete method must be a Number too, and not a String. So for example you might need to do the following:</p> + +<pre class="brush: js">var key_val = '42'; +var key = Number(key_val); +objectstore.delete(key);</pre> +</div> + +<h3 id="deleteIndex">deleteIndex()</h3> + +<p>Destroys the index with the specified name in the connected database. Note that this method must be called only from a <code><a href="/en/IndexedDB/IDBTransaction#VERSION_CHANGE" title="en/IndexedDB/IDBTransaction#VERSION CHANGE">VersionChange</a></code> transaction mode callback. Note that this method synchronously modifies the <a href="#attr_indexNames" title="#attr_indexNames">indexNames</a> property.</p> + +<pre><code style="font-size: 14px; color: rgb(51, 51, 51);">void <a href="#deleteIndex" title="#deleteIndex">deleteIndex</a> (in any </code><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code style="font-size: 14px; color: rgb(51, 51, 51);"> indexName) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></pre> + +<h5 id="Parameters_3">Parameters</h5> + +<dl> + <dt>indexName</dt> + <dd>The name of the existing index to remove.</dd> + <dt>Returns</dt> + <dd>Void</dd> +</dl> + +<h5 id="Exceptions_4">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>The method was not called from a <code style="font-size: 14px;"><a href="/en-US/docs/IndexedDB/IDBTransaction#VERSION_CHANGE" title="/en-US/docs/IndexedDB/IDBTransaction#VERSION_CHANGE">versionchange</a></code> transaction mode callback.</td> + </tr> + <tr> + <td><code style="font-size: 14px;">NotFoundError</code></td> + <td>There is no index with the given name (case-sensitive) in the database.</td> + </tr> + </tbody> +</table> + +<h3 id="get">get()</h3> + +<p>Immediately returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> object, and retrieves the requested record from the object store in a separate thread. If the operation is successful, then a success event is fired on the returned object, with its <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the retrieved value, and <code><a href="/en/IndexedDB/IDBTransactionEvent#attr_transaction" title="en/IndexedDB/IDBTransactionEvent#attr transaction">transaction</a></code> set to the transaction in which this object store is opened. </p> + +<pre><a href="/en/IndexedDB/IDBRequest" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/IndexedDB/IDBRequest">IDBRequest</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> </span><a href="#get" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="#get">get</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> (in any key) raises (</span><a href="/en-US/docs/DOM/DOMException" style="font-family: 'Courier New', 'Andale Mono', monospace;" title="/en-US/docs/DOM/DOMException">DOMException</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">);</span></pre> + +<p>{{ Note("This function produces the same result if no record with the given key exists in the database as when a record exists, but with an <code>undefined</code> value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and no cursor if it does not.") }}</p> + +<h5 id="Parameters_4">Parameters</h5> + +<dl> + <dt>key</dt> + <dd>The key or key range identifying the record to retrieve. In the case of a key range, the record returned is the first record associated with the first key in the range.</dd> +</dl> + +<h5 id="Returns_5">Returns</h5> + +<dl> + <dt><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></code></dt> + <dd>A request object on which subsequent events related to this operation are fired.</dd> +</dl> + +<h5 id="Exceptions_5">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>TransactionInactiveError</td> + <td>This IDBObjectStore's transaction is inactive.</td> + </tr> + <tr> + <td>DataError</td> + <td> + <p>The key or key range provided contains and invalid key.</p> + </td> + </tr> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>The IDBObjectStore has been deleted or removed.<br> + </td> + </tr> + </tbody> +</table> + +<h3 id="index">index()</h3> + +<p>Opens the named index in this object store.</p> + +<pre><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a> <a href="#index" title="#index">index</a> (in </code><code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code style="font-size: 14px; color: rgb(51, 51, 51);"> name) raises (<a href="/en-US/docs/DOM/DOMException" style="line-height: 18px;" title="/en-US/docs/DOM/DOMException">DOMException</a>);</code></pre> + +<h5 id="Parameters_5">Parameters</h5> + +<dl> + <dt>name</dt> + <dd>The name of the index to open.</dd> +</dl> + +<h5 id="Returns_6">Returns</h5> + +<dl> + <dt><code><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a></code></dt> + <dd>An object for accessing the index.</dd> +</dl> + +<h5 id="Exceptions_6">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>The source object store has been deleted, or the transaction for the object store has finished.</td> + </tr> + <tr> + <td><code style="font-size: 14px;">NotFoundError</code></td> + <td>There is no index with the given name (case-sensitive) in the database.<br> + </td> + </tr> + </tbody> +</table> + +<h3 id="openCursor">openCursor()</h3> + +<p>Immediately returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> object, and creates a <a href="/en-US/docs/IndexedDB/IDBCursor" title="en/IndexedDB#gloss cursor">cursor</a> over the records in this object store, in a separate thread. If there is even a single record that matches the <a href="/en/IndexedDB#gloss_key_range" title="en/IndexedDB#gloss key range">key range</a>, then a success event is fired on the returned object, with its <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the <a href="/en/IndexedDB/IDBCursor" title="en/IndexedDB/IDBCursor">IDBCursor</a> object for the new cursor. If no records match the key range, then a success event is fired on the returned object, with its <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to null.</p> + +<pre><a href="/en/IndexedDB/IDBRequest" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/IndexedDB/IDBRequest">IDBRequest</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> </span><a href="#openCursor" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="#openCursor">openCursor</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> (in optional </span><a href="/en/IndexedDB/IDBKeyRange" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/IndexedDB/IDBKeyRange">IDBKeyRange</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> range, in optional unsigned short direction) raises(</span><a href="/en-US/docs/DOM/DOMException" style="font-family: 'Courier New', 'Andale Mono', monospace;" title="/en-US/docs/DOM/DOMException">DOMException</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">);</span></pre> + +<h5 id="Parameters_6">Parameters</h5> + +<dl> + <dt>range</dt> + <dd>The key range to use as the cursor's range. If this parameter is unspecified or null, then the range includes all the records in the object store.</dd> + <dt>direction</dt> + <dd>The cursor's <a href="/en-US/docs/IndexedDB/IDBCursor" title="/en-US/docs/IndexedDB/IDBCursor">direction</a>.</dd> +</dl> + +<h5 id="Returns_7">Returns</h5> + +<dl> + <dt><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></code></dt> + <dd>A request object on which subsequent events related to this operation are fired.</dd> +</dl> + +<h5 id="Exceptions_7">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>TransactionInactiveError</td> + <td>This IDBObjectStore's transaction is inactive.</td> + </tr> + <tr> + <td>DataError</td> + <td> + <p>The key or key range provided contains and invalid key.</p> + </td> + </tr> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>The IDBObjectStore has been deleted or removed.</td> + </tr> + <tr> + <td><code>TypeError</code></td> + <td>The value of the <code>direction</code> parameter is invalid.</td> + </tr> + </tbody> +</table> + +<h3 id="put">put()</h3> + +<p>Returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> object, and, in a separate thread, creates a <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#structured-clone">structured clone</a> of the <code>value</code>, and stores the cloned value in the object store. If the record is successfully stored, then a success event is fired on the returned request object with the <code><a href="/en-US/docs/IndexedDB/IDBRequest" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the key for the stored record, and <code><a href="/en-US/docs/IndexedDB/IDBRequest" title="en/IndexedDB/IDBTransactionEvent#attr transaction">transaction</a></code> set to the transaction in which this object store is opened.</p> + +<p>The put method is an<span class="database"> <em>update or insert</em> </span>method. See also the <a href="#add()">add()</a> method.</p> + +<pre><a href="/en/IndexedDB/IDBRequest" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/IndexedDB/IDBRequest">IDBRequest</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> </span><a href="#put" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="#put">put</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> (in any value, in optional any key) raises (</span><a href="/En/DOM/DOMException" style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;" title="en/DOM/DOMException">DOMException</a><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">);</span></pre> + +<h5 id="Parameters_7">Parameters</h5> + +<dl> + <dt>value</dt> + <dd>The value to be stored.</dd> + <dt>key</dt> + <dd>The key to use to identify the record. If unspecified, it results to null.</dd> +</dl> + +<h5 id="Returns_8">Returns</h5> + +<dl> + <dt>IDBRequest</dt> + <dd>A request object on which subsequent events related to this operation are fired.</dd> +</dl> + +<h5 id="Exceptions_8">Exceptions</h5> + +<p>This method may raise a <a href="/en-US/docs/DOM/DOMException" title="/en-US/docs/DOM/DOMException">DOMException</a> with a <a href="/en-US/docs/DOM/DOMError" title="/en-US/docs/DOM/DOMError">DOMError</a> of the following types:</p> + +<table class="standard-table" style="font-size: 14px;"> + <thead> + <tr> + <th scope="col">Exception</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>ReadOnlyError</td> + <td>The transaction associated with this operation is in read-only <a href="/en-US/docs/IndexedDB/IDBTransaction#mode_constants" title="/en-US/docs/IndexedDB/IDBTransaction#mode_constants">mode</a>.</td> + </tr> + <tr> + <td>TransactionInactiveError</td> + <td>This IDBObjectStore's transaction is inactive.</td> + </tr> + <tr> + <td>DataError</td> + <td> + <p>Any of the following conditions apply:</p> + + <ul> + <li>The object store uses in-line keys or has a key generator, and a key parameter was provided.</li> + <li>The object store uses out-of-line keys and has no key generator, and no key parameter was provided.</li> + <li>The object store uses in-line keys but no key generator, and the object store's key path does not yield a valid key.</li> + <li>The key parameter was provided but does not contain a valid key.</li> + </ul> + </td> + </tr> + <tr> + <td><code style="font-size: 14px;">InvalidStateError</code></td> + <td>The IDBObjectStore has been deleted or removed.</td> + </tr> + <tr> + <td><code style="font-size: 14px;">DataCloneError</code></td> + <td>The data being stored could not be cloned by the internal structured cloning algorithm.</td> + </tr> + </tbody> +</table> + +<h2 id="Example">Example</h2> + +<dl> +</dl> + +<dl> +</dl> + +<p>This example shows a variety of different uses of object stores, from updating the data structure with {{domxref("IDBObjectStore.createIndex")}} inside an <code>onupgradeneeded</code>function, to adding a new item to our object store with {{domxref("IDBObjectStore.add")}}. For a full working example, see our <a href="https://github.com/mdn/to-do-notifications/">To-do Notifications</a> app (<a href="http://mdn.github.io/to-do-notifications/">view example live</a>.)</p> + +<pre><code>// Let us open our database +var DBOpenRequest = window.indexedDB.open("toDoList", 4); + +DBOpenRequest.onsuccess = function(event) { + note.innerHTML += '<li>Database initialised.</li>'; + + // store the result of opening the database in db. + db = DBOpenRequest.result; +}; + +// This event handles the event whereby a new version of +// the database needs to be created Either one has not +// been created before, or a new version number has been +// submitted via the window.indexedDB.open line above +DBOpenRequest.onupgradeneeded = function(event) { + var db = event.target.result; + + db.onerror = function(event) { + note.innerHTML += '<li>Error loading database.</li>'; + }; + + // Create an objectStore for this database + + var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" }); + + // define what data items the objectStore will contain + + objectStore.createIndex("hours", "hours", { unique: false }); + objectStore.createIndex("minutes", "minutes", { unique: false }); + objectStore.createIndex("day", "day", { unique: false }); + objectStore.createIndex("month", "month", { unique: false }); + objectStore.createIndex("year", "year", { unique: false }); + + objectStore.createIndex("notified", "notified", { unique: false }); + + note.innerHTML += '<li>Object store created.</li>'; +}; + +// Create a new item to add in to the object store +var newItem = [ + { taskTitle: "Walk dog", hours: 19, minutes: 30, day: 24, month: 'December', year: 2013, notified: "no" } +]; + +// open a read/write db transaction, ready for adding the data +var transaction = db.transaction(["toDoList"], "readwrite"); + +// report on the success of the transaction completing, when everything is done +transaction.oncomplete = function(event) { + note.innerHTML += '<li>Transaction completed.</li>'; +}; + +transaction.onerror = function(event) { + note.innerHTML += '<li>Transaction not opened due to error. Duplicate items not allowed.</li>'; +}; + +// create an object store on the transaction +var objectStore = transaction.objectStore("toDoList"); +// make a request to add our newItem object to the object store +var objectStoreRequest = objectStore.add(newItem[0]); + +objectStoreRequest.onsuccess = function(event) { + note.innerHTML += '<li>Request successful .</li>'; +}</code></pre> + +<h2 id="Specifications">Specifications</h2> + +<table> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('IndexedDB', '#idl-def-IDBObjectStore', 'IDBObjectStore')}}</td> + <td>{{Spec2('IndexedDB')}}</td> + <td></td> + </tr> + <tr> + <td>{{SpecName("IndexedDB 2", "#object-store-interface", "IDBObjectStore")}}</td> + <td>{{Spec2("IndexedDB 2")}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2> + +<p>The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>and send us a pull request.</p> + +<p>{{Compat("api.IDBObjectStore")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB">Using IndexedDB</a></li> + <li>Starting transactions: {{domxref("IDBDatabase")}}</li> + <li>Using transactions: {{domxref("IDBTransaction")}}</li> + <li>Setting a range of keys: {{domxref("IDBKeyRange")}}</li> + <li>Retrieving and making changes to your data: {{domxref("IDBObjectStore")}}</li> + <li>Using cursors: {{domxref("IDBCursor")}}</li> + <li>Reference example: <a href="https://github.com/mdn/to-do-notifications/tree/gh-pages">To-do Notifications</a> (<a href="http://mdn.github.io/to-do-notifications/">view example live</a>.)</li> +</ul> + +<div id="compat-mobile"></div> |