Краткое руководство: добавление элементов управления и стилей WinJS (HTML)

Статья
03/04/2016

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. В случае разработки приложений для Windows 10 см. раздел последняя документация]

Библиотека Windows для JavaScript (WinJS) предоставляет высококачественную инфраструктуру (в том числе элементы управления страницами, объекты Promise и привязку данных), усовершенствованные функции в пользовательском интерфейсе (такие как виртуализация коллекций) и высокоэффективные элементы управления Windows (например, ListView, FlipView и SemanticZoom).

Вы можете использовать WinJS в приложениях среды выполнения Windows, на веб-сайтах, а также при использовании приложений на основе HTML, например Apache Cordova.

Посмотрите, как работает эта функция, в нашей серии Компоненты приложения от начала до конца, в разделе Пользовательский интерфейс приложений Магазина Windows от А до Я.

Предварительные требования

Предполагается, что вы умеете создавать простые приложения Магазина Windows на JavaScript с использованием шаблонов WinJS. Дополнительные сведения о создании первого приложения см. в разделе Создание первого приложения Магазина Windows на JavaScript.
Предполагается, что вы имеете представление об обработке событий в приложении Магазина Windows на JavaScript. Рекомендуемый способ обработки событий см. в разделе Краткое руководство: добавление элементов управления HTML и обработка событий.

Что такое библиотека Windows для JavaScript?

WinJS — это библиотека файлов CSS и JavaScript. В ней содержатся организованные по пространствам имен объекты JavaScript, призванные упростить разработку качественных приложений. WinJS включает объекты, помогающие обрабатывать активацию, получать доступ к хранилищу и определять собственные классы и пространства имен.

Полный список элементов управления, предоставляемых WinJS, см. в разделе Список элементов управления.
WinJS также предоставляет средства работы со стилями в виде стилей и классов CSS, которые можно использовать или переопределять. (Определение стилей элементов управления описывается в разделе Краткое руководство: стили элементов управления.)

Добавление библиотеки Windows для JavaScript для своей страницы

Использование последней версии 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".

Также необходимо вызвать функцию WinJS.UI.processAll в коде JavaScript. Функция WinJS.UI.processAll анализирует разметку и создает экземпляры всех обнаруженных ею элементов управления WinJS.

В следующей серии примеров показано, как добавить элемент управления библиотеки WinJS в проект, созданный с помощью шаблона "Пустое приложение". Следить за изложением будет легче, если вы создадите новый проект с помощью шаблона "Пустое приложение".

Hh465493.wedge(ru-ru,WIN.10).gif Порядок создания нового проекта с помощью шаблона "Пустое приложение"

Запустите Microsoft Visual Studio.
На начальной странице щелкните Создать проект. Откроется диалоговое окно Новый проект.
На панели Установленные разверните узел JavaScript, а затем выберите тип шаблона Приложение Магазина Windows. Шаблоны проектов для JavaScript отображаются на центральной панели диалогового окна.
На центральной панели выберите шаблон Пустое приложение.
В текстовом поле Имя введите имя для вашего проекта.
Чтобы создать проект, нажмите кнопку ОК. Это займет некоторое время.

Hh465493.wedge(ru-ru,WIN.10).gif Порядок добавления элемента управления WinJS

Создайте элемент div, в который требуется поместить элемент управления. Для его атрибута data-win-control задайте полное имя создаваемого элемента управления. В этом примере создается элемент управления Rating на начальной странице приложения (файл default.html).

<!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), добавьте вызов функции WinJS.UI.processAll в ваш обработчик событий onactivated, как показано в предыдущем примере.
- Если элемент управления добавлен в элемент управления страницей, вызов функции 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 можно задать его свойства с помощью выделенных атрибутов. Например, чтобы задать свойства type, min и max элемента управления input, в разметке необходимо указать атрибуты 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}"

Этот пример задает свойству maxRating элемента управления Rating значение, равное 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 теперь выглядит следующим образом:

Элемент управления оценкой показывает оценку 6 из 10 звезд.

Если значение свойства — строка, заключите его в другие кавычки (' или "), не те, которые использовались при задании атрибута data-win-options. В этом примере показано, как задать для элемента управления TimePicker свойство current, принимающее строку:

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

Элемент управления TimePicker, показывающий время 10:29.

Чтобы узнать, поддерживается ли свойство заданным элементом управления 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 элемента управления и укажите событие и обработчик событий.

В примере ниже показана обработка события change элемента управления Rating.

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

Hh465493.wedge(ru-ru,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, настраивать их свойства и подключать обработчики событий.

В следующем разделе под названием Краткое руководство: стили элементов управления описывается использование каскадных таблиц стилей (CSS) и расширенных возможностей работы со стилями приложений Магазина Windows на JavaScript. Дополнительные сведения о конкретных элементах управления см. в разделах Список элементов управления и Элементы управления по функциям.