快速入门：添加 WinJS 控件和样式 (HTML)

项目
03/04/2016

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅最新文档 ]

Windows JavaScript 库 (WinJS) 提供了高质量的基础结构（例如页面控件、承诺和数据绑定）、精美的 UI 功能（例如虚拟化集合），以及高性能的 Windows 控件（例如 ListView、FlipView 和 SemanticZoom）。

你可以在 Windows 运行时应用中、网站中，以及在使用基于 HTML 的应用技术（例如 Apache Cordova）时，使用 WinJS。

请将此操作功能视为我们的应用功能大全系列的一部分：Windows 应用商店应用 UI 大全。

先决条件

我们假设你可以创建使用 WinJS 模板的基本 Windows 应用商店应用（采用 JavaScript）。有关首次尝试创建应用的帮助，请参阅首次创建使用 JavaScript 的 Windows 应用商店应用。
我们假设你了解如何在使用 JavaScript 的 Windows 应用商店应用中处理事件。若要了解处理事件的建议方法，请参阅快速入门：添加 HTML 控件并处理事件。

什么是适用于 JavaScript 的 Windows 库？

WinJS 是由 CSS 和 JavaScript 文件组成的库。它包含组织到命名空间的 JavaScript 对象，旨在使开发外观精美的应用更轻松。 inJS 包含的对象有助于处理激活、访问存储以及定义你自己的类和命名空间。

有关 WinJS 提供的控件的完整列表，请参阅控件列表。
WinJS 还以可供你使用或替代的 CSS 样式和类的形式提供样式功能。（控件样式设置在快速入门：设置控件样式中进行说明。）

向页面中添加适用于 JavaScript 的 Windows 库

若要在应用或网站中使用最新版本的 WinJS：

从 Get 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-cn,WIN.10).gif 使用“空白应用程序”模板创建新项目

启动 Microsoft Visual Studio。
在“起始页”选项卡中，单击“新建项目”****。随即将打开“新建项目”对话框。
在“已安装”****窗格中，展开 JavaScript 并单击“Windows 应用商店应用”模板类型。JavaScript 可用的项目模板随即将显示在对话框的中心窗格中。
在中心窗格中，选择“空白应用程序”****项目模板。
在“名称”文本框中，输入项目名称。
单击“确定”****以创建项目。这需要花费一点时间。

Hh465493.wedge(zh-cn,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 控件看上去如下所示：

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 控件现在看上去如下所示：

Rating 控件显示的分级是 6 星，最多 10 星。

如果属性值本身是字符串，请将它包括在与用来设置 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 控件一样，为 WinJS 控件附加事件侦听器的首选方法是使用 addEventListener 函数。但是，检索 WinJS 控件与检索 HTML 控件稍有不同。

若要处理事件，请执行以下操作：

在 JavaScript 中，检索该控件的主机元素并使用它的 winControl 属性检索该控件。
调用该控件的 addEventListener 函数并指定一个事件和一个事件处理程序。

下一个示例展示如何处理 Rating 控件的 change 事件。

Hh465493.wedge(zh-cn,WIN.10).gif 处理 rating 控件的 change 事件

在 HTML 文件中，添加一个段落并为它赋予 ID "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); 
            }));
        }
    };

当你运行该应用并更改分级时，此示例会创建事件信息属性和值的列表。

change 事件的输出。

使用代码添加 WinJS 控件

上面的几个示例展示了如何使用标记创建 WinJS 控件以及如何处理这样的控件，但是你还可以改用 JavaScript 代码创建 WinJS 控件。

Hh465493.wedge(zh-cn,WIN.10).gif 使用代码创建 WinJS 控件

在标记中，创建将用来托管控件的元素。
```
<div id="hostElement"></div>
```
在代码中（最好是在 DOMContentLoaded 事件处理程序中），检索主机元素。
```
var hostElement = document.getElementById("hostElement");
```
通过调用控件的构造函数并向该构造函数传递主机元素来创建控件。以下示例创建一个 Rating 控件：
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
当你运行该程序时，它会显示已创建的 Rating：

在标记中创建 WinJS 控件时，无需调用 WinJS.UI.processAll—只需调用 WinJS.UI.processAll。

摘要和后续步骤

你已了解如何创建 WinJS 控件、如何设置这些控件的属性以及如何为这些控件附加事件处理程序。

下一个主题快速入门：设置控件样式介绍如何使用采用 JavaScript 的 Windows 应用商店应用的级联样式表 (CSS) 和增强样式功能。若要了解有关特定控件的更多信息，请参阅控件列表和按功能列出控件主题。

示例

有关几乎每一个 WinJS 控件的实时代码示例和联机编辑器，请参阅 try.buildwinjs.com。