Backbone.Model（模型） · Backbone.js 中文文檔 1.1.2

## Backbone.Model（模型） **Models（模型）**是任何Javascript應用的核心，包括數據交互及與其相關的大量邏輯：轉換、驗證、計算屬性和訪問控制。你可以用特定的方法擴展 **Backbone.Model**，**Model** 也提供了一組基本的管理變化的功能。下面的示例演示了如何定義一個模型，包括自定義方法、設置屬性、以及觸發該屬性變化的事件。一旦運行此代碼后，`sidebar`在瀏覽器的控制臺就可用，這樣你就可以充分發揮了。 ``` var Sidebar = Backbone.Model.extend({ promptColor: function() { var cssColor = prompt("Please enter a CSS color:"); this.set({color: cssColor}); } }); window.sidebar = new Sidebar; sidebar.on('change:color', function(model, color) { $('#sidebar').css({background: color}); }); sidebar.set({color: 'white'}); sidebar.promptColor(); ``` **extend**`Backbone.Model.extend(properties, [classProperties])` 要創建自己的 **Model** 類，你可以擴展 **Backbone.Model** 并提供實例 **properties(屬性)** ，以及可選的可以直接注冊到構造函數的**classProperties(類屬性)**。 **extend** 可以正確的設置原型鏈，因此通過 **extend** 創建的子類 (subclasses) 也可以被深度擴展。 ``` var Note = Backbone.Model.extend({ initialize: function() { ... }, author: function() { ... }, coordinates: function() { ... }, allowedToEdit: function(account) { return true; } }); var PrivateNote = Note.extend({ allowedToEdit: function(account) { return account.owns(this); } }); ``` 父類（`super`）的簡述：Javascript沒有提供一種直接調用父類的方式 — 如果你要重載原型鏈中上層定義的同名函數，如 `set`, 或 `save` ，并且你想調用父對象的實現，這時需要明確的調用它，類似這樣： ``` var Note = Backbone.Model.extend({ set: function(attributes, options) { Backbone.Model.prototype.set.apply(this, arguments); ... } }); ``` **constructor / initialize**`new Model([attributes], [options])` 當創建model實例時，可以傳入屬性 (**attributes**)初始值，這些值會被 [set](#Model-set) （設置）到 model。如果定義了 **initialize** 函數，該函數會在model創建后執行。 ``` new Book({ title: "One Thousand and One Nights", author: "Scheherazade" }); ``` 在極少數的情況下，你可能需要去重寫 **constructor** ，它可以讓你替換你的model的實際構造函數。 ``` var Library = Backbone.Model.extend({ constructor: function() { this.books = new Books(); Backbone.Model.apply(this, arguments); }, parse: function(data, options) { this.books.reset(data.books); return data.library; } }); ``` 如果你傳入`{collection: ...}` ，這個 **options**表示這個model屬于哪個`collection`，且用于計算這個model的[url](#Model-url)。否則`model.collection` 這個屬性會在你第一次添加model到一個collection的時候被自動添加。需要注意的是相反的是不正確的，因為傳遞這個選項給構造函數將不會自動添加model到集合。有時這個是很有用的。如果`{parse: true}`被作為一個**option**選項傳遞， **attributes**將在 [set](#Model-set)到model之前首先通過[parse](#Model-parse)被轉換。 **get**`model.get(attribute)` 從當前model中獲取當前屬性(attributes)值，比如： `note.get("title")` **set**`model.set(attributes, [options])` 向model設置一個或多個hash屬性(attributes)。如果任何一個屬性改變了model的狀態，在不傳入 {silent: true} 選項參數的情況下，會觸發 `"change"` 事件，更改特定屬性的事件也會觸發。可以綁定事件到某個屬性，例如：`change:title`，及 `change:content`。 ``` note.set({title: "March 20", content: "In his eyes she eclipses..."}); book.set("title", "A Scandal in Bohemia"); ``` **escape**`model.escape(attribute)` 與 [get](#Model-get) 類似，只是返回的是HTML轉義后版本的model屬性值。如果從model插入數據到HTML，使用 escape 取數據可以避免 [XSS](http://en.wikipedia.org/wiki/Cross-site_scripting) 攻擊。 ``` var hacker = new Backbone.Model({ name: "<script>alert('xss')</script>" }); alert(hacker.escape('name')); ``` **has**`model.has(attribute)` 屬性值為非 null 或非 undefined 時返回 `true`。 ``` if (note.has("title")) { ... } ``` **unset**`model.unset(attribute, [options])` 從內部屬性散列表中刪除指定屬性(attribute)。如果未設置 `silent` 選項，會觸發 `"change"` 事件。 **clear**`model.clear([options])` 從model中刪除所有屬性，包括`id`屬性。如果未設置 `silent` 選項，會觸發 `"change"` 事件。 **id**`model.id` id是model的特殊屬性，可以是任意字符串（整型 **id** 或 UUID）。在屬性中設置的 **id** 會被直接拷貝到model屬性上。我們可以從集合（collections）中通過 id 獲取model，另外 id 通常用于生成model的 URLs。 **idAttribute**`model.idAttribute` 一個model的唯一標示符，被儲存在 `id` 屬性下。如果使用一個不同的唯一的key直接和后端通信。可以設置Model的 `idAttribute` 到一個從key到 `id` 的一個透明映射中。 ``` var Meal = Backbone.Model.extend({ idAttribute: "_id" }); var cake = new Meal({ _id: 1, name: "Cake" }); alert("Cake id: " + cake.id); ``` **cid**`model.cid` model的特殊屬性，**cid** 或客戶 id 是當所有model創建時自動產生的唯一標識符。客戶 ids 在model尚未保存到服務器之前便存在，此時model可能仍不具有最終的 **id**，但已經需要在用戶界面可見。 **attributes**`model.attributes` **attributes** 屬性是包含模型狀態的內部散列表 — 通常（但不一定）JSON對象的形式表示在服務器上模型數據。它通常是數據庫中一個行的簡單的序列，但它也可以是客戶端的計算狀態。建議采用 [set](#Model-set) 更新 **attributes**而不要直接修改。 ?如果您想檢索和獲取模型屬性的副本，用 `_.clone(model.attributes)` 取而代之。由于這樣的事實： [Events（事件）](#Events)接受空格分隔事件列表，但是屬性名稱不應該包括空格。 **changed**`model.changed` **changed**屬性是一個包含所有屬性的內部散列，自最后 [set](#Model-set) 已改變。自最后一組已改變。請不要直接更新 **changed**，因為它的狀態是由[set](#Model-set)內部維護。 **changed**的副本可從[changedAttributes](#Model-changedAttributes)獲得。 **defaults**`model.defaults or model.defaults()` **defaults** 散列（或函數）用于為模型指定默認屬性。創建模型實例時，任何未指定的屬性會被設置為其默認值。 ``` var Meal = Backbone.Model.extend({ defaults: { "appetizer": "caesar salad", "entree": "ravioli", "dessert": "cheesecake" } }); alert("Dessert will be " + (new Meal).get('dessert')); ``` 需要提醒的是，在 Javascript 中，對象是按引用傳值的，因此如果包含一個對象作為默認值，它會被所有實例共享。可以定義 **defaults**為一個函數取代。 **toJSON**`model.toJSON([options])` 返回一個模型的 [attributes](#Model-attributes) 淺拷貝副本的 JSON 字符串化形式。它可用于模型的持久化、序列化，或者發送到服務之前的擴充。該方法名稱比較混亂，因為它事實上并不返回 JSON 字符串，但這是對 [JavaScript API 的 **JSON.stringify**](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON_behavior) 實現。 ``` var artist = new Backbone.Model({ firstName: "Wassily", lastName: "Kandinsky" }); artist.set({birthday: "December 16, 1866"}); alert(JSON.stringify(artist)); ``` **sync**`model.sync(method, model, [options])` 使用 [Backbone.sync](#Sync) 可以將一個模型的狀態持續發送到服務器。可以自定義行為覆蓋。 **fetch**`model.fetch([options])` 通過委托給[Backbone.sync](#Sync)從服務器重置模型的狀態。返回[jqXHR](http://www.css88.com/jqapi-1.9/jQuery.ajax/#jqXHR)。如果模型從未填充數據時非常有用，或者如果你想確保你有最新的服務器狀態。如果服務器的狀態不同于當前屬性的`"change"`事件將被觸發。接受 `success` 和 `error`回調的選項散列，這兩個回調都可以傳遞`(model, response, options)`作為參數。 ``` // 每隔 10 秒從服務器拉取數據以保持頻道模型是最新的 setInterval(function() { channel.fetch(); }, 10000); ``` **save**`model.save([attributes], [options])` 通過委托給[Backbone.sync](#Sync)，保存模型到數據庫（或替代持久化層）。如果驗證成功，返回[jqXHR](http://www.css88.com/jqapi-1.9/jQuery.ajax/#jqXHR)，否則為 `false`。 **attributes**散列（如[set](#Model-set)）應包含你想改變的屬性 - 不涉及的鍵不會被修改 - 但是，該資源的一個_完整表示_將被發送到服務器。至于`set`，你可能會傳遞單獨的鍵和值，而不是一個哈希值。如果模型有一個[validate](#Model-validate)方法，并且驗證失敗，該模型將不會被保存。如果模型[isNew](#Model-isNew)，保存將采用`"create"`（HTTP `POST`），如果模型在服務器上已經存在，保存將采用`"update"`（HTTP `PUT`）。相反，如果你只想將_改變_屬性發送到服務器，調用`model.save(attrs, {patch: true})`。你會得到一個HTTP `PATCH`請求將剛剛傳入的屬性發送到服務器。通過新的屬性調用`save` 將立即觸發一個`"change"`事件，一個`"request"`事件作為Ajax請求開始到服務器，并且當服務器確認成功修改后立即觸發一個`"sync"`事件。如果你想在模型上等待服務器設置新的屬性，請傳遞`{wait: true}`。在下面的例子中，注意我們如何覆蓋`Backbone.sync`的版本，在模型初次保存時接收到 `"create"`請求，第二次接收到 `"update"` 請求的。 ``` Backbone.sync = function(method, model) { alert(method + ": " + JSON.stringify(model)); model.set('id', 1); }; var book = new Backbone.Model({ title: "The Rough Riders", author: "Theodore Roosevelt" }); book.save(); book.save({author: "Teddy"}); ``` **save** 支持在選項散列表中傳入 `success` 和 `error` 回調函數，回調函數支持傳入 `(model, response, options)` 作為參數。如果服務端驗證失敗，返回非 `200` 的 HTTP 響應碼，將產生文本或 JSON 的錯誤內容。 ``` book.save("author", "F.D.R.", {error: function(){ ... }}); ``` **destroy**`model.destroy([options])` 通過委托給[Backbone.sync](#Sync)，保存模型到數據庫（或替代持久化層）。通過委托一個HTTP `DELETE`請求給[Backbone.sync](#Sync)破壞服務器上的模型。返回一個[jqXHR](http://www.css88.com/jqapi-1.9/jQuery.ajax/#jqXHR)對象，或者如果模型[isNew](#Model-isNew)，那么返回`false`。選項散列表中接受 `success` 和 `error` 回調函數，回調函數支持傳入 `(model, response, options)` 作為參數。在模型上觸發 `"destroy"` 事件，該事件將會冒泡到任何包含這個模型的集合中，一個`"request"`事件作為Ajax請求開始到服務器，并且當服務器確認模型被刪除后立即觸發一個`"sync"`事件。如果你想在集合中刪除這個模型前等待服務器相應，請傳遞`{wait: true}`。 ``` book.destroy({success: function(model, response) { ... }}); ``` **Underscore 方法 (6)** Backbone 代理了 **Underscore.js**用來給**Backbone.Model**提供 6 個對象函數。這里沒有完全記錄他們，但你可以看看Underscore文檔中全部詳情… (愚人碼頭注：下面鏈接已經替換成中文文檔的地址) * [keys](http://www.css88.com/doc/underscore/#keys) * [values](http://www.css88.com/doc/underscore/#values) * [pairs](http://www.css88.com/doc/underscore/#pairs) * [invert](http://www.css88.com/doc/underscore/#invert) * [pick](http://www.css88.com/doc/underscore/#pick) * [omit](http://www.css88.com/doc/underscore/#omit) ``` user.pick('first_name', 'last_name', 'email'); chapters.keys().join(', '); ``` **validate**`model.validate(attributes, options)` 這種方法是未定義的，如果您有任何可以在JavaScript中執行的代碼并且我們鼓勵你用你自定義驗證邏輯覆蓋它?。默認情況下**validate**在`save`之前調用，但如果傳遞了 `{validate:true}`，也可以在`set`之前調用。 **validate**方法是通過模型的屬性， ?選項和`set` 和 `save`是一樣的。如果屬性是有效的， **validate**不返回驗證任何東西; ?如果它們是無效的，返回一個你選擇的錯誤。它可以是一個用來顯示的簡單的字符串錯誤信息，或一個以編程方式描述錯誤的完整錯誤對象。如果**validate**返回一個錯誤， `save`不會繼續，并且在服務器上該模型的屬性將不被修改。校驗失敗將觸發`"invalid"`事件，并用此方法返回的值設置模型上的`validationError`屬性。 ``` var Chapter = Backbone.Model.extend({ validate: function(attrs, options) { if (attrs.end < attrs.start) { return "can't end before it starts"; } } }); var one = new Chapter({ title : "Chapter One: The Beginning" }); one.on("invalid", function(model, error) { alert(model.get("title") + " " + error); }); one.save({ start: 15, end: 10 }); ``` `"invalid"`事件提供粗粒度的錯誤信息在模型或集合層面上是很有用。 **validationError**`model.validationError` 用[validate](#Model-validate)最后驗證失敗時返回的值。 **isValid**`model.isValid()` 運行[validate](#Model-validate)來檢查模型狀態。 ``` var Chapter = Backbone.Model.extend({ validate: function(attrs, options) { if (attrs.end < attrs.start) { return "can't end before it starts"; } } }); var one = new Chapter({ title : "Chapter One: The Beginning" }); one.set({ start: 15, end: 10 }); if (!one.isValid()) { alert(one.get("title") + " " + one.validationError); } ``` **url**`model.url()` 返回模型資源在服務器上位置的相對 URL 。如果模型放在其它地方，可通過合理的邏輯重載該方法。生成 URLs 的默認形式為：`"/[collection.url]/[id]"`，如果模型不是集合的一部分，你可以通過指定明確的`urlRoot`覆蓋。由于是委托到 [Collection#url](#Collection-url) 來生成 URL，所以首先需要確認它是否定義過，或者所有模型共享一個通用根 URL 時，是否存在 [urlRoot](#Model-urlRoot) 屬性。例如，一個 id 為 `101` 的模型，存儲在 `url` 為 `"/documents/7/notes"` 的 [Backbone.Collection](#Collection) 中，那么該模型的 URL 為：`"/documents/7/notes/101"` **urlRoot**`model.urlRoot or model.urlRoot()` 如果使用的集合_外部_的模型，通過指定 `urlRoot` 來設置生成基于模型 id 的 URLs 的默認 [url](#Model-url) 函數。 `"[urlRoot]/id"`。通常情況下，你不會需要定義這一點。需要注意的是`urlRoot`也可以是一個函數。 ``` var Book = Backbone.Model.extend({urlRoot : '/books'}); var solaris = new Book({id: "1083-lem-solaris"}); alert(solaris.url()); ``` **parse**`model.parse(response, options)` **parse** 會在通過 [fetch](#Model-fetch) 從服務器返回模型數據，以及 [save](#Model-save) 時執行。傳入本函數的為原始 `response` 對象，并且應當返回可以 [set](#Model-set) 到模型的屬性散列表。默認實現是自動進行的，僅簡單傳入 JSON 響應。如果需要使用已存在的 API，或者更好的命名空間響應，可以重載它。如果使用的3.1版本之前的 Rails 后端，需要注意 Rails's 默認的 `to_json` 實現已經包含了命名空間之下的模型屬性。對于無縫的后端集成環境禁用這種行為： ``` ActiveRecord::Base.include_root_in_json = false ``` **clone**`model.clone()` 返回該模型的具有相同屬性的新實例。 **isNew**`model.isNew()` 模型是否已經保存到服務器。如果模型尚無 `id`，則被視為新的。 **hasChanged**`model.hasChanged([attribute])` 標識模型從上次 [set](#Model-set) 事件發生后是否改變過。如果傳入 **attribute** ，當指定屬性改變后返回 `true`。注意，本方法以及接下來 change 相關的方法，僅對 `"change"`事件發生有效。 ``` book.on("change", function() { if (book.hasChanged("title")) { ... } }); ``` **changedAttributes**`model.changedAttributes([attributes])` 只從最后一次[set](#Model-set)開始檢索已改變的模型屬性散列（hash）， ?或者如果沒有，返回 `false`。作為可選，可以傳遞外部屬性哈希（hash），返回與該模型不同的屬性的哈希（hash）。這可以用來找出視圖的哪些部分應該更新，或者確定哪些需要與服務器進行同步。 **previous**`model.previous(attribute)` 在 `"change"` 事件發生的過程中，本方法可被用于獲取已改變屬性的舊值。 ``` var bill = new Backbone.Model({ name: "Bill Smith" }); bill.on("change:name", function(model, name) { alert("Changed name from " + bill.previous("name") + " to " + name); }); bill.set({name : "Bill Jones"}); ``` **previousAttributes**`model.previousAttributes()` 返回模型的上一個屬性的副本。一般用于獲取模型的不同版本之間的區別，或者當發生錯誤時回滾模型狀態。