這一節要透過一個完整的例子,帶你實作 XBL 元件。
我們來打造一個運用 XBL 的完整範例:這是一個能保存一組物件的元件,每次只顯示其中一頁。下方的導覽按鈕用來循環切換這些物件,並在一個文字元件中顯示目前的頁碼。你可以往頁面裡加入任何元素,當然最合適的還是放上一組圖片——我們就把它取名為「幻燈片」元素。
首先,我們得決定哪些元素要透過 XBL 的匿名內容來呈現。因為要實現翻頁效果,用 deck 元素作為容器再合適不過了。循環顯示的內容會在 XUL 檔中定義,而不是寫在 XBL 裡,但我們要把這些內容插入到 XBL 的 deck 中,這個操作會用到 children 元素。下方則要加上兩個按鈕,分別負責顯示上一頁與下一頁,另外還要一個文字元件(其實是一個 label)來顯示頁碼。
範例 11.8.1:原始碼
<binding id="slideshow"> <content> <xul:vbox flex="1"> <xul:deck xbl:inherits="selectedIndex" selectedIndex="0" flex="1"> <children/> </xul:deck> <xul:hbox> <xul:button xbl:inherits="label=previoustext"/> <xul:label flex="1"/> <xul:button xbl:inherits="label=nexttext"/> </xul:hbox> </xul:vbox> </content> </binding>
這個綁定建立了我們需要的幻燈片結構。許多元素都加上了 flex 特性,這樣它們就能自動排版。兩個按鈕上的 label 特性是從綁定元素繼承而來的,分別對應各自的特性 previoustext 與 nexttext,如此一來便能方便地修改按鈕上顯示的文字。與這個 XBL 綁定關聯的元素,其子元素會被顯示在 deck 元素之下。selectedIndex 同樣是從元素繼承而來的特性,讓我們能在 XUL 中設定初始顯示的頁數。
下面的 XUL 檔用來建構要顯示的結果。
<box class="slideshow" previoustext="Previous" nexttext="Next" flex="1"> <button label="Button 1"/> <checkbox label="Checkbox 2"/> <textbox/> </box>
樣式表也不能少:
.slideshow {
-moz-binding: url("slideshow.XML#slideshow");
}
第一個按鈕「Button 1」對應 deck 中的第一頁;由於我們沒有為 label 元件設定值,所以它沒有顯示任何文字——我們當然可以幫它設個值,但後面還會對它做更多操作。
接下來,我們要新增一個用來保存頁碼的屬性,它的值取自 deck 的 selectedIndex 特性,這個值正好對應目前的頁碼。同樣地,我們也能修改這個屬性,改動後它會同步更新 deck 上的 selectedIndex 特性。此外,文字元件需要在頁碼變動時即時更新。
<property name="page"
onget="return parseInt(document.getAnonymousNodes(this)[0].childNodes[0].getAttribute('selectedIndex'));"
onset="return this.setPage(val);"/>
page 屬性的值來自匿名內容陣列的第一個元素。由於第一個元素回傳的是 vbox,因此為了取得 deck,我們得再取 vbox 的第一個子元素。這裡之所以沒有用取得匿名內容的方法,是因為對 vbox 而言,deck 在 DOM 中已經是看得見的了。總之,最後我們取得了 selectedIndex 特性的值。為了修改目前的頁碼,我們需要新增一個 setPage 方法,這個方法會在後面定義。
在上一頁與下一頁兩個按鈕上,我們要加上 oncommand 事件處理器,這樣切換頁面時就能一併修改頁碼。這裡的做法很方便,因為我們只需要改動剛剛新增的 page 屬性即可:
<xul:button xbl:inherits="label=previoustext" oncommand="parentNode.parentNode.parentNode.page--;"/> <xul:description flex="1"/> <xul:button xbl:inherits="label=nexttext" oncommand="parentNode.parentNode.parentNode.page++;"/>
由於 page 屬性是在上層元素中定義的,所以我們得用 parentNode 逐層往上取得。第一個 parentNode 回傳的是 button 的父元素 hbox,第二個指向 vbox,第三個則指向最外層的 box 元素。page 屬性被遞增或遞減時,會先呼叫 onget 內的腳本來取值,對這個值做加一或減一之後,再呼叫 onset 內的腳本把值寫回去。
接著我們來定義 setPage 方法。這個方法只有一個參數,也就是要設定的頁碼。我們得先確認這個頁碼沒有超出實際範圍,然後才能把它賦給 deck 的 selectedIndex 特性與文字元件的 label 特性。
<method name="setPage">
<parameter name="newidx"/>
<body>
<![CDATA[
var thedeck=document.getAnonymousNodes(this)[0].childNodes[0];
var totalpages=this.childNodes.length;
if (newidx<0) return 0;
if (newidx>=totalpages) return totalpages;
thedeck.setAttribute("selectedIndex",newidx);
document.getAnonymousNodes(this)[0].childNodes[1].childNodes[1]
.setAttribute("value",(newidx+1)+" of "+totalpages);
return newidx;
]]>
</body>
</method>
這個函式名為 setPage,只有一個叫 newidx 的參數,方法內容被包在 CDATA 標記中。這是在 XML 檔裡嵌入程式碼又不必逐一轉義的小技巧,如此一來,你就不用把每個小於號、大於號都換成特殊編碼了。
我們一步一步來解讀這段程式碼:
var thedeck=document.getAnonymousNodes(this)[0].childNodes[0];
取得匿名內容陣列的第一個元素(也就是 vbox)的第一個子元素,對應到 deck 元素。
var totalpages=this.childNodes.length;
取得關聯的 box 底下子元素的數量,這個數值也對應到總頁數。
if (newidx<0) return 0;
如果新頁碼小於第一頁的頁碼,當然不做修改並回傳 0——畢竟第一頁前面不會有任何頁面。
if (newidx>=totalpages) return totalpages;
如果新頁碼大於最後一頁,同樣不做任何修改,直接回傳最後一頁的頁碼。合理的頁碼應該小於或等於最後一頁。
thedeck.setAttribute("selectedIndex",newidx);
修改 deck 元素上的 selectedIndex 特性,這會使畫面切換到新頁面。
document.getAnonymousNodes(this)[0].childNodes[1].childNodes[1].setAttribute( "value",(newidx+1)+" of "+totalpages);
這行程式碼把 label 元件的內容改成目前頁碼。做法是取得匿名內容陣列第一個元素(vbox)的第二個子元素(hbox),再取其第二個子元素,就能拿到 label 元素。value 特性會被設成介於 1 到 3 之間的數值。請注意這裡有一處「加一」的操作,因為索引是從 0 開始算的。
我們還需要建立一個建構子,在幻燈片剛載入時初始化 label 元素,好讓它能正常顯示。我們直接用與上一個方法類似的程式碼來設定頁碼。「this.page」會呼叫 page 屬性 onget 內的腳本,反過來也會用來初始化首頁的頁碼。
<constructor>
var totalpages=this.childNodes.length;
document.getAnonymousNodes(this)[0].childNodes[1].childNodes[1]
.setAttribute("value",(this.page+1)+" of "+totalpages);
</constructor>
我們還可以加上一些擴充功能。例如為上一頁、下一頁按鈕加上快速鍵(退格鍵與 Enter 鍵應該是個不錯的選擇),或再加兩個按鈕分別跳到第一頁與最後一頁;label 元素也可以換成文字方塊,讓使用者直接輸入要跳轉的頁碼,或換成下拉清單,直接選擇要跳轉的頁面。此外,還可以在 deck 四周加上邊框,並用 CSS 做些美化,相信這樣會更加漂亮。
下面是本節範例的完整程式碼:
範例 11.8.2:原始碼
<binding id="slideshow">
<content>
<xul:vbox flex="1">
<xul:deck xbl:inherits="selectedIndex" selectedIndex="0" flex="1">
<children/>
</xul:deck>
<xul:hbox>
<xul:button xbl:inherits="label=previoustext"
oncommand="parentNode.parentNode.parentNode.page--;"/>
<xul:description flex="1"/>
<xul:button xbl:inherits="label=nexttext"
oncommand="parentNode.parentNode.parentNode.page++;"/>
</xul:hbox>
</xul:vbox>
</content>
<implementation>
<constructor>
var totalpages=this.childNodes.length;
document.getAnonymousNodes(this)[0].childNodes[1].childNodes[1]
.setAttribute("value",(this.page+1)+" of "+totalpages);
</constructor>
<property name="page"
onget="return parseInt(
document.getAnonymousNodes(this)[0].childNodes[0].getAttribute('selectedIndex'));"
onset="return this.setPage(val);"/>
<method name="setPage">
<parameter name="newidx"/>
<body>
<![CDATA[
var thedeck=document.getAnonymousNodes(this)[0].childNodes[0];
var totalpages=this.childNodes.length;
if (newidx<0) return 0;
if (newidx>=totalpages) return totalpages;
thedeck.setAttribute("selectedIndex",newidx);
document.getAnonymousNodes(this)[0].childNodes[1].childNodes[1]
.setAttribute("value",(newidx+1)+" of "+totalpages);
return newidx;
]]>
</body>
</method>
</implementation>
</binding>