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

發行項
03/04/2016

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

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

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

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

先決條件

我們假設您可以利用 JavaScript，以 WinJS 範本建立基本的 Windows 市集應用程式。如果建立您的第一個應用程式時需要協助，請參閱使用 JavaScript 建立您的第一個 Windows 市集應用程式。
我們假設您知道如何處理使用 JavaScript 的 Windows 市集應用程式中的事件。若要了解建議的事件處理方法，請參閱快速入門：新增 HTML 控制項和處理事件。

什麼是適用於 JavaScript 的 Windows Library？

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

如需 WinJS 所提供之控制項的完整清單，請參閱控制項清單。
WinJS 也會以 CSS 樣式和類別的形式，提供您可以使用或覆寫的樣式設定功能 (控制項樣式設定詳述於快速入門：設定控制項的樣式)。

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

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

從取得 WinJS 下載最新版，並複製到您應用程式或網站的目錄中。
將 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 使用 [空白的應用程式] 範本建立新的專案

啟動 Microsoft Visual Studio。
在 [起始頁] 索引標籤，按一下 [新增專案]****。隨即開啟 [新增專案] 對話方塊。
在 [已安裝的]**** 窗格中，展開 [JavaScript]，然後按一下 [Windows 市集應用程式]**** 範本類型。適用於 JavaScript 的可用專案範本會顯示在對話方塊的中央窗格中。
在中央窗格中，選取 [空白的應用程式] 專案範本。
在 [名稱]**** 文字方塊中，輸入專案的名稱。
按一下 [確定] 來建立專案。這可能要花一點時間。

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

建立您要放置控制項的 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>

您的 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 控制項的 type、min 以及 max 內容，可以在標記中設定 type 、min 和 max 屬性。

<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 控制項稍有不同。

處理事件：

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

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

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

在 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>

在 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>";

    }

使用 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 控制項

在標記中，建立將主控您控制項的元素。
```
<div id="hostElement"></div>
```
在程式碼 (最好是在 DOMContentLoaded 事件處理常式) 中，擷取主機元素。
```
var hostElement = document.getElementById("hostElement");
```
透過呼叫控制項的建構函式，並將主機元素傳遞至該建構函式，以建立控制項。這個範例會建立 Rating 控制項：
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
當您執行程式時，會顯示您所建立的 Rating：

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

摘要與後續步驟

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

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

範例

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

共用方式為