Guia de Início Rápido: Adicionando Controles WinJS e Estilos (HTML)

Artigo
03/04/2016

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

A Biblioteca do Windows para JavaScript (WinJS) fornece infraestrutura de alta qualidade como controles de página, promessas e associação de dados; recursos de interface do usuário refinados como virtualização de coleções; e controles de alto desempenho do Windows, como ListView, FlipView e SemanticZoom.

Você pode usar WinJS em seus aplicativos em Tempo de Execução do Windows, em seus sites e quando usar tecnologias de aplicativo com base em HTML como Apache Cordova.

Consulte este recurso em ação como parte da nossa série Recursos para aplicativos, do início ao fim: Interface do usuário de aplicativo da Windows Store, do início ao fim.

Pré-requisitos

Nós supomos que você possa criar um aplicativo da Windows Store básico em JavaScript que use o modelo WinJS. Para obter ajuda para criar seu primeiro aplicativo, veja Criar seu primeiro aplicativo da Windows Store em JavaScript.
Presumimos que você saiba manipular eventos em um aplicativo da Windows Store em JavaScript. Para aprender a forma recomendada de manipular eventos, consulte Guia de início rápido: adicionando controles HTML e manipulando eventos.

O que é a Biblioteca do Windows para JavaScript?

O WinJS é uma biblioteca de arquivos CSS e JavaScript. Ele inclui objetos JavaScript, organizados em namespaces, criados para facilitar o desenvolvimento de aplicativos com ótima aparência. O WinJS inclui objetos que servem para ativar, acessar o armazenamento e definir suas próprias classes e namespaces.

(Para obter a lista completa dos controles que o WinJS fornece, confira Lista de controles.)
O WinJS também inclui recursos de definição de estilo na forma de estilos e classes CSS que você pode usar ou substituir. (A definição do estilo do controle está descrita em Guia de início rápido: definindo o estilo de controles.)

Adicionando a Biblioteca do Windows para JavaScript a sua página

Para usar a versão mais recente do WinJS no seu aplicativo ou site:

Baixe a versão mais recente na página para baixar o WinJS (em inglês) e copie-a para o diretório para seu aplicativo ou site.
Adicione referências de script e CSS do WinJS a cada página do aplicativo ou site que usa os recursos WinJS.

Este exemplo mostra a aparência dessas referências para um aplicativo que tenha seus arquivos WinJS em seu diretório raiz.

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

Adicionando um controle WinJS em marcação

Diferentemente dos controles HTML, os controles WinJS não possuem elementos de marcação dedicados: você não pode criar um controle Rating adicionando um elemento <rating />, por exemplo. Para adicionar um controle WinJS, você cria um elemento div e usa o atributo data-win-control para especificar o tipo de controle desejado. Para adicionar um controle Rating, você define o atributo como "WinJS.UI.Rating".

Você também deve chamar a função WinJS.UI.processAll em seu código JavaScript. O WinJS.UI.processAll analisa sua marcação e cria uma instância de quaisquer controles WinJS que encontrar.

O próximo conjunto de exemplos mostra como adicionar um controle WinJS a um projeto criado com o modelo Aplicativo em Branco. É mais fácil acompanhar as etapas quando você cria um novo projeto Aplicativo em Branco.

Hh465493.wedge(pt-br,WIN.10).gif Para criar um novo projeto usando o modelo Aplicativo em Branco

Inicie o Microsoft Visual Studio.
Na guia Página Inicial, clique em Novo Projeto. A caixa de diálogo Novo Projeto é aberta.
No painel Instalado, expanda JavaScript e clique no tipo de modelo Aplicativo da Windows Store. Os modelos de projeto disponíveis para JavaScript são exibidos no painel central da caixa de diálogo.
No painel central, selecione o modelo de projeto Aplicativo em Branco.
Na caixa de texto Nome, insira um nome para o seu projeto.
Clique em OK para criar o projeto. Isso levará um tempo.

Hh465493.wedge(pt-br,WIN.10).gif Para adicionar um controle da WinJS

Crie um elemento div onde você quer colocar o controle. Defina o seu atributo data-win-control para o nome totalmente qualificado do controle que você quer criar. Este exemplo cria um controle Rating na página inicial do aplicativo (o arquivo 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>

O seu código JavaScript deve chamar WinJS.UI.processAll para inicializar o controle Rating que você criou na etapa anterior. Se você estiver usando o modelo Aplicativo em Branco, o seu arquivo default.js já inclui uma chamada para 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();
})();

Se você não estiver usando o modelo Aplcativo em Branco ou se estiver adicionando o controle a uma página que você criou, pode precisar adicionar uma chamada a WinJS.UI.processAll.

Se você adicionou o controle à home page de seu aplicativo (que normalmente é o arquivo default.html), adicione uma chamada para WinJS.UI.processAll em seu manipulador de evento de onactivated, como mostrado no exemplo anterior.
Se você adicionou o controle a um Controle de páginas, você não precisa adicionar uma chamada para WinJS.UI.processAll porque o Controle de páginas faz isso para você automaticamente.
Se você adicionou o controle a outra página que não é a homepage de seu aplicativo, trate o evento DOMContentLoaded e use o manipulador para chamar WinJS.UI.processAll.
```
function initialize() {
    WinJS.UI.processAll();
}

document.addEventListener("DOMContentLoaded", initialize(), false);
```

A função WinJS.UI.processAll processa o documento e ativa quaisquer controles WinJS que você declarou na marcação.

Quando você executa o aplicativo, o controle Rating aparece onde você posicionou o elemento do host div.

Um controle de classificação

Definindo as propriedades de um controle WinJS em marcação

Quando você cria um controle HTML, você pode definir as suas propriedades usando os atributos dedicados. Por exemplo, para definir as propriedades type, min e max de um controle input, você pode definir os atributos type, min e max em sua marcação:

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

Diferentemente dos controles HTML, os controles WinJS não possuem elemento dedicado nem marcas de atributos; por exemplo, você não pode criar um controle Rating e definir suas propriedades usando esta marcação:

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

Em vez disso, você usa o atributo data-win-options para definir uma propriedade na marcação. Ele pega uma cadeia de caracteres que contém um ou mais pares de propriedade/valor:

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

Este exemplo define o maxRating de um controle Rating como 10.

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

Quando você executa o aplicativo, o controle Rating fica parecendo assim:

O controle de classificação mostra um sistema de classificação de 10 estrelas.

Para definir mais do que uma propriedade, separe-as com uma vírgula:

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

O próximo exemplo define duas propriedades do controle Rating.

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

Quando você executa o aplicativo, o controle Rating agora parece assim:

O controle de classificação mostra uma classificação de 6 em 10 estrelas.

Se o valor da propriedade é uma cadeia de caracteres, coloque-o entre um tipo de aspas diferente (' ou ") do que você usou para definir o atributo data-win-options. Este exemplo mostra como definir a propriedade current do controle TimePicker, que pega uma cadeia de caracteres:

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

Um controle do Seletor de Hora mostrando a hora em 10:29 AM.

Para descobrir se uma propriedade é compatível com determinado controle WinJS, veja a sua página de referência.

Recuperando um controle que você criou na marcação

Você também pode definir as propriedades de um controle WinJS programaticamente. Para acessar o controle em código, recupere o elemento do host e, em seguida, use a sua propriedade winControl para recuperar o controle. Nos exemplos anteriores, o elemento do host do controle Rating é "ratingControlHost".


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

Em alguns casos, você pode querer recuperar e manipular o controle assim que ele estiver disponível. Saiba de que o método WinJS.UI.processAll é assíncrono, então qualquer código que segui-lo pode ser executado antes de WinJS.UI.processAll ser concluído. Sendo assim, não tente manipular o controle imediatamente porque ele pode não estar disponível:


WinJS.UI.processAll();

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

O WinJS.UI.processAll retorna um objeto WinJS.Promise que você pode usar para chamar uma função quando o método WinJS.UI.processAll termina. Aqui o exemplo define a função de realização que recupera o controle e define seu averageRating como 3.


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

A próxima seção descreve como adicionar ouvintes de eventos a um controle WinJS.

Manipulando eventos para os controles WinJS

Assim como nos controles HTML, a forma preferida de anexar ouvintes de eventos a um controle WinJS é usando a função addEventListener. Porém, a recuperação de um controle WinJS é um pouco diferente de um controle HTML.

Para manipular um evento

Em seu JavaScript, recupere o elemento host do controle e use a sua propriedade winControl para recuperar o controle.
Chame a função addEventListener do controle e especifique um evento e um manipulador de evento.

O próximo exemplo mostra como manipular com um evento change de um controle Rating.

Hh465493.wedge(pt-br,WIN.10).gif Para manipular com o evento de mudança de um controle de classificação

Em seu arquivo HTML, adicione um parágrafo e dê a ele uma ID de "outputParagraph". O seu ouvinte de evento enviará a saída para este parágrafo.

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

Em seu JavaScript, crie uma função manipuladora de eventos chamada ratingChanged que usa um parâmetro. O próximo exemplo cria um manipulador de eventos que exibe as propriedades e valores contidos no objeto de evento.


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

    }

Use a propriedade winControl para recuperar o controle do elemento host e chamar a função addEventListener para adicionar seu manipulador de evento. Este exemplo recupera o controle assim que ele é criado e adiciona o manipulador de eventos:

    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); 
            }));
        }
    };

Quando você executa o aplicativo e muda a classificação, ele cria uma lista de propriedades e valores de informações do evento.

A saída do evento de mudança.

Adicionando um controle WinJS em código

Os exemplos anteriores mostraram como criar e manipular um controle WinJS que você criou em sua marcação; mas você também pode criar um controle WinJS usando código JavaScript.

Hh465493.wedge(pt-br,WIN.10).gif Para criar um controle WinJS em código

Em sua marcação, crie o elemento que hospedará o seu controle.
```
<div id="hostElement"></div>
```
Em seu código (preferencialmente em seu manipulador de eventos DOMContentLoaded), recupere o elemento de host.
```
var hostElement = document.getElementById("hostElement");
```
Crie seu controle chamando o construtor e passando o elemento host para o construtor. Este exemplo cria um controle Rating:
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
Quando você executa o programa, ele exibe a Rating que você criou:

Não é preciso chamar WinJS.UI.processAll — você só precisa chamar WinJS.UI.processAll ao criar um controle WinJS na marcação.

Resumo e próximas etapas

Você aprendeu como criar controles WinJS, definir suas propriedades e anexar manipuladores de eventos.

O próximo tópico, Início rápido: definindo o estilo de controles, descreve como usar as capacidades de Folhas de Estilo em Cascata (CSS) e de definição de estilos melhorada dos aplicativos da Windows Store em JavaScript. Para saber mais sobre controles específicos, veja os tópicos Lista de controles e Controles por função.