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，由於這是聲明式的，並且開發者能夠很容易的經過元素標籤來看到全部元素暴露出來的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來控制元素的樣式。

待續...