Ember Namespace

Emberjs API：http://emberjs.com/api/
定義于：packages/ember-metal/lib/core.js:8
所屬模塊：ember-metal

說明：所有Ember方法與函數(shù)都定義在這個命名空間里忆嗜。Ember可以用Em縮寫代替。Ember-Runtime是一個提供Ember核心功能的框架弧关，包括跨平臺功能匆帚、屬性觀察、對象等累榜【笔可配合其他跨平臺js庫一起使用章母，如jQuery存哲。
核心框架Runtime基于jQuery API因宇，并做了一些性能優(yōu)化。

繼承的方法
-無
自有的方法

-$

說明：jQuery的別名祟偷。
-A(arr)

參數(shù)：
@arr--類數(shù)組

返回：Ember.NativeArray

說明：從一個類數(shù)組對象創(chuàng)建一個本地的Ember.NativeArray察滑。不會修改原始對象。

-addListener(obj, eventName, targetOrMethod, method)

參數(shù)：
@obj--對象
@eventName--字符串修肠。事件名
@targetOrMethod--目標對象或函數(shù)
@method--函數(shù)或字符串杭棵。要在目標對象上調(diào)用的函數(shù)或函數(shù)名

說明：添加一個事件監(jiān)聽器。

-alias(methodName)

參數(shù)：
@methodName--字符串氛赐。方法或?qū)傩缘拿?/p>

返回：Ember.Descriptor

說明：使一個屬性或方法可以通過額外的名字訪問。

App.PaintSample = Ember.Object.extend({
  color: 'red',
  colour: Ember.alias('color'),
  name: function(){
    return "Zed";
  },
  moniker: Ember.alias("name")
});
var paintSample = App.PaintSample.create()
paintSample.get('colour'); //=> 'red'
paintSample.moniker(); //=> 'Zed'

-assert(desc, test)

參數(shù)：
@desc--字符串先舷。用于斷言失敗時拋出異常的描述
@test--布爾值艰管。一個用于斷言的表達式，為真時跳過斷言蒋川。如果是假牲芋，將拋出異常

說明：定義一個斷言，當條件不匹配時（test結(jié)果是false），拋出異常缸浦，異常信息為desc夕冲。使用用于生產(chǎn)環(huán)境的版本時，Ember構(gòu)建工具將屏蔽該方法裂逐。

// Test for truthiness
Ember.assert('Must pass a valid object', obj);
// Fail unconditionally
Ember.assert('This code path should never be run')

-beforeObserver(func, propertyNames)

參數(shù)：
@func--函數(shù)
@propertyNames--字符串

返回：func

說明：無相關(guān)信息歹鱼，Ember中的源代碼如下

Ember.beforeObserver = function(func) {
  var paths = a_slice.call(arguments, 1);
  func.__ember_observesBefore__ = paths;
  return func;
};

-bind(obj, to, from)

參數(shù)：
@obj--根對象
@to--字符串。與obj相關(guān)的目標路徑
@from--字符串卜高。來源路徑弥姻，與obj相關(guān)的路徑或全局路徑

返回：Ember.Bingding實例

說明：創(chuàng)建新綁定的全局方法。傳遞根對象與目標和來源路徑來創(chuàng)建和連接綁定掺涛。

Ember中的源碼如下

Ember.bind = function(obj, to, from) {
  return new Ember.Binding(to, from).connect(obj);
};

-cacheFor(obj, key)

參數(shù)：
@obj--待檢查的對象
@key--字符串庭敦。要返回緩存值的屬性名

返回：緩存的屬性值，如果有

說明：如果存在薪缆，返回屬性的緩存值秧廉。對于查看計算屬性會有用。

-canInvoke(obj, methodName)

參數(shù)：
@obj--待檢查的對象
@method--待檢查的方法名

返回：布爾值

說明：檢查method是否存在obj上拣帽。

-compare(v, w)

參數(shù)：
@v--第一個比較對象
@w--第二個比較對象

返回：如果v<w疼电，返回-1；如果v=w诞外，返回0澜沟；如果v>w，返回1

說明：比較兩個javascript值峡谊。如果類型不同茫虽，比較的順序是基于Ember.ORDER_DEFINITION計算的。

Ember.compare('hello', 'hello'); // 0
Ember.compare('abc', 'dfg'); // -1
Ember.compare(2, 1); // 1

-computed(func)

參數(shù)：
@func--計算屬性的計算函數(shù)

返回：Ember.ComputedProperty實例

說明：這個輔助函數(shù)返回一個新的屬性描述符既们，包裝傳入的計算屬性函數(shù)濒析。您可以使用這個輔助函數(shù)或通過Ember.defineProperty()來定義混合屬性。

傳遞的函數(shù)將被用來獲取和設置屬性值啥纸。該函數(shù)接受兩個參數(shù)号杏，鍵和值。如果值是未定義的斯棒，你應該先設定值盾致。在任一情況下，返回屬性的當前值荣暮。

-computed.bool(dependentKey)

參數(shù)：
@dependentKey--字符串

說明：暫無

-computed.empty(dependentKey)

參數(shù)：
@dependentKey--字符串

說明：暫無

-computed.not(dependentKey)

參數(shù)：
@dependentKey--字符串

說明：暫無

-copy(object, deep)

參數(shù)：
@object--被克隆的對象
@deep--布爾值庭惜。true表示使用深度拷貝

返回：克隆的新對象

說明：創(chuàng)建傳遞參數(shù)對象的一個拷貝。此功能可以拷貝任何類型的對象穗酥，包括原始值（實際上并沒有克隆护赊，因為它們是不可變的）惠遏。

如果傳遞的參數(shù)對象本身有clone()（必須是繼承自Ember.Copyable）方法，則執(zhí)行該方法并返回結(jié)果骏啰。

-create()

說明：相當于Object.create()节吮，如果本身不可實現(xiàn)。

-deprecate(message, test)

參數(shù)：
@message--字符串
@test--布爾值

說明：顯示警告判耕，包含提供的message和堆棧信息透绩。使用用于生產(chǎn)環(huán)境的版本時，Ember構(gòu)建工具將屏蔽該方法祈秕。

-deprecateFunc(message, func)

參數(shù)：
@message--字符串
@func--函數(shù)

說明：當包裝函數(shù)被調(diào)用時渺贤，顯示警告，包含提供的message和堆棧信息请毛。

-destroy(obj)

參數(shù)：
@obj--待銷毀的對象

說明：刪除對象元信息志鞍，該對象將被回收。多次調(diào)用不會產(chǎn)生副作用方仿。

-empty(obj)

參數(shù)：
@obj--待檢測的對象

返回：布爾值

說明：驗證參數(shù)是否null或一個空的string固棚、array。

Ember.empty(); => true
Ember.empty(null); => true
Ember.empty(undefined); => true
Ember.empty(''); => true
Ember.empty([]); => true
Ember.empty('tobias fünke'); => false
Ember.empty([0,1,2]); => false
Ember.empty({});     => false

-get(obj, keyName)

參數(shù)：
@obj--待檢索的對象
keyName--檢索的屬性名

返回：屬性值或null

說明：獲取對象上的屬性仙蚜。如果時計算屬性此洲，計算函數(shù)將被調(diào)用。如果屬性未定義委粉，執(zhí)行unknownProperty()方法呜师。

在IE8或以前的瀏覽器，你應該使用該方法來檢索對象屬性贾节。

如果對象為null汁汗，該方法返回undefined。

-immediateObserver(func, propertyNames)

參數(shù)：
@func--函數(shù)
@propertyName--字符串

返回：func

-inspect(obj)

參數(shù)：
@obj--待審查的對象

返回：字符串栗涂。被審查對象的描述

說明：審查對象的便捷方法知牌。該方法將嘗試轉(zhuǎn)換對象為有用的描述語。

Ember.inspect( Ember.Object.create({
  firstName: 'Hansi',
  lastName: 'Hinterseer',
  age: 58
})); 
//"{firstName: Hansi , lastName: Hinterseer , age: 58}"

-isArray(obj)

參數(shù)：
@obj--待檢測的對象

返回：布爾值

說明：如果傳遞的參數(shù)是數(shù)組或類數(shù)組斤程，返回true角寸。

Ember中判斷Array的規(guī)則：

對象擁有一個objectAt屬性
對象是本地數(shù)組
對象是一個Obejct，且有一個length屬性

不像Ember.typeOf忿墅，即使傳遞的參數(shù)不是正規(guī)數(shù)組扁藕，只要是類數(shù)組（比如Ember.Array實現(xiàn)的數(shù)組），這個方法就會返回true疚脐。

Ember.isArray(); // false
Ember.isArray([]); // true
Ember.isArray( Ember.ArrayProxy.create({ content: [] }) ); // true

-isEqual(a, b)

參數(shù)：
@a--第一個比較對象
@b--第二個比較對象

返回：布爾值

說明：比較兩個對象亿柑，如果他們邏輯上相等，返回true亮曹。相比===全等比較符橄杨，該方法采用深度比較。它會比較內(nèi)部的對象照卦。如果兩個比較對象中式矫，任意一個含有isEuqal()的對象，直接調(diào)用該方法并返回結(jié)果役耕，不進行比較采转。對于數(shù)組不進行比較，因為對數(shù)組進行比較耗費的資源太大瞬痘，即使數(shù)組相同故慈，也返回false。

Ember.isEqual('hello', 'hello'); => true
Ember.isEqual(1, 2); => false
Ember.isEqual([4,2], [4,2]); => false

-K

返回：this

說明：簡單的返回自身框全。某些情況下會有用察绷。在模板中使用{{action}}并分配一個Ember.K方法給它，可以避免開發(fā)過程中津辩，指定的目標對象不能處理動作時拋出異常的麻煩拆撼。

Ember.View.create({
  templateName: 'menu',
  home: Ember.K,
  profile: Ember.K,
  links: Ember.K
});

<ul>
  <li {{action "home"}} >Home</li>
  <li {{action "profile"}} >Profile</li>
  <li {{action "links"}} >Links</li>
</ul>

-keys(obj)

參數(shù)：
@obj--對象

返回：對象鍵組成的數(shù)組

說明：返回所有對象或哈希表上定義的鍵。調(diào)試時審查對象會有用喘沿。

var obj = Ember.Object.create({
  firstName: 'Hansi',
  lastName: 'Hinterseer',
  age: 58
})
Ember.keys(obj);    //["firstName", "lastName", "age"]

-makeArray(obj)

參數(shù)：
@obj--要轉(zhuǎn)換為數(shù)組的對象

返回：數(shù)組

說明：將傳遞的參數(shù)轉(zhuǎn)換成數(shù)組闸度，但不改變原對象。如果參數(shù)對象以及是數(shù)組蚜印，則返回該對象莺禁。否則將添加該參數(shù)對象到一個數(shù)組。如果參數(shù)是null或undefined窄赋，返回空數(shù)組哟冬。

Ember.makeArray(); => []
Ember.makeArray(null); => []
Ember.makeArray(undefined); => []
Ember.makeArray('lindsay'); => ['lindsay']
Ember.makeArray([1,2,42]); => [1,2,42]
var controller = Ember.ArrayProxy.create({ content: [] });
Ember.makeArray(controller) === controller; => true

-mixin(obj, mixins)

參數(shù)：
@obj--對象
@mixins--混合類

返回：obj

-none(obj)

參數(shù)：
@obj--待檢測的對象

返回：布爾值

說明：如果傳遞的參數(shù)是null或undefined，返回true寝凌。當使用==時會在JSLint測試中出現(xiàn)錯誤柒傻，可以用該方法代替來避免。

Ember.none(); => true
Ember.none(null); => true
Ember.none(undefined); => true
Ember.none(''); => false
Ember.none([]); => false
Ember.none(function(){}); => false

-observer(func, propertyNames)

參數(shù)：
@func--函數(shù)较木。屬性更改時調(diào)用
@propertyNames--字符串红符。要觀察的屬性名

返回：func

說明：添加屬性觀察者。

var obj = Ember.Object.create({
  num:'1',
  change:Em.observer(function(){
  console.log('num change to '+this.num);
  },'num')
});
obj.set('num','2'); => num change to 2

-onLoad(name, callback)

參數(shù)：
@name--掛鉤名稱
@callback--回調(diào)函數(shù)

-oneWay(obj, to, from)

參數(shù)：
@obj--根對象
@to--字符串伐债。與obj相關(guān)的目標路徑
@from--字符串预侯。來源路徑，與obj相關(guān)的路徑或全局路徑

返回：Ember.Binding實例

說明：創(chuàng)建單向綁定的全局方法峰锁。

Ember中的源碼如下

Ember.oneWay = function(obj, to, from) {
  return new Ember.Binding(to, from).oneWay().connect(obj);
};

-propertyDidChange(obj, keyName)

參數(shù)：
@obj--屬性已經(jīng)更改的對象
@keyName--已經(jīng)更改的屬性名（或路徑）

說明：當屬性更改后調(diào)用萎馅。它會通知任何觀察者并清除緩存。

一般不需要直接去調(diào)用該方法虹蒋，但如果因為某些原因不能直接監(jiān)控某個屬性糜芳，你可以手動調(diào)用飒货，在屬性值更改之前需調(diào)用Ember.propertyWillChange()。

-propertyWillChange(obj, keyName)

參數(shù)：
@obj--屬性即將更改的對象
@keyName--即將更改的屬性名（或路徑）

說明：當屬性更改前調(diào)用峭竣。它會通知任何觀察者并準備緩存塘辅。

一般不需要直接去調(diào)用該方法，但如果因為某些原因不能直接監(jiān)控某個屬性皆撩，你可以手動調(diào)用扣墩，在屬性值更改之后需調(diào)用Ember.propertyDidChange()。

-removeListener(obj, eventName, targetOrMethod, method)

參數(shù)：
@obj--調(diào)用方法的對象
@eventName--事件名
@targetOrMethod--目標對象或方法
@method--方法或方法名

說明：移除一個事件監(jiān)聽者扛吞。參數(shù)必須與傳遞給Ember.addListener的參數(shù)相匹配呻惕。

-renderBuffer(tagName)

參數(shù)：
@targetName--字符串

返回：Ember.RenderBuffer

說明：用傳遞的tagName創(chuàng)建新的renderBuffer±谋龋可以覆蓋此方法來進一步定制亚脆，一般不需要調(diào)用或覆寫。

-required()

返回：REQUIRED

說明：Denotes a required property for a mixin

-runLoadHooks(name, object)

參數(shù)：
@name--掛鉤名
@object--傳遞給回調(diào)函數(shù)的對象

-sendEvent(obj, eventName, params)

參數(shù)：
@obj--對象
@eventName--事件名
@params--數(shù)組

返回：true

-set(obj, keyName, value)

參數(shù)：
@obj--要修改的對象
@keyName--要修改的屬性名
@value--要設置的值

返回：對象守呜。傳遞的值

說明：在對象上設置屬性值型酥。對于為定義的屬性，調(diào)用unknownProperty()查乒。

在IE8或以前的瀏覽器弥喉，你應該使用該方法來設置對象屬性。

-tryInvoke(obj, methodName, args)

參數(shù)：
@obj--檢查的對象
@methodName--字符串玛迄。檢查的方法名
@args--數(shù)組由境。傳遞給methodName的參數(shù)

返回：methodName返回的值或undefined

說明：檢查obj是否存在methodName方法，如果有蓖议，調(diào)用它虏杰，并傳遞args作為參數(shù)。

-trySet(obj, keyName, value)

參數(shù)：
@obj--要修改的對象
@keyName--要設置的屬性
@value--要設置的值

說明：Ember.set的容錯形式勒虾。主要用于同步綁定時嘗試更新一個銷毀的對象纺阔。

-typeOf(item)

參數(shù)：
@item--待檢測的對象

返回：字符串。對象的類型

說明：返回參數(shù)對象的類型修然。使用此方法代替內(nèi)建的typeof方法來獲取對象的類型笛钝。它在所有瀏覽器都返回同樣結(jié)果，并且包含更多細節(jié)愕宋。

示例

Ember.typeOf(); => 'undefined'
Ember.typeOf(null); => 'null'
Ember.typeOf(undefined); => 'undefined'
Ember.typeOf('michael'); => 'string'
Ember.typeOf(101); => 'number'
Ember.typeOf(true); => 'boolean'
Ember.typeOf(Ember.makeArray); => 'function'
Ember.typeOf([1,2,90]); => 'array'
Ember.typeOf(Ember.Object.extend()); => 'class'
Ember.typeOf(Ember.Object.create()); => 'instance'
Ember.typeOf(new Error('teamocil')); => 'error'
// "normal" JavaScript object
Ember.typeOf({a: 'b'}); => 'object'

-warn(message, test)

參數(shù)：
@message--字符串玻靡。警告信息內(nèi)容
@test--布爾值≈斜矗可選囤捻。如果為假，警告信息將顯示

說明：顯示警告信息message邻寿。使用用于生產(chǎn)環(huán)境的版本時蝎土，Ember構(gòu)建工具將屏蔽該方法视哑。

Ember.warn('Ah, we have a problem!', Ember.isEqual([1,2],[1,2]))
=> WARNING: Ah, we have a problem!

繼承的屬性
-無
自有的屬性

-ENV

說明：標準環(huán)境變量。在加載Ember之前誊涯，定義全局ENV變量來控制各種配置設置黎炉。屬性值為哈希表。

-EXTEND_PROTOTYPES

默認值：true

說明：用于決定是否增強javascript內(nèi)建原型來提供更友好的API醋拧。如果開啟，一些方法將添加到包裝對象Function淀弹、String丹壕、Array上，Object.prototype不會得到增強薇溃，以避免麻煩菌赖。

在一般情況下我們建議保留此選項設置為true，因為它很少與其他代碼沖突沐序。如果您需要將其關(guān)閉琉用，你可以定義ENV.EXTEND_PROTOTYPES配置來禁用它。

-LOG_BINDINGS

默認值：false

說明：開啟時策幼，將在控制臺輸出所有觸發(fā)綁定更改的信息邑时。在產(chǎn)品代碼中應禁用√亟悖可以在控制臺臨時開啟晶丘。

Ember.LOG_BINDINGS = true;
App = Ember.Application.create();
App.controller = Ember.Object.create({
  name: 'Nellie'
});
App.boundController = Ember.Object.create({
  nameBinding: 'App.controller.name'
});
App.boundController.set('name', 'Tobias');
> Begin: Flush Sync Queue 
> Ember.Binding<ember116>(App.controller.name -> name) <- Tobias {name: "Tobias", nameBinding: f}
> End: Flush Sync Queue

-LOG_STACKTRACE_ON_DEPRECATION

默認值：true

說明：決定當出現(xiàn)警告信息時是否在控制臺輸出完整的堆棧信息。

-SHIM_ES5

默認值：Ember.EXTEND_PROTOTYPES

說明：決定是否為舊瀏覽器添加ECMAScript 5 shims[shims主要目的是解決HTML5元素在舊IE下的樣式問題]

-STRINGS

說明：屬性值為哈希表唐含。定義當前語言本地化字符串哈希表浅浮。通過Ember.String.loc()使用。參閱loc()捷枯。

-TEMPLATES

說明：全局共享模板哈希表滚秩。你可以將Handlebars模板存放在獨立文件，在生成時構(gòu)建工具會自動將模板加載到JavaScript淮捆。

-VERSION

默認值：'1.0.0-pre.2'

說明：版本號郁油，常量。

-parentView

默認值：null

說明：如果視圖當前已插入到DOM中的一個父視圖争剿，這個屬性將指向該父視圖已艰。

事件

-onerror(error)

參數(shù)：
@error--錯誤事件對象

說明：分配一個函數(shù)給Ember.onerror，當Ember內(nèi)部遇到錯誤時執(zhí)行該函數(shù)蚕苇。