【轉】Polymer API開發指南 (二)（翻譯）

標籤：blog   http   io   color   ar   使用   java   for   sp   

原文轉自：http://segmentfault.com/blog/windwhinny/1190000000596258

公開 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，因為這是聲明式的，而且開發人員可以很容易的通過元素標籤來看到所有元素暴露出來的API。

只有以下情況，我們才建議使用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來控制元素的樣式。

待續...

【轉】Polymer API開發指南 (二)（翻譯）