添加 WinJS 控件和样式

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

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

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

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

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

先决条件

什么是适用于 JavaScript 的 Windows 库?

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

  • 有关 WinJS 提供的控件的完整列表,请参阅控件列表

  • WinJS 还以可供你使用或替代的 CSS 样式和类的形式提供样式功能。(控件样式设置在快速入门:设置控件样式中进行说明。)

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

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

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

  1. 启动 Microsoft Visual Studio。

  2. 在“起始页”选项卡中,单击“新建项目”。随即将打开“新建项目”对话框。

  3. 在“已安装”窗格中,展开 JavaScript 并单击“Windows 应用商店应用”模板类型。JavaScript 可用的项目模板随即将显示在对话框的中心窗格中。

  4. 在中心窗格中,选择“空白应用程序”项目模板。

  5. 在“名称”文本框中,输入项目名称。

  6. 单击“确定”以创建项目。这需要花费一点时间。

Hh465493.wedge(zh-cn,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 控件的 typeminmax 属性,可以在标记中设置 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 控件看上去如下所示:

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

若要处理事件,请执行以下操作:

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

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

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

  1. 在 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>
    
    
  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); 
                }));
            }
        };
    
    

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

change 事件的输出。

使用代码添加 WinJS 控件

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

Hh465493.wedge(zh-cn,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

    在代码中创建的 rating 控件

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

摘要和后续步骤

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

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

示例

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

相关主题

获取 WinJS
控件列表
按功能列出控件
Windows 运行时和 Windows JavaScript 库的 API 引用

 

 

显示:
© 2016 Microsoft