PouchDB中文API
API概述
pouchdb具有异步API，支持回调，承诺，和异步函数。对于初学者，我们建议的承诺，虽然你可以自由使用任何你喜欢的格式。如果您不确定，检查我们的异步代码指南。
大部分的接口被定义为：
db.doSomething(args..., [options], [callback])……其中的选项和回调都是可选的。
Callbacks
大部分的API定义：回调使用标准的Node.js语法：
function(error, result) { /* ... */ }如果没有错误，err就是undefined。
promise
如果不指定回调，那么API返回一个promise。 在支持的浏览器或Node.js中，使用本机promise，根据需要回退到最小库。
Create a database
new PouchDB([name], [options])此方法创建数据库或打开现有数据库。 如果您使用类似“http://domain.com/dbname”的URL，那么PouchDB将作为客户端在线的CouchDB实例。 否则它将使用任何后端存在创建本地数据库。
Options
name：您可以省略name参数，并通过选项指定它。 请注意，名称是必需的。
本地数据库的Options：
- auto_compaction：这将打开自动压缩，这意味着在每次更改数据库后调用compact（）。 默认为false。
- adapter：’idb’，’leveldb’，’websql’或’http’之一。
如果未指定，PouchDB会自动推断这一点，在支持这两种浏览器的浏览器（即Chrome，Opera和Android
4.4+）中优先使用IndexedDB到WebSQL。 - revs_limit：指定我们跟踪（不是副本）的旧版本。
指定低值意味着Pouch可能无法确定通过复制接收的新修订是否与其当前可能导致冲突的任何相关。 默认为1000。
var db = new PouchDB('dbname');
// or
var db = new PouchDB('http://localhost:5984/dbname');创建一个明确使用WebSQL的PouchDB：
var db = new PouchDB('dbname', {adapter : 'websql'});创建内存小包（必须首先安装pouchdb适配器内存）：
var db = new PouchDB('dbname', {adapter: 'memory'});Delete a database
db.destroy([options], [callback])删除数据库。 请注意，这对其他复制的数据库没有影响。
Example Usage
db.destroy().then(function (response) {
// success
}).catch(function (err) {
console.log(err);
});
//response
{
"ok" : true
}Create/update a document
Using db.put()
db.put(doc, [options], [callback])创建新文档或更新现有文档。 如果文档已存在，则必须指定其修订版本_rev，否则将发生冲突。
对文档的有效属性名称有一些限制。 如果尝试存储非JSON数据（例如Date对象），您可能会看到不一致的结果。
示例用法：
- 使用_id of’mydoc’创建一个新文档：
db.put({
_id: 'mydoc',
title: 'Heroes'
}).then(function (response) {
// handle response
}).catch(function (err) {
console.log(err);
});- 您可以使用_rev更新现有的文档：
db.get('mydoc').then(function(doc) {
return db.put({
_id: 'mydoc',
_rev: doc._rev,
title: "Let's Dance"
});
}).then(function(response) {
// handle response
}).catch(function (err) {
console.log(err);
});Example Response:
{
"ok": true,
"id": "mydoc",
"rev": "1-A6157A5EA545C99B00FF904EEF05FD9F" }响应包含文档的id，新的rev和一个确定，以确保一切都没关系。
Using db.post()
db.post(doc, [options], [callback])创建一个新文档并让PouchDB为其自动生成一个_id。
实例用法：
db.post({
title: 'Ziggy Stardust'
}).then(function (response) {
// handle response
}).catch(function (err) {
console.log(err);
});
//response
{
"ok" : true,
"id" : "8A2C3761-FFD5-4770-9B8C-38C33CED300A",
"rev" : "1-d3a8e0e5aa7c8fff0c376dac2d8a4007"
}注意：Put vs. post：基本的经验法则是：put（）新文档带有一个_id，post（）没有_id的新文档。
你应该更喜欢put（）post（），因为当你post（），你缺少一个机会使用allDocs（）来通过_id排序文档（因为你的_ids是随机的）。 有关更多信息，请阅读PouchDB专业提示。
Fetch a document
检索由docId指定的文档。
db.get(docId, [options], [callback])所有选项默认为false，除非另有说明。
- options.rev：获取文档的特定版本。 默认为获胜修订版本（参见CouchDB指南）。
- options.revs：包括文档的修订历史记录。
- options.revs_info：包括文档的修订版本及其可用性的列表。
- options.open_revs：如果open_revs
=“all”或获取在open_revs数组中指定的所有叶修订版本，则提取所有叶修订版本。 叶将按照在输入数组中指定的顺序返回。 - options.conflicts：如果指定，冲突的叶修订版将附加在_conflicts数组中。
- options.attachments：包含附件数据。
- options.binary：返回附件数据为Blobs / Buffers，而不是base64编码的字符串。
- options.ajax：要发送给ajax请求者的选项的对象。 在节点中，它们被逐字地发送以请求，除了：
options.ajax.cache：将随机字符串附加到所有HTTP GET请求的结尾，以避免它们在IE上缓存。
将此设置为true可防止发生这种情况。实例用法：
db.get('mydoc').then(function (doc) {
// handle doc
}).catch(function (err) {
console.log(err);
});
//response
{
"_id": "mydoc",
"_rev": "1-A6157A5EA545C99B00FF904EEF05FD9F"
"title": "Rock and Roll Heart",
}响应包含存储在数据库中的文档及其_id和_rev。
Delete a document
db.remove(doc, [options], [callback])
//或者
db.remove(docId, docRev, [options], [callback])删除文档。 doc必须是至少具有_id和_rev属性的文档。 发送完整的文档也会奏效。
请参阅过滤复制，了解为什么您可能希望使用put（）与{_deleted：true}。
实例用法：
db.get('mydoc').then(function(doc) {
return db.remove(doc);
}).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});
//response
{
"ok": true,
"id": "mydoc",
"rev": "2-9AF304BE281790604D1D8A4B0F4C9ADB"
}您还可以通过提供ID和rev来删除文档：
实例用法：
db.get('mydoc').then(function(doc) {
return db.remove(doc._id, doc._rev);
}).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});您也可以使用put（）与{_deleted：true}删除文档：
db.get('mydoc').then(function(doc) {
doc._deleted = true;
return db.put(doc);
}).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});Create/update a batch of documents
db.bulkDocs(docs, [options], [callback])创建，更新或删除多个文档。 docs参数是一个文档数组。
如果在给定文档上省略_id参数，数据库将创建一个新文档并为您分配ID。 要更新文档，必须同时包含_id参数和_rev参数，这些参数应与用于更新的文档的ID和版本相匹配。 最后，要删除文档，请包含值为true的_deleted参数。
实例用法：
放置一些新的文档，提供_ids：
db.bulkDocs([ {title : 'Lisa Says', _id: 'doc1'}, {title : 'Space Oddity', _id: 'doc2'} ]).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});发布一些新文档并自动生成_ids：
db.bulkDocs([
{title : 'Lisa Says'},
{title : 'Space Oddity'}
]).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});
//response
[
{
"ok": true,
"id": "doc1",
"rev": "1-84abc2a942007bee7cf55007cba56198"
},
{
"ok": true,
"id": "doc2",
"rev": "1-7b80fc50b6af7a905f368670429a757e"
}
]该响应包含来自put（）/ post（）API的熟悉的ok / rev / id数组。 如果有任何错误，它们将被单独提供，如：
[
{ status: 409,
name: 'conflict',
message: 'Document update conflict',
error: true
}
]结果以与提供的“docs”数组相同的顺序返回。
请注意，bulkDocs（）不是事务性的，并且您可以返回错误/非错误的混合数组。 在CouchDB / PouchDB中，最小的原子单位是文档。
Bulk update/delete:
您也可以使用bulkDocs（）一次更新/删除许多文档：
db.bulkDocs([
{
title : 'Lisa Says',
artist : 'Velvet Underground',
_id : "doc1",
_rev : "1-84abc2a942007bee7cf55007cba56198"
},
{
title : 'Space Oddity',
artist : 'David Bowie',
_id : "doc2",
_rev : "1-7b80fc50b6af7a905f368670429a757e"
}
]).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});
//删除
db.bulkDocs([
{
title : 'Lisa Says',
_deleted : true,
_id : "doc1",
_rev : "1-84abc2a942007bee7cf55007cba56198"
},
{
title : 'Space Oddity',
_deleted : true,
_id : "doc2",
_rev : "1-7b80fc50b6af7a905f368670429a757e"
}
]).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});注意：您还可以在options对象上指定一个new_edits属性，当设置为false时，可以从其他数据库发布现有文档。 这将不允许您编辑现有的本地文档，通常只有复制算法需要这样做。
db.allDocs({
include_docs: true,
attachments: true
}).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});
//response
{
"offset": 0,
"total_rows": 1,
"rows": [{
"doc": {
"_id": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
"_rev": "1-5782E71F1E4BF698FA3793D9D5A96393",
"title": "Sound and Vision",
"_attachments": {
"attachment/its-id": {
"content_type": "image/jpg",
"data": "R0lGODlhAQABAIAAAP7//wAAACH5BAAAAAAALAAAAAABAAEAAAICRAEAOw==",
"digest": "md5-57e396baedfe1a034590339082b9abce"
}
}
},
"id": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
"key": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
"value": {
"rev": "1-5782E71F1E4BF698FA3793D9D5A96393"
}
}]
}在回应中，您有三件事：
total_rows数据库中未删除的文档的总数
如果提供，则偏移跳过，或在CouchDB中实际偏移
rows：包含文档的行，如果没有将include_docs设置为true，则只是_id / _revs。
您可以使用startkey / endkey来查找范围内的所有文档：
db.allDocs({
include_docs: true,
attachments: true,
startkey: 'bar',
endkey: 'quux'
}).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});这将返回在’bar’和’quux’之间的所有包含_ids的文档。
前缀搜索
您可以在allDocs（）中执行前缀搜索，即“通过使用特殊的高Unicode字符”\ uffff“为我提供所有其_id以’foo’开头的文档：
db.allDocs({
include_docs: true,
attachments: true,
startkey: 'foo',
endkey: 'foo\uffff'
}).then(function (result) {
// handle result
}).catch(function (err) {
console.log(err);
});这是因为CouchDB / PouchDB _ids按字典顺序排序。
Listen to database changes
在数据库中对文档所做的更改的列表，按照它们的顺序。 它返回一个对象与方法cancel（），你调用，如果你不想再听到新的更改。
它是一个事件发射器，将在每次文档更改时发出“更改”事件，在处理所有更改时发出“完成”事件，并在发生错误时发出“错误”事件。 调用cancel（）将自动取消订阅所有事件侦听器。
db.changes(options)Options
- options.live：将为所有未来更改发出更改事件，直到取消。
- options.include_docs：包含每个更改的关联文档。
- options.conflicts：包括冲突。
- options.attachments：包含附件。
- options.binary：返回附件数据为Blobs / Buffers，而不是base64编码的字符串。
- options.descending：反转输出文档的顺序。
- options.since：在给定序列号之后立即开始更改结果。 如果您只需要新的更改（当live为true时），您也可以传递“now”。
- options.limit：将结果数限制为此数字。
- options.timeout：请求超时（以毫秒为单位），使用false禁用。
- options.heartbeat：仅适用于http适配器，服务器发出心跳保持长连接打开的时间（以毫秒为单位）。
默认为10000（10秒），使用false禁用默认值。
Filtering Options：
- options.filter：从设计文档中引用过滤器函数以选择性地获取更新。要使用视图函数，请在此处传递_view，并在options.view中提供对视图函数的引用。有关详细信息，请参阅过滤的更改。
- options.doc_ids：只显示具有这些id（字符串数组）的文档的更改。
- options.query_params：包含传递给过滤器函数的属性的对象，例如{“foo：”bar“}，其中”bar“将作为params.query.foo在过滤器函数中可用。访问params，定义你的过滤函数function（doc，params）{/
- … * /}。
- options.view：指定一个视图函数（例如’design_doc_name /
view_name’或’view_name’作为’view_name /
view_name’的缩写）作为过滤器。如果地图函数为其显示至少一个记录，则文档视为过滤器的“传递”。
注意：options.filter必须设置为“_view”才能使此选项工作。
Advanced Options:
- options.return_docs（以前的options.returnDocs）：可用于非http数据库，默认值为true。传递false防止更改订阅源将所有文档保留在内存中
- 换句话说，complete总是具有空的结果数组，而change事件是获取事件的唯一方法。适用于大变更集，否则会耗尽内存。
options.batch_size：仅适用于http数据库，这可以配置一次获取多少更改。增加这个可以减少请求的数量。默认值为25。
options.style：指定在changes数组中返回的修订版本数。默认值’main_only’将只返回当前的“获胜”修订版本;
‘all_docs’将返回所有叶修订（包括冲突和删除的前冲突）。很可能你不会需要这个，除非你正在写一个复制器。
var changes = db.changes({
since: 'now',
live: true,
include_docs: true
}).on('change', function(change) {
// handle change
}).on('complete', function(info) {
// changes() was canceled
}).on('error', function (err) {
console.log(err);
});
changes.cancel(); // whenever you want to cancel
//response
{
"id":"somestuff",
"seq":21,
"changes":[{
"rev":"1-8e6e4c0beac3ec54b27d1df75c7183a8"
}],
"doc":{
"title":"Ch-Ch-Ch-Ch-Changes",
"_id":"someDocId",
"_rev":"1-8e6e4c0beac3ec54b27d1df75c7183a8"
}
}Change events
- change (info) - 当找到更改时触发此事件。 信息将包含有关更改的详细信息，例如是否已删除以及新的_rev是什么。
如果将include_docs设置为true，Info.doc将包含该文档。 请参阅下面的响应示例。 - complete （info） - 当读取所有更改时触发此事件。 在实时更改中，只有取消事件才会触发此事件。
Info.results将包含更改列表。 见下面的例子。 - error（err） - 由于无法恢复的失败，更改Feed停止时，会触发此事件。
未完待续…………