Idioma: JavaScript e HTML | VB/C#/C++ e XAML

Guia de início rápido: adicionando controles HTML e manipulando eventos (aplicativos do Tempo de Execução do Windows em JavaScript e HTML)

Applies to Windows and Windows Phone

Todo aplicativo precisa de controles, como botões, caixas de seleção e listas suspensas. Os aplicativos do Tempo de Execução do Windows em JavaScript podem usar dois tipos de controle: controles HTML intrínsecos e controles da Biblioteca do Windows para JavaScript. Os controles HTML intrínsecos são aqueles que fazem parte do padrão HTML, como botões e caixas de seleção.

Nosso foco está em como criar e usar os controles HTML. O próximo tópico, Guia de início rápido: adicionando controles e estilos WinJS, descreve como criar e usar os controles WinJS.

(Apenas Windows) Veja este recurso em ação como parte da nossa série de Recursos para aplicativos, do início ao fim.:  Interação do usuário: entrada por toque... e mais e Interface do usuário de aplicativo da Windows Store, do começo ao fim.

Pré-requisitos

O que é um controle?

Em muitos modelos de programação de aplicativos, você precisa de um controle para exibir ou interagir com o conteúdo. Como a maioria dos elementos HTML pode exibir conteúdo e responder a uma variedade de eventos, a distinção entre um controle e um elemento nem sempre é clara para os aplicativos do Tempo de Execução do Windows em JavaScript. Estamos nos referindo a elementos e objetos cujo principal objetivo é fornecer interatividade como controles. Para obter uma lista de elementos e objetos que se enquadram nessa categoria, veja Controles por função.

Adicionando um controle HTML

Você pode usar qualquer controle HTML em seu aplicativo do Tempo de Execução do Windows em JavaScript.

Hh465402.wedge(pt-br,WIN.10).gif Para adicionar um controle HTML

  • Para adicionar um controle HTML, apenas adicione o HTLM do controle à sua página, como você faria para uma página da Web típica. Este exemplo cria um button:
    
    <button id="button1">An HTML Button</button>
    
    

    Geralmente, é uma boa ideia atribuir uma ID ou nome de classe ao controle para que você possa recuperá-lo e manipulá-lo facilmente. Em seguida, quando mostrarmos como anexar eventos, você usará a ID do botão para encontrá-lo.

O HTML de um controle nem sempre é tão simples quanto o de um botão. Por exemplo, para criar um controle slider, use o elemento de entrada input:


<input type="range" />

Para obter uma lista de controles HTML disponíveis e a marcação que você usa para criá-los, veja a Lista de controles.

Manipulando eventos

Todo controle fornece eventos que permitem que você responda a ações do usuário. Por exemplo, o controle de botão fornece um evento click que é gerado quando um usuário clica no botão. Crie uma função, chamada manipulador de eventos, para manipular o evento e depois registre o manipulador de eventos com o controle.

Existem duas formas de registrar um manipulador de eventos. Uma forma é adicionar um manipulador de eventos ao seu HTML definindo o atributo de evento do controle como o nome de uma função de manipulador de eventos JavaScript ou de uma instrução JavaScript. Para saber mais sobre essa abordagem, veja a seção Por que você não deve definir um manipulador de eventos na marcação.

A outra forma de adicionar um manipulador de eventos é adicioná-lo programaticamente. Esta é a abordagem que recomendamos.

Hh465402.wedge(pt-br,WIN.10).gifPara registrar um manipulador de eventos programaticamente

  1. Crie o controle e atribua uma ID a ele. Este exemplo cria um botão e atribui a ele a ID "button1".
    
    <button id="button1">An HTML button</button>
    
    
  2. Apenas para este exemplo, crie um elemento de parágrafo e atribua a ID "button1Output". Você o utilizará para exibir informações sobre o evento de clique do botão.

    
    <p id="button1Output"></p>
    
    
  3. No seu código JavaScript, defina um manipulador de evento. A maioria dos manipuladores de eventos aceita um único argumento: um objeto Event contendo informações sobre o evento. Outros eventos podem retornar outros tipos de objetos de informações do evento para fornecer informações específicas sobre aquele evento.

    O evento click fornece um objeto MouseEvent contendo informações sobre o evento, como qual botão do mouse foi pressionado e qual objeto disparou o evento. Este exemplo cria um manipulador de eventos click que usa o objeto MouseEvent para obter as coordenadas x e y do ponto em que o usuário clicou.

    (O evento click também responde a interações de toque e de teclado. Os exemplos neste tópico pressupõem que o usuário esteja clicando com um mouse. Para saber mais sobre interação de toque e diferentes dispositivos, veja Respondendo à interação do usuário.)

    
    function button1Click(mouseEvent) {
        var button1Output = document.getElementById("button1Output");
        button1Output.innerText =
        mouseEvent.type
        + ": (" + mouseEvent.clientX + "," + mouseEvent.clientY + ")";
    
    }
    
    
  4. Agora você precisa anexar o evento ao seu controle recuperando-o e chamando addEventListener. A pergunta é quando você deve recuperar o controle? Você poderia adicioná-lo a qualquer lugar do seu código JavaScript, mas existiria uma chance de ele ser chamado antes de o controle existir.

    • Se você estiver adicionando o controle à página inicial do aplicativo, que é definida por default.html e default.js, use a função WinJS.UI.processAll para registrar os manipuladores de eventos. Cada modelo do Microsoft Visual Studio cria um arquivo default.js que chama WinJS.UI.processAll no manipulador de eventos activated. Como este é um método assíncrono, o método WinJS.UI.processAll retorna Promise. Para anexar seus manipuladores de eventos, forneça uma função then ou done do Promise que o WinJS.UI.processAll retorna e use essa função para anexar os manipuladores de eventos. (Para saber mais sobre as promessas, veja Programação assíncrona em JavaScript.)

      Este exemplo usa WinJS.UI.processAll para anexar o manipulador de eventos do botão.

      
      (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().done(function () {
                      var button1 = document.getElementById("button1");
                      button1.addEventListener("click", button1Click, false);
                      })
                  );
              }
          };
      
          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().
          };
      
          // The click event handler for button1
          function button1Click(mouseEvent) {
              var button1Output = document.getElementById("button1Output");
              button1Output.innerText =
                  mouseEvent.type
                  + ": (" + mouseEvent.clientX + "," + mouseEvent.clientY + ")";
      
          }
      
          app.start();
      })();
      
      
      

      Para saber mais sobre o método WinJS.UI.processAll, veja Guia de início rápido: adicionando controles e estilos WinJS.

    • Se você estiver adicionando o controle a um controle de Página, no controle de Página, use a função ready para anexar seus manipuladores de eventos.

      O controle de  Página WinJS é uma maneira de dividir o conteúdo em unidades modulares reutilizáveis. Seu aplicativo pode incluir um ou mais controles de Página automaticamente, dependendo do modelo do Visual Studio que você usou para criá-lo.

      Quando você cria um controle de Página, ele inclui automaticamente uma ready que você pode usar para adicionar um manipulador de eventos ao seu botão. Este exemplo mostra o código JavaScript completo de um controle de Página que adiciona um manipulador de eventos click a um botão.

      
      
      // home.js
      (function () {
          "use strict";
      
          WinJS.UI.Pages.define("/pages/home/home.html", {
              // This function is called whenever a user navigates to this page. It
              // populates the page elements with the app's data.
              ready: function (element, options) {
                  // TODO: Initialize the page here.
                  var button1 = element.querySelector("#button1");
                  button1.addEventListener("click", this.button1Click, false);
              },
      
              button1Click: function(mouseEvent) {
                  var button1Output = document.getElementById("button1Output");
                  button1Output.innerText =
                  mouseEvent.type
                  + ": (" + mouseEvent.clientX + "," + mouseEvent.clientY + ")";
      
              }
          });
      })();
      
      
      

      Para saber mais sobre os controles de Página, veja Adicionando controles de página.

    • Se você está adicionando o controle aos seus próprios arquivos HTML e JavaScript personalizados, manipule o evento DOMContentLoaded e o use para chamar WinJS.UI.processAll. Você pode registrar o evento DOMContentLoaded em qualquer lugar do seu código, pois o objeto document já existe no momento em que seu código é executado. Forneça uma função then ou done para o Promise retornado por WinJS.UI.processAll e use essa função para anexar seus manipuladores de eventos.

Quando você executa o aplicativo e clica no botão, ele exibe as coordenadas do ponto de clique.

Por que você não deve definir um manipulador de eventos na marcação

Você pode adicionar manipuladores de eventos à sua marcação, mas, de alguma forma, isso pode ser mais complicado do que adicioná-los com o método addEventListener devido a problemas de escopo. Quando você usa o Visual Studio para criar um novo aplicativo do Tempo de Execução do Windows em JavaScript Aplicativo em Branco, ele cria este arquivo default.js:


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

Todo código é encapsulado em uma função global anônima. O encapsulamento de código em uma função global anônima é uma prática recomendada porque ele limita o escopo do código do aplicativo e evita poluir o namespace global. Se você adicionar o manipulador de eventos descrito anteriormente, o código subjacente ao arquivo teria esta aparência:


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

    function button1Click(mouseEvent) {
        var button1Output = document.getElementById("button1Output");
        button1Output.innerText =
        mouseEvent.type
        + ": (" + mouseEvent.clientX + "," + mouseEvent.clientY + ")";

    }

    app.start();
})();

Se você definir o manipulador de eventos na marcação, não no seu código, o botão dos exemplos anteriores teria esta aparência:



<!-- Incorrect code. Do not use this in your solution. -->
<button id="button1" onclick="button1Click(event)">An HTML button</button>

Quando você executa o aplicativo e clica no botão, nada acontece. Isso ocorre porque a função button1Click é encapsulada em uma função anônima e não está diretamente acessível à sua marcação. Para que seu código funcione, você precisa remover button1Click da função anônima.


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

function button1Click(mouseEvent) {
    var button1Output = document.getElementById("button1Output");
    button1Output.innerText =
    mouseEvent.type
    + ": (" + mouseEvent.clientX + "," + mouseEvent.clientY + ")";

}


Mas agora button1Click é global, o que não é nossa intenção. Uma boa opção é retornar a definição button1Click para a função anônima e depois usar WinJS.Namespace.define para torná-la publicamente acessível (para obter um exemplo de como fazer isso, veja Como definir manipuladores de eventos declarativamente).

Comentários

Não use URIs JavaScript

Não use URIs JavaScript em seu manipulador de eventos porque seu aplicativo não vai executá-los. Por exemplo, se você tentar fazer isso, nada acontecerá quando você clicar no botão:



<!-- Incorrect code. Do not use this in your solution. -->
<button id="button1" onclick="javascript: 2 + 2;">An HTML Button</button>

Essa restrição se aplica a código no contexto do aplicativo (código incluído no pacote do aplicativo), mas não se aplica a código em páginas da Web externas acessadas pelo seu aplicativo.

Usando formulários

Em um site HTML tradicional, os controles e outros elementos de entrada geralmente são contidos em um elemento form. Os elementos form são usados para passar dados para o servidor. Como a maior parte da programação de um aplicativo típico é baseada no cliente, geralmente não é preciso usar um elemento form.

Usando camadas transparentes

É prática comum usar uma camada transparente em tela inteira, como um elemento div vazio, para detectar certas interações do usuário ou exibir animações. Porém, cobrir um controle HTML com uma camada transparente pode reduzir sua resposta às interações do usuário. Para manter a resposta dos controles HTML, não coloque uma camada transparente sobre eles.

Resumo e próximas etapas

Você aprendeu a criar controles HTML e a anexar manipuladores de eventos.

Em seguida, aprenda a usar os novos controles WinJS fornecidos para aplicativos do Tempo de Execução do Windows em JavaScript lendo Guia de início rápido: adicionando controles e estilos WinJS.

Para saber mais sobre controles específicos, veja Lista de controles.

Amostras

Tópicos relacionados

Codificando aplicativos básicos
Início rápido: adicionando controles e estilos WinJS
Lista de controles

 

 

Mostrar:
© 2014 Microsoft. Todos os direitos reservados.