快速入門:新增 WinJS 控制項與樣式 (HTML)

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App,請參閱 最新文件 ]

Windows Library for JavaScript (WinJS) 提供了高品質基礎結構,例如網頁控制項、承諾與資料繫結;優美的 UI 功能,例如虛擬化集合;以及高效能 Windows 控制項,例如 ListViewFlipViewSemanticZoom

您可以在 Windows 執行階段應用程式與網站中,以及在使用以 HTML 為基礎的應用程式技術 (像是 Apache Cordova) 時使用 WinJS。

如需了解此功能的運作情形,請參閱應用程式功能,從開始到完成系列:Windows 市集應用程式 UI,從開始到完成

先決條件

什麼是適用於 JavaScript 的 Windows Library?

WinJS 是 CSS 和 JavaScript 檔案的程式庫。它包含組織成命名空間,並為了讓開發美觀的應用程式變得更輕鬆所設計的 JavaScript 物件。 WinJS 包含可協助您處理啟用、存取存放區以及定義您自己的類別與命名空間的物件。

將適用於 JavaScript 的 Windows Library 新增到頁面

如果要在您的應用程式或網站中使用最新版的 WinJS:

  1. 取得 WinJS 下載最新版,並複製到您應用程式或網站的目錄中。
  2. 將 WinJS CSS 與指令碼參考新增到您使用 WinJS 功能之應用程式或網站的各個頁面。

這個範例會顯示應用程式 (其 WinJS 檔案位於其根目錄中) 的這些參考看起來的樣子。

    <!-- WinJS style sheets (include one) -->
    <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
    <link href="/WinJS/css/ui-light.css" rel="stylesheet">

    <!-- WinJS code -->
    <script src="/WinJS/js/WinJS.js"></script>

在標記中新增 WinJS 控制項

和 HTML 控制項不同,WinJS 控制項沒有專用的標記元素;例如,您無法透過加入 <rating /> 元素建立 Rating 控制項。若要新增 WinJS 控制項,要建立 div 元素,並使用 data-win-control 屬性指定所需的控制項類型。若要新增 Rating 控制項,您要將屬性設定為 "WinJS.UI.Rating"。

您也必須呼叫 JavaScript 程式碼中的 WinJS.UI.processAll 函式。WinJS.UI.processAll 會剖析您的標記,並具現化所找到的任何 WinJS 控制項。

下一組範例會示範如何將 WinJS 控制項新增到使用 [空白的應用程式] 範本建立的專案。如果您建立新的 [空白的應用程式] 專案,比較容易依循。

Hh465493.wedge(zh-tw,WIN.10).gif使用 [空白的應用程式] 範本建立新的專案

  1. 啟動 Microsoft Visual Studio。

  2. 在 [起始頁] 索引標籤,按一下 [新增專案]****。隨即開啟 [新增專案] 對話方塊。

  3. 在 [已安裝的]**** 窗格中,展開 [JavaScript],然後按一下 [Windows 市集應用程式]**** 範本類型。適用於 JavaScript 的可用專案範本會顯示在對話方塊的中央窗格中。

  4. 在中央窗格中,選取 [空白的應用程式] 專案範本。

  5. 在 [名稱]**** 文字方塊中,輸入專案的名稱。

  6. 按一下 [確定] 來建立專案。這可能要花一點時間。

Hh465493.wedge(zh-tw,WIN.10).gif新增 WinJS 控制項

  1. 建立您要放置控制項的 div 元素。將其 data-win-control 屬性設定為您要建立之控制項的完整名稱。此範例會在應用程式的起始頁 (default.html 檔案) 上建立 Rating 控制項。

    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8">
        <title>Adding WinJS controls and styles</title>
    
        <!-- WinJS references -->
        <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
        <script src="/WinJS/js/WinJS.js"></script>
    
        <!-- AddingWinJSControlsAndStyles references -->
        <link href="/css/default.css" rel="stylesheet">
        <script src="/js/default.js"></script>
    </head>
    <body>
    
        <p>Create a WinJS control in markup</p>
    
        <div id="ratingControlHost" data-win-control="WinJS.UI.Rating">
        </div>
    
    </body>
    </html>
    
  2. 您的 JavaScript 程式碼必須呼叫 WinJS.UI.processAll 才能初始化您在上一個步驟中建立的 Rating 控制項。 如果使用 [空白的應用程式] 範本,您的 default.js 檔案已包含一個 WinJS.UI.processAll 的呼叫:

    (function () {
        "use strict";
    
        var app = WinJS.Application;
        var activation = Windows.ApplicationModel.Activation;
        WinJS.strictProcessing();
    
        app.onactivated = function (args) {
            if (args.detail.kind === activation.ActivationKind.launch) {
                if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                    // TODO: This application has been newly launched. Initialize
                    // your application here.
                } else {
                    // TODO: This application has been reactivated from suspension.
                    // Restore application state here.
                }
                args.setPromise(WinJS.UI.processAll());
            }
        };
    
        app.oncheckpoint = function (args) {
            // TODO: This application is about to be suspended. Save any state
            // that needs to persist across suspensions here. You might use the
            // WinJS.Application.sessionState object, which is automatically
            // saved and restored across suspension. If you need to complete an
            // asynchronous operation before your application is suspended, call
            // args.setPromise().
        };
    
        app.start();
    })();
    

    如果不是使用 [空白的應用程式] 範本,或者是將控制項新增到自行建立的頁面,您可能需要新增 WinJS.UI.processAll 的呼叫。

    • 如果您將控制項新增到應用程式的首頁 (通常是 default.html 檔案),請在 onactivated 事件處理常式中新增 WinJS.UI.processAll 的呼叫,如上一個範例所示。

    • 如果您將控制項新增到頁面控制項,因為頁面控制項會自動新增 WinJS.UI.processAll 的呼叫,所以您不需要進行這個動作。

    • 如果您將控制項新增到應用程式首頁之外的其他頁面,請處理 DOMContentLoaded 事件,並使用處理常式呼叫 WinJS.UI.processAll

      function initialize() {
          WinJS.UI.processAll();
      }
      
      document.addEventListener("DOMContentLoaded", initialize(), false);
      

    WinJS.UI.processAll 函式會處理文件,並啟用您在標記中宣告的任何 WinJS 控制項。

當您執行應用程式時,Rating 控制項會出現在您放置 div 主機元素的位置。

評等控制項

在標記中設定 WinJS 控制項的屬性

當您建立 HTML 控制項時,可以使用專用的屬性設定其內容。例如,若要設定 input 控制項的 typemin 以及 max 內容,可以在標記中設定 typeminmax 屬性。

<input type="range" min="0" max="20" />

和 HTML 控制項不同,WinJS 控制項沒有專用的元素或屬性標記;例如,您無法使用這個標記建立 Rating 控制項和設定其內容:

<!-- Not valid markup. -->
<rating maxRating="10" averageRating="6" />

必須改用 data-win-options 屬性設定標記中的內容。它會採用包含一或多個屬性/值配對的字串:

data-win-options="{propertyName: propertyValue}"

 

這個範例會將 Rating 控制項的 maxRating 設定為 10。

<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 10}">
</div>

當您執行應用程式時,Rating 控制項看起來就像這樣:

評等控制項會顯示 10 顆星的評等系統。

若要設定多個屬性,請以逗號加以分隔:

data-win-options="property1Name: property1Value, property2Name: property2Value"

 

下一個範例會設定 Rating 控制項的兩個屬性。

<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 10, averageRating: 6}">
</div>

當您執行應用程式時,Rating 控制項現在看起來就像這樣:

評等控制項顯示 10 顆星中的 6 顆星評等。

如果屬性值本身是字串,請在該字串加上不同於您用來設定 data-win-options 屬性的引號類型 (' 或 ")。這個範例顯示如何設定採用字串之 TimePicker 控制項的 current 屬性:

<div id="timepicker" data-win-control="WinJS.UI.TimePicker" 
    data-win-options="{current: '10:29 am'}">
</div>

時間顯示為 10:29 AM 的 TimePicker 控制項。

若要了解指定的 WinJS 控制項是否支援某個屬性,請參閱其參考頁面

擷取您在標記中建立的控制項

您也可以使用程式設計的方式,設定 WinJS 控制項的屬性。若要存取程式碼中的控制項,請抓取主機元素,然後使用其 winControl 屬性抓取該控制項。 在上一個範例中,Rating 控制項的主機元素為 "ratingControlHost"。


var control = document.getElementById("ratingControlHost").winControl; 

在某些情況下,您可能想要在控制項可用時就抓取並操作該控制項。請注意,WinJS.UI.processAll 方法是非同步的,因此,遵循該方法的程式碼可能會在 WinJS.UI.processAll 完成之前執行。假設如此,請勿立即嘗試操作控制項,因為該控制項可能無法使用:


WinJS.UI.processAll();

// Don't do this:
var control = document.getElementById("ratingControlHost").winControl; 
control.averageRating = 3; 
            

WinJS.UI.processAll 會傳回 WinJS.Promise 物件,當 WinJS.UI.processAll 方法完成時,您可以使用這個物件呼叫函式。 這個範例會定義一個抓取控制項的完成函式,並將其 averageRating 設定為 3。


// Do this instead:
WinJS.UI.processAll().then(function () {
    var control = document.getElementById("ratingControlHost").winControl;
    control.averageRating = 3; 
});

下一節描述如何將事件接聽程式新增到 WinJS 控制項。

處理 WinJS 控制項的事件

如同使用 HTML 控制項,通常會使用 addEventListener 函式附加 WinJS 控制項的事件接聽程式。不過,抓取 WinJS 控制項與抓取 HTML 控制項稍有不同。

處理事件:

  1. 在 JavaScript 中,抓取控制項的主機元素,並使用其 winControl 屬性抓取該控制項。
  2. 呼叫控制項的 addEventListener 函式,然後指定事件及事件處理常式。

下一個範例會示範如何處理 Rating 控制項的 change 事件。

Hh465493.wedge(zh-tw,WIN.10).gif處理評等控制項的變更事件

  1. 在 HTML 檔案中新增段落,並提供 "outputParagraph" 識別碼給它。您的事件接聽程式將輸出至這個段落。

            <p>Create a WinJS control in markup</p>
    
            <div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
                data-win-options="{maxRating: 10, averageRating: 6}">
            </div>
    
            <!-- This paragraph will be used to demonstrate event handling. -->
            <p id="outputParagraph"></p>
    
  2. 在 JavaScript 中,建立名為 ratingChanged 的事件處理常式,此函式會採用一個參數。接下來的這個範例會建立事件處理常式,顯示事件物件所包含的屬性和值。

    
        function ratingChanged(event) {
    
            var outputParagraph = document.getElementById("outputParagraph");
            var output = event.type + ": <ul>";
            var property;
            for (property in event) {
                output += "<li>" + property + ": " + event[property] + "</li>";
            }
    
            outputParagraph.innerHTML = output + "</ul>";
    
        }
    
  3. 使用 winControl 屬性從主機元素抓取控制項,然後呼叫 addEventListener 函式以新增事件處理常式。這個範例會在控制項建立之後便抓取,然後新增事件處理常式:

        app.onactivated = function (args) {
            if (args.detail.kind === activation.ActivationKind.launch) {
                if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                    // TODO: This application has been newly launched. Initialize
                    // your application here.
                } else {
                    // TODO: This application has been reactivated from suspension.
                    // Restore application state here.
                }
                args.setPromise(WinJS.UI.processAll().then(function () {
                    var control = document.getElementById("ratingControlHost").winControl;
                    control.addEventListener("change", ratingChanged, false); 
                }));
            }
        };
    

當您執行應用程式並變更評等時,它會建立事件資訊屬性和值的清單。

變更事件的輸出。

在程式碼中新增 WinJS 控制項

上一個範例示範如何建立和操作您在標記中所建立 WinJS 控制項,但您也可以改用 JavaScript 程式碼來建立 WinJS 控制項。

Hh465493.wedge(zh-tw,WIN.10).gif在程式碼中建立 WinJS 控制項

  1. 在標記中,建立將主控您控制項的元素。

    <div id="hostElement"></div>
    
  2. 在程式碼 (最好是在 DOMContentLoaded 事件處理常式) 中,擷取主機元素。

    var hostElement = document.getElementById("hostElement");
    
  3. 透過呼叫控制項的建構函式,並將主機元素傳遞至該建構函式,以建立控制項。這個範例會建立 Rating 控制項:

    var ratingControl = new WinJS.UI.Rating(hostElement); 
    

    當您執行程式時,會顯示您所建立的 Rating

    在程式碼中建立的評等控制項

    不需要呼叫 WinJS.UI.processAll— 在標記中建立 WinJS 控制項時,您只需要呼叫 WinJS.UI.processAll

摘要與後續步驟

您學會了如何建立 WinJS 控制項、如何設定屬性,以及如何附加事件處理常式。

下一個主題快速入門:設定控制項的樣式,描述如何使用階層式樣式表 (CSS),以及使用 JavaScript 的 Windows 市集應用程式的增強型樣式設定功能。若要深入了解特定控制項,請參閱控制項清單依功能分類的控制項主題。

範例

如需幾乎每個 WinJS 控制項與線上編輯器的動態程式碼範例,請參閱 try.buildwinjs.com

相關主題

取得 WinJS

控制項清單

依功能分類的控制項

適用於 Windows 執行階段和適用於 JavaScript 的 Windows Library 的 API 參考