Polymer API開發指南 (二)(翻譯)
公開 property
當你公開一個 Polymer 元素的 property 名字時,就等於把這個 property 設定為公開API了。公開 property 會有如下的特性:
- 支援宣告資料雙向繫結
- 通過宣告,property 將會按照名稱一樣的 html attribute 初始化資料
- property 的值可以反射到元素對應的attribute上
注: property 名稱是大小寫區分的,但是 attribute 卻不是。polymer 將會把 property 和 attribute 一一對應,所以你不能宣告兩個只有大小寫區別的 attribute(比如:name 和 NAME);
有兩種方法可以繫結 property :
- 將property名放在
polymer-element
元素attributes
attribute裡 - 將property名放在構造原型的
publish
裡
舉個例子,這裡一個元素,通過設定attributes
來設定三個公開的property,foo
,bar
,baz
。
<polymer-element name="x-foo" attributes="foo bar baz"> <script> Polymer(‘x-foo‘); </script> </polymer-element>
下面這個例子用到了publish
:
<polymer-element name="x-foo">
<script>
Polymer(‘x-foo‘,{
publish: {
foo: ‘I am foo!‘,bar: 5,baz: {
value: false,reflect: true
}
}
});
</script>
</polymer-element>
主要注意的是baz
使用了不同的宣告方法來開啟 attribute 反射功能。
一般來說,我們更建議使用attributes
只有以下情況,我們才建議使用publish
式宣告:
- 元素公開的property太多,把所有property名放在
attributes
會顯得有點奇怪。 - 需要設定property的初始值。
- 你需要設定attribute到property之間的反射
property 的預設值
預設情況下,在attributes
裡設定的property的值為null
。
<polymer-element name="x-foo" attributes="foo">
<script>
// x-foo 有一個名稱為 foo 的 property ,預設值為 null
Polymer(‘x-foo‘);
</script>
</polymer-element>
polymer會將foo新增到元素prototype
上,並設定為null
。
你可以通過在元素的prototype
上顯式property的預設值。
<polymer-element name="x-foo" attributes="bar">
<script>
Polymer(‘x-foo‘,{
// x-foo 有一個名稱為 bar 的 property ,預設值為 false
bar: false
});
</script>
</polymer-element>
或者可以全部移到publish
裡:
<polymer-element name="x-foo">
<script>
Polymer(‘x-foo‘,{
publish: {
bar: false
}
});
</script>
</polymer-element>
如果property的預設值為object或者array的時候,則需要放在created裡初始化,這樣就保證了在不同的例項裡值的引用都不同。
<polymer-element name="x-default" attributes="settings">
<script>
Polymer(‘x-default‘,{
created: function() {
// create a default settings object for this instance
this.settings = {
textColor: ‘blue‘;
};
}
});
</script>
</polymer-element>
通過設定 attribute 來配置元素
Attribute 為我們提供了一種簡單的方法來直接配置元素。我們可以通過設定attribute為元素提供一個初始值,從而來自定義它。
<x-foo name="Bob"></x-foo>
如果元素的property不是字串,那麼polymer會自動判斷它的型別,並將其轉換為合適的格式。
除非開啟了attribute反射,否則Attribute到property的連線是單向的,property改變並不會影響到attribute。
注:不要將資料繫結和attribute配置混淆。資料繫結是引用式的,這就意味著值並不會被序列化和反序列化。
探測property型別
Polymer會根據property的預設值,來判斷它的型別,並將相繫結的attribute轉換為此型別。
例如一個元素x-hint
有一個property名為count
,預設值為0
。
<x-hint count="7"></x-hint>
因為count
的預設值為0
,所以polymer將字串"7"
轉換成了數字7
。
如果一個property是物件或者陣列,則我們可以用JSON字串來表示它。
<x-name fullname=‘{ "first": "Bob","last": "Dobbs" }‘></x-name>
這就相當於在JS裡設定元素的propertyfullname
。
xname.fullname = { first: ‘Bob‘,last: ‘Dobbs‘ };
我們可以在publish
或者created
回撥中設定預設值。下面這個元素使用了三種方法。
<polymer-element name="hint-element" attributes="isReady items">
<script>
Polymer(‘hint-element‘,{
// hint that isReady is a Boolean
isReady: false,publish: {
// hint that count is a Number
count: 0
},created: function() {
// hint that items is an array
this.items = [];
}
});
</script>
</polymer-element>
重要:對於型別為物件或者陣列的property,應該始終在created
回撥中初始化。如果直接在構造原型上設定預設值的話,那麼在不同的例項裡就會遇到 "shared state" 錯誤。
Property 反射到 Attribute
Property的值可以反射到對應的Attribute上。例如,如果在一個元素上開啟了對name
的反射,那麼this.name="Joe"
的效果就等於 this.setAttribute(‘name‘,‘Joe‘)
,元素將會自動的更新DOM。
<x-foo name="Joe"></x-foo>
Property 反射只在某些特殊的場景有用,所以它預設是關閉的,它最常用的地方就是用attribute來控制元素的樣式。