Collections · Meteor 中文文檔

## Collections Meteor用_集合_保存數據。集合里保存的Javascript對象叫做文檔。使用`new Mongo.Collection`聲明一個集合。 ### [new Mongo.Collection(name, [options])](#/basic/Mongo-Collection) Anywhere Constructor for a Collection #### Arguments name String The name of the collection. If null, creates an unmanaged (unsynchronized) local collection. 調用`Mongo.Collection`構造函數創建一個集合對象，它的行為就像MongoDB 的集合。如果在創建集合時傳入了一個name參數，那么聲明的就是一個持久性集合 — 保存在服務端并可以發布到客戶端。要想使客戶端代碼和服務端代碼都可以通過相同的API訪問相同的集合，最好在一個客戶端和服務端都能加載到的javascript文件中把集合聲明為全局變量。示例：聲明兩個命名的，持久性的集合作為全局變量： ``` // In a JS file that's loaded on the client and the server Posts = new Mongo.Collection("posts"); Comments = new Mongo.Collection("comments"); ``` 如果傳入`null`作為name參數，那么創建出來的就是一個本地集合。本地集合不會在客戶端和服務端之間進行同步；它只是javascript對象的臨時集合，支持Mongo-style `find`, `insert`, `update`, 和 `remove`操作。默認情況下，Meteor會自動發布所有集合里的文檔到每一個連接上的客戶端。要禁用此行為，必須移除`autopublish`包： ``` $ meteor remove autopublish ``` 然后，使用[`Meteor.publish`](#meteor_publish) 和 [`Meteor.subscribe`](#meteor_subscribe)來指定集合的哪一部分發送到哪些客戶端。使用`findOne` 和 `find`從集合里檢索文檔。 ### [_collection_.findOne([selector], [options])](#/basic/Mongo-Collection-findOne) Anywhere Finds the first document that matches the selector, as ordered by sort and skip options. #### Arguments selector [Mongo Selector](#selectors), [Object ID](#mongo_object_id), or String A query describing the documents to find #### Options sort [Mongo Sort Specifier](#sortspecifiers) Sort order (default: natural order) skip Number Number of results to skip at the beginning fields [Mongo Field Specifier](#fieldspecifiers) Dictionary of fields to return or exclude. `findOne`方法可以從集合里查找特定的文檔。調用`findOne`時，通常都會傳入一個特定文檔的`_id`: ``` var post = Posts.findOne(postId); ``` 然而，也可以給`findOne`傳入一個Mongo 選擇器，Mongo選擇器是一個對象，指明了目標文檔要滿足的一系列屬性。例如，下面的選擇器 ``` var post = Posts.findOne({ createdBy: "12345", title: {$regex: /first/} }); ``` 會匹配到下面的文檔 ``` { createdBy: "12345", title: "My first post!", content: "Today was a good day." } ``` 關于MongoDB query operators 例如`$regex`, `$lt` (小于), `$text` (文本搜索)的更多信息參見[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/query/)。一個非常有用但是不那么明顯的功能就是Mongo 選擇器可以匹配數組里的元素。例如：下面的選擇器 ``` Post.findOne({ tags: "meteor" }); ``` 會匹配到下面的文檔 ``` { title: "I love Meteor", createdBy: "242135223", tags: ["meteor", "javascript", "fun"] } ``` `findOne`方法和[`Session.get`](#session_get)一樣，也是響應式的，也就是說，如果你在[template helper](#template_helpers)或是 [`Tracker.autorun`](#tracker_autorun)回調函數中使用了`findOne`，如果`findOne`返回的文檔發生了變化，那么模板就會自動重新渲染，計算會重新執行。注意，如果`findOne`沒有找到任何文檔，則返回`null`，通常發生在文檔還沒加載或是已經從集合中移除，所以要有處理`null`值的準備。 ### [_collection_.find([selector], [options])](#/basic/Mongo-Collection-find) Anywhere Find the documents in a collection that match the selector. #### Arguments selector [Mongo Selector](#selectors), [Object ID](#mongo_object_id), or String A query describing the documents to find #### Options sort [Mongo Sort Specifier](#sortspecifiers) Sort order (default: natural order) skip Number Number of results to skip at the beginning limit Number Maximum number of results to return fields [Mongo Field Specifier](#fieldspecifiers) Dictionary of fields to return or exclude. `find`方法和`findOne`類似，不同的是，它不返回單一文檔，而是返回一個MongoDB _游標_。游標是一個特殊的對象，代表一個查詢里會被返回的文檔列表。可以在模板Helper里返回游標，或是其它可以返回數組的地方： ``` Template.blog.helpers({ posts: function () { // this helper returns a cursor of // all of the posts in the collection return Posts.find(); } }); ``` ```  <template name="blog"> {{#each posts}} <h1>{{title}}</h1> <p>{{content}}</p> {{/each}} </template> ``` 要想從一個游標里檢索當前的文檔列表時，調用游標的`.fetch()`方法： ``` // get an array of posts var postsArray = Posts.find().fetch(); ``` 記住，雖然調用`fetch`的計算會在數據變化時重新運行，但是the resulting array will not be reactive if it is passed somewhere else. 通過調用`insert`,`update`, 或 `remove`來修改保存在`Mongo.Collection`里的數據。 ### [_collection_.insert(doc, [callback])](#/basic/Mongo-Collection-insert) Anywhere Insert a document in the collection. Returns its unique _id. #### Arguments doc Object The document to insert. May not yet have an _id attribute, in which case Meteor will generate one for you. callback Function Optional. If present, called with an error object as the first argument and, if no error, the _id as the second. 下面的例子展示了如何插入文檔到集合里： ``` Posts.insert({ createdBy: Meteor.userId(), createdAt: new Date(), title: "My first post!", content: "Today was a good day." }); ``` 每個`Mongo.Collection`里的每個文檔都有一個`_id`字段。它必須是唯一的，如果你沒有提供，會自動生成。[`collection.findOne`](#findOne)使用`_id`可以用來檢索特定的文檔。 ### [_collection_.update(selector, modifier, [options], [callback])](#/basic/Mongo-Collection-update) Anywhere Modify one or more documents in the collection. Returns the number of affected documents. #### Arguments selector [Mongo Selector](#selectors), [Object ID](#mongo_object_id), or String Specifies which documents to modify modifier [Mongo Modifier](#modifiers) Specifies how to modify the documents callback Function Optional. If present, called with an error object as the first argument and, if no error, the number of affected documents as the second. #### Options multi Boolean True to modify all matching documents; false to only modify one of the matching documents (the default). upsert Boolean True to insert a document if no matching documents are found. 這里的選擇器和你傳給`find`方法的是一致的，它可以匹配多個文檔。修改器是一個對象，它指明了對匹配到的文檔要做的修改。注意：除非你使用了`$set`操作符，否則`update`方法會直接用修改器替換整個匹配到的文檔。下面的例子展示了，設置所有標題包含"first"的文章的內容字段 ``` Posts.update({ title: {$regex: /first/} }, { $set: {content: "Tomorrow will be a great day."} }); ``` 關于支持的所有operators參見[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/update/)。有一點需要注意：當在客戶端調用`update`的時候，只能通過`_id`來查找文檔。要使用所有可用的選擇器，必須在服務端代碼或是 [method](#meteor_methods)中調用`update`。 ### [_collection_.remove(selector, [callback])](#/basic/Mongo-Collection-remove) Anywhere Remove documents from the collection #### Arguments selector [Mongo Selector](#selectors), [Object ID](#mongo_object_id), or String Specifies which documents to remove callback Function Optional. If present, called with an error object as its argument. `remove`方法使用和`find`、`update`一樣的選擇器，并且從數據庫中移除所有匹配到的文檔。請小心使用`remove` — 刪掉的數據沒辦法恢復。和`update`一樣，客戶端代碼只能通過`_id`移除文檔，而服務端代碼和[methods](#meteor_methods)可以使用任何選擇器移除文檔。 ### [_collection_.allow(options)](#/basic/Mongo-Collection-allow) Server Allow users to write directly to this collection from client code, subject to limitations you define. #### Options insert, update, remove Function Functions that look at a proposed modification to the database and return true if it should be allowed. 在新創建的APP中，Meteor允許任何客戶端和服務端代碼調用`insert`, `update`, 和 `remove` 。這是因為用`meteor create`創建的APP默認包含了`insecure`包，目的是簡化開發。很顯然，如果任何用戶都可以修改數據庫，這是很不安全的，所以移除`insecure`包，并聲明一些權限規則是很重要的： ``` $ meteor remove insecure ``` 一旦你移除了`insecure`包，就可以用`allow`和`deny`來控制誰可以執行哪些數據庫操作。默認情況下，客戶端所有的操作都被禁止，所以，需要添加一些`allow`規則。記住：服務端代碼和[methods](#meteor_methods) 不受`allow`和`deny`影響 — 這些規則只應用于當不可信的客戶端代碼調用`insert`, `update`, 和 `remove`時。例如，假設只有當`createBy`字段為當前用戶ID時，才允許用戶插入新文章，這樣用戶就不能冒充其他人 ``` // In a file loaded on the server (ignored on the client) Posts.allow({ insert: function (userId, post) { // can only create posts where you are the author return post.createdBy === userId; }, remove: function (userId, post) { // can only delete your own posts return post.createdBy === userId; } // since there is no update field, all updates // are automatically denied }); ``` `allow`方法接受三個回調函數：`insert`,`remove`,`update`。三個回調函數的第一個參數是登錄用戶的`_id`,其余的參數如下： 1. `insert(userId, document)` `document` 是將要插入到數據庫的文檔。如果允許插入，則返回`true`，否則返回`false` 2. `update(userId, document, fieldNames, modifier)` `document` 是將要被修改的文檔。`fieldNames`是一個數組，包含了受這次修改影響的一級字段。 `modifier`是傳給`collection.update`的第二個參數[Mongo Modifier](#mongo_modifiers)。如果使用這個回調無法實現正確的校驗，那么推薦使用[methods](#meteor_methods)。如果允許修改，則返回`true`，否則返回`false` 3. `remove(userId, document)` `document`是將要從數據庫中移除的文檔。如果允許移除則返回`true`，否則返回`false` ### [_collection_.deny(options)](#/basic/Mongo-Collection-deny) Server Override `allow` rules. #### Options insert, update, remove Function Functions that look at a proposed modification to the database and return true if it should be denied, even if an [allow](#allow) rule says otherwise. `deny`方法允許你選擇性的重寫`allow`規則。只要有一個`allow`回調函數返回`true`，就允許修改，但必須所有`deny`規則都返回false，才允許修改。例如，我們要重寫上面定義的`allow`規則：排除特定標題的文章： ``` // In a file loaded on the server (ignored on the client) Posts.deny({ insert: function (userId, post) { // Don't allow posts with a certain title return post.title === "First!"; } }); ```