Ember API 笔记-Ember.Observable

Emberjs API:http://emberjs.com/api/
继承自:Ember.Mixin
定义于:packages/ember-runtime/lib/mixins/observable.js:8
所属模块:ember-runtime

概览

该类由Ember.Mixin.create()方法创建,向Ember对象模型提供属性与属性观察功能。

属性观察者允许一个对象监测另一个对象的属性变化。在一个Ember应用中,这是模型、控制器、视图信息沟通的一种基本方法。

应用了Ember.Observable类的对象都可以使用观察者模式。包括Ember.Object在内。

通常你不会应用这个混合类到你自己的类里面,但你会经常使用到这个模块的功能,因此明白如何使用它非常重要。

使用get()和set()

由于Ember支持绑定与观察者,你应当总是使用get方法访问属性,用set方法设置属性。这会通知到观察的对象以及处理计算属性。

下面有更多关于get、set方法的文档。

观察属性更改

典型的观察属性更改方式只需要简单的添加一个observes方法到你声明的方法的结尾。例如:

Ember.Object.create({
  valueObserver: function() {
  // Executes whenever the "value" property changes
  }.observes('value')
});

除了这种常用的方式,还可以通过addObserver和removeObserver来在运行时添加、移除观察者。

为一个属性添加观察模式时,这样调用:

object.addObserver('propertyKey', targetObject, targetAction)

当属性propertyKey(第一个参数,属性名称)改变时,在targetObject(第二个参数,对像)上执行函数targetAction(第三个参数,回调函数)。

如果观察的属性是计算属性,任何依赖的属性一旦改变,即使计算属性的最终结果并未改变,观察者也会被调用。这是必要的,因为计算属性只有在调用get方法时才被计算。

继承的方法

-参阅Ember.Mixin

自有的方法

-addObserver(key, target, method)

参数:
@key--字符串,被观察的属性
@target--调用函数的对象
@method--字符串或函数,调用的方法

返回:对象自身

说明:在一个属性上添加观察。给属性注册观察者的核心方法。

一旦调用该方法,无论何时,只要key的值被设置,不管值是否真的改变,观察者将被通知。

你还可以传递一个可选的上下文参数,上下文会被传递给观察者方法。如果你多次给一个key添加同样的target/method对和不同的上下文参数,观察者将只调用一次并使用最后传递的上下文。

观察者方法

如果不传递上下文参数,那么传递的观察者方法一般是这样的(参数是自动传递):

fooDidChange: function(sender, key, value, rev);

sender是产生变化的对象。key是更改了的属性。value目前保留未使用。rev是对象更改时最后的属性版本,你可以用来检测key值是否真正改变了。

如果你传递了上下文参数,该参数应该放在rev之前:

fooDidChange: function(sender, key, value, context, rev);

通常你不需要用到value,context或rev参数。如果你不关心这些参数,完全可以不传递任何参数给观察者方法。

-beginPropertyChanges()

返回:自身

说明:开始一组属性更改。在一组属性改变时使用该方法不会发送通知,直到所有更改完成。如果你打算同时对某一对象做出大量改变,你应该在开始改变前调用beginPropertyChanges()来延迟更改的通知。当更改完成后,调用endPropertyChanges()来发送更改通知并结束延迟。

-cacheFor(keyName)

参数:
@keyName--字符串

返回:对象。计算属性的缓存值,如果有的话

说明:This allows you to inspect the value of a computed property without accidentally invoking it if it is intended to be generated lazily.

-decrementProperty(keyName, increment)

参数:
@keyName--字符串,要进行减量操作的属性名
@increment--减量值。默认为1

返回:对象。新的属性值。

说明:将属性的当前值减去指定数值。

player.decrementProperty('lives');
orc.decrementProperty('health', 5);
-endPropertyChanges()

返回:自身

说明:结束一组属性更改。参阅beginPropertyChanges方法。

-get(key)

参数:
@key--待检索的属性名称

返回:对象。属性的值或undefined

说明:检索对象的属性值。

该方法与使用object[keyName]或object.keyName类似,但它还支持计算属性,同时能处理未知属性。

你应该使用这个统一的get方法来访问各种属性。

计算属性

计算属性是在函数声明的末尾添加property方法来定义的,如:

fullName: function() {
  return this.getEach('firstName', 'lastName').compact().join(' ');
}.property('firstName', 'lastName')

当在计算属性上使用get方法时,返回的是函数调用返回的值,而不是函数本身。

未知属性

同样的,如果你尝试在未定义的属性上使用get方法,unknownProperty()方法会被调用。如果方法返回的是undefined之外的值,它将被返回。这允许你执行之前没定义过的“虚拟”属性。

-getProperties(list)

参数:
@list--一组字符串或一个数组,包含待检索的属性名

返回:哈希对

说明:传递一组字符串或一个数组来一次性获取多个属性:

record.getProperties('firstName', 'lastName', 'zipCode'); // => { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

等价于:

record.getProperties(['firstName', 'lastName', 'zipCode']); // => { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
-getWithDefault(keyName, defaultValue)

参数:
@keyName--待检索的属性名
@defaultValue--属性值未定义时返回的值

返回:对象。属性值或第二个参数的值

说明:检索属性的值,如果返回的是undefined,则用第二个参数代替。

-hasObserverFor(key)

参数:
@key--字符串。待检测的值。

返回:布尔值。

说明:如果对象在指定key上注册了观察者,返回true。

-incrementProperty(keyName, increment)

参数:
@keyName--字符串,要进行增量操作的属性名
@increment--增量值。默认为1

返回:对象。新的属性值。

说明:将属性的当前值加上指定数值。

person.incrementProperty('age');
team.incrementProperty('score', 2);
-notifyPropertyChange(keyName)

参数:
@keyName--被通知的属性名称

返回:自身

说明:代替连续调用propertyWillChange和propertyDidChange的方便方法。

-propertyDidChange(keyName)

参数:
@keyName--刚刚更改的属性名称

返回:自身

说明:通知观察者系统有属性更改了。

有时需要不通过get或set方法更改属性值,你可以使用propertyDidChange和propertyWillChange来代替。同时调用这两个方法将通知所有观察者有属性可能更改了。

注意,这两个方法必须总是配对使用。

-propertyWillChange

参阅propertyDidChange方法

-removeObserver(key, target, method)

参数:
@key--字符串。观察的属性名称
@target--调用函数的对象
@method--调用的函数

返回:观察接收者

说明:移除之前注册到对象上的观察者。传递调用addObserver时使用的参数,target对象将不再接收到通知。

-set(key, value)

参数:
@key--字符串。要设置的属性名称
@value--要设置的值或null

返回:自身

说明:将value赋给指定的key。

该方法与使用object[key]=value或object.key=value类似,但它还支持计算属性,未知属性和观察属性。

你应该使用这个统一的set方法来设置各种属性。

计算属性

当在计算属性上使用set方法时,并非简单的改变属性值,计算属性定义的函数将被调用,参数key、value将被作为参数传递。

未知属性

如果你尝试在未定义的属性上使用set方法,setUnknownProperty()方法会被调用。如果方法返回undefined,set方法将在对象上设置属性值。

观察者属性

更改属性的同时,set会注册一个属性更改给对象。除非使用了beginPropertyChanges()和endPropertyChanges(),任何“本地”观察者(比如定义观察者方法的对象)将立即被调用。任何“远程”观察者(比如定义在其他对象上的观察者方法)将被放在一个队列中并稍后调用。

链式调用

set方法除了改变了属性,还返回自身,因此可以使用链式调用:

record.set('firstName', 'Charles').set('lastName', 'Jolley');
-setProperties(hash)

参数:
@hash--要设置的键值对

返回:自身

说明:传递hash给方法来进行一次设置多个属性的操作:

record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });
-setUnknownProperty(key, value)

参数:
@key--字符串。未知属性的名称
@value--要设置的值

说明:试图设置未定义的属性时调用该方法。

-toggleProperty (keyName)

参数:
@keyName--字符串。要切换的属性名称

返回:对象。新的属性值

说明:设置一个布尔值属性为相反的值。

var obj = Ember.Object.create({
  isVisible: true
});
obj.toggleProperty('isVisible'); // isVisible === false
obj.toggleProperty('isVisible'); // isVisible === true
-unknownProperty(key)

参数:
@key--字符串。请求的未知属性

返回:对象。属性值或undefined,默认为undefined

说明:试图获取未定义的属性时调用该方法。

继承的属性

-无

自有的属性

-无

你可能感兴趣的:(Ember API 笔记-Ember.Observable)