Início rápido: ponteiros (HTML)

  • Artigo

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

Interações por toque, mouse e caneta/caneta digitalizadora são recebidas, processadas e gerenciadas como uma entrada de ponteiro em aplicativos em JavaScript.

Atualizações para Windows 8.1: O Windows 8.1 introduz uma série de atualizações e melhorias para as APIs de entrada de ponteiro. Para saber mais, veja Alterações de API para Windows 8.1.

Se você for iniciante no desenvolvimento de aplicativos em JavaScript: Leia estes tópicos para se familiarizar com as tecnologias discutidas aqui.

Criar seu primeiro aplicativo da Windows Store em JavaScript

Mapa para os aplicativos da Windows Store usando JavaScript

Saiba mais sobre eventos com Guia de início rápido: adicionando controles HTML e manipulando eventos

Recursos de aplicativos, do início ao fim:

Explore esse recurso mais profundamente como parte da nossa série sobre recursos para aplicativos, do início ao fim

Interação do usuário, do início ao fim (HTML)

Personalização da interação do usuário, do início ao fim (HTML)

Diretrizes de experiência do usuário:

As bibliotecas de controle de plataforma (HTML e XAML) fornecem a experiência de total interação do usuário do Windows, incluindo interações padrão, efeitos físicos animados e comentários visuais. Se não precisar de suporte para interação personalizada, use esses controles internos.

Se os controles de plataforma não forem suficientes, as diretrizes a seguir para interação do usuário podem ajudá-lo a proporcionar uma experiência de interação envolvente e imersiva, consistente entre os modos de entrada. Essas diretrizes têm como foco principal a entrada por toque, mas elas ainda são relevante para entrada por touchpad, mouse, teclado e caneta.

Exemplos: Veja essa funcionalidade em ação em nossos exemplos de aplicativos.

Exemplo de personalização da interação do usuário, do início ao fim

Amostra de rolagem, movimento panorâmico e aplicação de zoom em HTML

Entrada: amostra de manipulação de eventos de ponteiros DOM

Entrada: exemplo de gestos instanciáveis

Entrada: amostra de tinta

Entrada: exemplo de manipulações e gestos (JavaScript)

Entrada: exemplo de tinta simplificada

Objetivo: Para saber como escutar e manipular a entrada de ponteiro.

Pré-requisitos

Nós supomos que você possa criar um aplicativo básico em JavaScript que use o modelo da Biblioteca do Windows para JavaScript.

Para completar este tutorial, você precisa:

Tempo para conclusão: 30 minutos.

Instruções

O que é a entrada de ponteiro?

Ao unificar a entrada por toque, mouse, caneta/caneta digitalizadora como uma entrada de ponteiro abstrata, você pode manipular interações do usuário com o seu aplicativo independentemente do tipo de dispositivo de entrada em uso.

Um objeto de ponteiro representa um "contato" de entrada único e exclusivo (um PointerPoint) de um dispositivo de entrada (como um mouse, caneta/caneta digitalizadora, um dedo ou vários dedos). O sistema cria um ponteiro quando um contato é detectado pela primeira vez, destruindo-o quando esse ponteiro sai (se afasta) do intervalo de detecção ou é cancelado. No caso de vários dispositivos ou entrada multitoque, cada contato é tratado como um ponteiro exclusivo.

Há um extenso conjunto de entradas de ponteiro com base em APIs de entrada que pode interceptar os dados de entrada diretamente de vários dispositivos. Você pode lidar com eventos de ponteiro para obter informações comuns, como localização e tipo de dispositivo, e informações estendidas, como pressão e geometria de contato. Como, em vários casos, os aplicativos devem responder a diferentes modos de entrada de diferentes maneiras, propriedades de dispositivo específicas também estão disponíveis, como qual botão do mouse um usuário pressionou ou se um usuário está usando a ponta de borracha da caneta. Por exemplo, o toque pode ser filtrado para dar suporte a interações, como movimentação panorâmica e rolagem, enquanto o mouse e a caneta/caneta digitalizadora são tipicamente mais adequados para tarefas precisas, como pintura e desenho. Caso seu aplicativo precise diferenciar entre dispositivos de entrada e suas funcionalidades, veja Guia de Início Rápido: Identificando Dispositivos de Entrada.

Se você implementar seu próprio suporte para interação, tenha em mente que os usuários esperam uma experiência intuitiva que envolva a interação direta com os elementos de interface do usuário do seu aplicativo. Recomendamos que você modele suas interações personalizadas nos controles de estrutura para manter as coisas consistentes e detectáveis. Apenas crie interações personalizadas se houver uma exigência clara e bem definida e se nenhuma das interações básicas for permitida em seu cenário.

Criar a interface do usuário

Para este exemplo, usamos um retângulo (target) como objeto de destino para a entrada de ponteiro. A cor do destino muda quando o status do ponteiro muda.

Os detalhes de cada ponteiro são exibidos em um bloco de texto flutuante localizado adjacente ao ponteiro e segue todos os movimentos do ponteiro. Eventos de ponteiros específicos são relatados à extrema direita da exibição. A captura de tela a seguir mostra a IU deste exemplo.

Captura de tela da IU do aplicativo de exemplo

Este é o HTML para este exemplo.

Observação  Aplicativos da Windows Store

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>PointerInput_Universal.Windows</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <!-- PointerInput_Universal.Windows references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body class="windows">
    <div id="grid">
        <div id="targetContainer">
            <div id="target"></div>
        </div>
        <div id="bottom">
        </div>
        <div id="eventLog"></div>
    </div>
</body>
</html>

Observação  Aplicativos da Loja do Windows Phone

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>PointerInput_Universal.WindowsPhone</title>

    <!-- WinJS references -->
    <!-- At runtime, ui-themed.css resolves to ui-themed.light.css or ui-themed.dark.css 
    based on the user’s theme setting. This is part of the MRT resource loading functionality. -->
    <link href="/css/ui-themed.css" rel="stylesheet" />
    <script src="//Microsoft.Phone.WinJS.2.1/js/base.js"></script>
    <script src="//Microsoft.Phone.WinJS.2.1/js/ui.js"></script>

    <!-- PointerInput_Universal.Phone references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body class="phone">
    <div id="grid">
        <div id="targetContainer">
            <div id="target"></div>
        </div>
        <div id="bottom">
        </div>
        <div id="eventLog"></div>
    </div>
</body>
</html>

Estas são as CSS (Folhas de Estilos em Cascata) para este exemplo.

Observação  Eventos de ponteiro não são disparados durante uma interação de panorâmica ou zoom. Você pode desabilitar gestos de panorâmica e zoom por meio das propriedades msTouchAction, overflow e -ms-content-zooming da CSS.

 

body {
    overflow: hidden;
    position: relative;
}

#grid {
    display: -ms-grid;
    height: 100vh; /* 100% of viewport height */
    -ms-grid-columns: 4fr 1fr; /* 2 columns */
    -ms-grid-rows: 1fr 320px 1fr;  /* 3 rows */
    /*touch-action: none;*/ /* Disable panning and zooming */
}
#targetContainer {
    border:solid;
    border-width:thin;
    border-color: red;
    -ms-grid-row: 2;
    -ms-grid-column: 1;
    -ms-grid-row-align: center;
    -ms-grid-column-align: center;
    /*touch-action: none; /* Disable panning and zooming */*/
}
#eventLog {
    -ms-grid-row: 1;
    -ms-grid-column: 2; 
    -ms-grid-row-span: 3;
    padding-right: 10px;
    background-color: black;
    color: white;
}
.phone #target {
    width: 200px;
    height: 300px;
    border: none;
    padding: 0px;
    margin: 0px;
    -ms-transform-origin: 0% 0%;
    /*touch-action: none; /* Disable panning and zooming */*/
}
.windows #target {
    width: 400px;
    height: 200px;
    border: none;
    padding: 0px;
    margin: 0px;
    -ms-transform-origin: 0% 0%;
    touch-action: none; /* Disable panning and zooming */
}

Escutar eventos de ponteiro

Na maioria dos casos, recomendamos que você obtenha informações sobre o ponteiro por meio do argumento de eventos dos manipuladores de eventos do ponteiro em sua estrutura de idioma escolhida.

Se o argumento não representar os detalhes de ponteiro exigidos pelo seu aplicativo, você poderá obter acesso a dados de ponteiro estendidos do argumento do evento por meio dos métodos getCurrentPoint e getIntermediatePoints ou das propriedades currentPoint e intermediatePoints. Nós recomendamos o uso dos métodos getCurrentPoint e getIntermediatePoints pois você pode especificar o contexto dos dados de ponteiro.

A captura de tela a seguir mostra a área de destino com detalhes do ponteiro do mouse deste exemplo.

Captura de tela da área de destino do ponteiro.

Aqui, configuramos o local na tela e os ouvintes de eventos da área de destino.

Em primeiro lugar, declaramos variáveis globais, inicializamos as áreas de detalhes do ponteiro e do destino e identificamos o registrador de log de eventos.

// For this example, we track simultaneous contacts in case the 
// number of contacts has reached the maximum supported by the device.
// Depending on the device, additional contacts might be ignored 
// (PointerPressed not fired). 
var numActiveContacts = 0;

// The input target.
var target;

// Target background colors corresponding to various pointer states.
var pointerColor = {
    hover: "rgb(255, 255, 102)",
    down: "rgb(0, 255, 0)",
    up: "rgb(255, 0, 0)",
    cancel: "rgb(0,0,0)",
    out: "rgb(127,127,127)",
    over: "rgb(0,0,255)"
};

// The event log (updated on each event).
var eventLog;

function initialize() {
    /// <summary>Set up the app.</summary>
    eventLog = document.getElementById("eventLog");
    target = document.getElementById("target");
    setTarget();
}

Em seguida, configuramos o objeto de destino e declaramos os vários ouvintes de eventos de ponteiro para o destino.

function setTarget() {
    /// <summary>Set up the target and interaction event handlers.</summary>

    // Initial color of target.
    target.style.backgroundColor = pointerColor.out;

    // Expando dictionary property to track active contacts. 
    // An entry is added during pointer down/hover/over events 
    // and removed during pointer up/cancel/out/lostpointercapture events.
    target.pointers = [];

    // Declare pointer event handlers.
    target.addEventListener("pointerdown", onPointerDown, true);
    target.addEventListener("pointerover", onPointerOver, true);
    target.addEventListener("pointerup", onPointerUp, true);
    target.addEventListener("pointerout", onPointerOut, true);
    target.addEventListener("pointercancel", onPointerCancel, true);
    target.addEventListener("lostpointercapture", onLostPointerCapture, true);
    target.addEventListener("pointermove", onPointerMove, true);
    target.addEventListener("wheel", onMouseWheel, false);
}

Por fim, configuramos a área de detalhes do ponteiro.

function createInfoPop(e) {
    /// <summary>
    /// Create and insert DIV into the DOM for displaying pointer details.
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>
    var infoPop = document.createElement("div");
    infoPop.setAttribute("id", "infoPop" + e.pointerId);

    // Set screen position of DIV.
    var transform = (new MSCSSMatrix()).translate(e.offsetX + 20, e.offsetY + 20);
    infoPop.style.msTransform = transform;
    target.appendChild(infoPop);

    infoPop.innerText = queryPointer(e);
}

function updateInfoPop(e) {
    /// <summary>
    /// Update pointer details in UI.
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>
    var infoPop = document.getElementById("infoPop" + e.pointerId);
    if (infoPop === null)
        return;

    // Set screen position of DIV.
    var transform = (new MSCSSMatrix()).translate(e.offsetX + 20, e.offsetY + 20);
    infoPop.style.msTransform = transform;
    infoPop.innerText = queryPointer(e);
}

Manipular eventos de ponteiro

Em seguida, usamos comentários da interface do usuário para demonstrar manipuladores de eventos de ponteiro básicos.

  • Esse manipulador gerencia um evento de contato de ponteiro (para baixo, pressionado). Adicionamos o evento ao log de eventos, adicionamos o ponteiro à matriz de ponteiros usada para rastrear os ponteiros de interesse e exibimos os detalhes do ponteiro.

    Observação  Eventos pointerdown e pointerup nem sempre ocorrem em pares. Seu aplicativo deve escutar e manipular qualquer evento que possa concluir uma ação de ponteiro para baixo (como pointerup, pointerout, pointercancel e lostpointercapture).

     

    function onPointerDown(e) {
    /// <summary>
    /// Occurs for mouse when at least one mouse button is pressed or 
    /// for touch and pen when there is physical contact with the digitizer.
    /// For input devices that do not support hover, the pointerover event is 
    /// fired immediately before the pointerdown event.  
    /// Here, we  filter pointer input based on the first pointer type detected. 
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // pointerdown and pointerup events do not always occur in pairs. 
    // Listen for and handle any event that might conclude a pointer down action 
    // (such as pointerup, pointerout, pointercancel, and lostpointercapture).
    //
    // For this example, we track the number of contacts in case the 
    // number of contacts has reached the maximum supported by the device.
    // Depending on the device, additional contacts might be ignored 
    // (PointerPressed not fired). 

    // Prevent the next handler in the hierarchy from receiving the event.
    e.cancelBubble = true;

    // Check if the number of supported contacts is exceeded.
    var touchCapabilities = new Windows.Devices.Input.TouchCapabilities();
    if ((touchCapabilities.touchPresent != 0) & (numActiveContacts > touchCapabilities.contacts)) {
        return;
    }

    // Update event details and target UI.
    eventLog.innerText += "\nDown: " + e.pointerId;
    target.style.backgroundColor = pointerColor.down;

    // Check if pointer already exists (if hover/over occurred prior to down).
    for (var i in target.pointers) {
        if (target.pointers[i].id = e.pointerId) {
            return;
        }
    }

    // Push new pointer Id onto expando target pointers array.
    target.pointers.push({ id: e.pointerId, type: e.pointerType });

    // Ensure that the element continues to receive PointerEvents 
    // even if the contact moves off the element. 
    // Capturing the current pointer can improve usability by reducing 
    // the touch precision required when interacting with an element.
    // Note: Only the assigned pointer is affected. 
    target.setPointerCapture(e.pointerId);

    // Display pointer details.
    createInfoPop(e);
}

  • Esse manipulador gerencia um evento de entrada (sobre) de ponteiro para um ponteiro que se encontra em contato e movimento dentro do limite do alvo. Adicionamos o evento ao log de eventos, adicionamos o ponteiro à matriz de ponteiros e exibimos os detalhes do ponteiro.

    Veja o evento pointermove manipulando o estado de foco de um ponteiro que não está em contato, mas está nos limites do alvo (geralmente um dispositivo de caneta/stylus).

    function onPointerOver(e) {
    /// <summary>
    /// Occurs when a pointer is detected within the hit test boundaries 
    /// of an element.
    /// Also occurs prior to a pointerdown event for devices that do not 
    /// support hover.  
    /// This event type is similar to pointerenter, but bubbles. 
    /// See the pointermove event for handling the hover state of a pointer 
    /// that is not in contact but is within the boundary of the target 
    /// (typically a pen/stylus device). 
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // Prevent the next handler in the hierarchy from receiving the event.
    e.cancelBubble = true;

    // Update event details and target UI.
    eventLog.innerText += "\nOver: " + e.pointerId;

    if (target.pointers.length === 0) {
        // Change background color of target when pointer contact detected.
        if (e.getCurrentPoint(e.currentTarget).isInContact) {
            // Pointer down occured outside target.
            target.style.backgroundColor = pointerColor.down;
        } else {
            // Pointer down occured inside target.
            target.style.backgroundColor = pointerColor.over;
        }
    }

    // Check if pointer already exists.
    for (var i in target.pointers) {
        if (target.pointers[i].id = e.pointerId) {
            return;
        }
    }

    // Push new pointer Id onto expando target pointers array.
    target.pointers.push({ id: e.pointerId, type: e.pointerType });

    // Ensure that the element continues to receive PointerEvents 
    // even if the contact moves off the element. 
    // Capturing the current pointer can improve usability by reducing 
    // the touch precision required when interacting with an element.
    // Note: Only the assigned pointer is affected. 
    target.setPointerCapture(e.pointerId);

    // Display pointer details.
    createInfoPop(e);
}

  • Esse manipulador gerencia um evento de movimentação de ponteiro. Adicionamos o evento ao log de eventos e atualizamos os detalhes do ponteiro (para focalizar, também adicionamos o ponteiro à matriz de ponteiros).

    O MSPointerHover foi substituído no Windows 8.1. Use pointermove e a propriedade de ponteiro IsInContact para determinar o to determine o estado de foco.

    Observação   Vários cliques simultâneos do botão do mouse também são processados neste manipulador. A entrada do mouse é associada a um único ponteiro atribuído quando detectada pela primeira vez. Clicar em outros botões do mouse (esquerdo, roda ou direito) durante a interação cria associações secundárias entre esses botões e o ponteiro por meio do evento de ponteiro pressionado. O evento de ponteiro liberado é disparado apenas quando o último botão associado à interação (não necessariamente o botão inicial) é liberado. Em razão dessa associação exclusiva, outro cliques em botões do mouse são roteados por meio do evento de movimento do ponteiro.

     

     function onPointerMove(e) {
     /// <summary>
     /// Occurs when a pointer moves within the hit test boundaries 
     /// of an element.
     /// </summary>
     /// <param name="e" type="Event">The event argument.</param>

     // NOTE: Multiple, simultaneous mouse button inputs are processed here.
     // Mouse input is associated with a single pointer assigned when 
     // mouse input is first detected. 
     // Clicking additional mouse buttons (left, wheel, or right) during 
     // the interaction creates secondary associations between those buttons 
     // and the pointer through the pointer pressed event. 
     // The pointer released event is fired only when the last mouse button 
     // associated with the interaction (not necessarily the initial button) 
     // is released. 
     // Because of this exclusive association, other mouse button clicks are 
     // routed through the pointer move event.  

     // Prevent the next handler in the hierarchy from receiving the event.
     e.cancelBubble = true;

     if (e.pointerType == "mouse") {
         // Mouse button states are extended PointerPoint properties.
         var pt = e.getCurrentPoint(e.currentTarget);
         var ptProperties = pt.properties;
         if (ptProperties.isLeftButtonPressed) {
             eventLog.innerText += "\nLeft button: " + e.pointerId;
         }
         if (ptProperties.isMiddleButtonPressed) {
             eventLog.innerText += "\nWheel button: " + e.pointerId;
         }
         if (ptProperties.isRightButtonPressed) {
             eventLog.innerText += "\nRight button: " + e.pointerId;
         }
     }
     // Handle hover state of a pointer that is not in contact but is within 
     // the boundary of the target (typically a pen/stylus device). 
     if (e.pointerType == "pen") {
         var pt = e.getCurrentPoint(e.currentTarget);
         if (pt.isInContact == false) {
             // Update event details and target UI.
             target.style.backgroundColor = pointerColor.hover;
             eventLog.innerText = "\nHover: " + e.pointerId;

             // Check if pointer already exists.
             for (var i in target.pointers) {
                 if (target.pointers[i].id = e.pointerId) {
                     updateInfoPop(e);
                     return;
                 }
             }

             target.pointers.push({ id: e.pointerId, type: e.pointerType });

             // Ensure that the element continues to receive PointerEvents 
             // even if the contact moves off the element. 
             // Capturing the current pointer can improve usability by reducing 
             // the touch precision required when interacting with an element.
             // Note: Only the assigned pointer is affected. 
             target.setPointerCapture(e.pointerId);
         }
     }

     // Display pointer details.
     updateInfoPop(e);
 }

  • Esse manipulador gerencia um evento de roda do mouse (rotação). Nós adicionamos o evento ao log de eventos, adicionamos o ponteiro à matriz de ponteiros (se necessário) e exibimos os detalhes do ponteiro.

    function onMouseWheel(e) {
    /// <summary>  
    /// Occurs when the mouse wheel is rotated. 
    /// </summary> 
    /// <param name="e" type="Event">The event argument.</param>
    // Check if a mouse pointer already exists.
    for (var i in target.pointers) {
        // Ensure existing pointer type registered with pointerover is mouse. 
        if (target.pointers[i].type === "mouse") {
            e.pointerId = target.pointers[i].id;
            break;
        }
    }
    eventLog.innerText += "\nMouse wheel: " + e.pointerId;
    // For this example, we fire a corresponding pointer down event.
    onPointerDown(e);
}

  • Esse manipulador gerencia um evento de partida (acima) de ponteiro. Adicionamos o evento ao log de eventos, removemos o ponteiro da matriz de ponteiros e atualizamos os detalhes do ponteiro.

    function onPointerUp(e) {
    /// <summary>
    /// Occurs for mouse at transition from at least one button pressed 
    /// to no buttons pressed.
    /// Occurs for touch and pen when contact is removed from the digitizer. 
    /// For input devices that do not support hover, the pointerout event 
    /// is fired immediately after the pointerup event.  
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // Prevent the next handler in the hierarchy from receiving the event.
    e.cancelBubble = true;

    // Update event details.
    eventLog.innerText += "\nUp: " + e.pointerId;

    // If event source is mouse pointer and the pointer is still 
    // over the target, retain pointer and pointer details.
    // Return without removing pointer from pointers dictionary.
    // For this example, we assume a maximum of one mouse pointer.
    if ((e.pointerType === "mouse") &
        (document.elementFromPoint(e.x, e.y) === target)) {
        target.style.backgroundColor = pointerColor.up;
        return;
    }

    // Ensure capture is released on a pointer up event.
    target.releasePointerCapture(e.pointerId);

    // Remove pointer from pointers dictionary.
    var targetPointers = target.pointers;
    for (var i in targetPointers) {
        if (target.pointers[i].id === e.pointerId) {
            target.pointers.splice(i, 1);
            var pointerInfoPop = document.getElementById("infoPop" + e.pointerId);
            if (pointerInfoPop === null)
                return;
            pointerInfoPop.removeNode(true);
        }
    }

    // Update target UI.
    if (target.pointers.length === 0) {
        target.style.backgroundColor = pointerColor.up;
    }
}

  • Esse manipulador gerencia um evento de partida (para fora) de ponteiro. Adicionamos o evento ao log de eventos, removemos o ponteiro da matriz de ponteiros e atualizamos os detalhes do ponteiro.

    function onPointerOut(e) {
    /// <summary>
    /// Occurs when a pointer (in contact or not) moves out of the 
    /// target hit test boundary, after a pointerup event for a device 
    /// that does not support hover, and after a pointercancel event. 
    /// This event type is similar to pointerleave, but bubbles.  
    /// Note: Pointer capture is maintained until pointer up event.
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // Prevent the next handler in the hierarchy from receiving the event.
    e.cancelBubble = true;

    // Update event details.
    eventLog.innerText += "\nPointer out: " + e.pointerId;

    // Remove pointer from pointers dictionary.
    var targetPointers = target.pointers;
    for (var i in targetPointers) {
        if (target.pointers[i].id === e.pointerId) {
            target.pointers.splice(i, 1);
            var pointerInfoPop = document.getElementById("infoPop" + e.pointerId);
            if (pointerInfoPop === null)
                return;
            pointerInfoPop.removeNode(true);

            // Update target UI.
            if (target.pointers.length === 0) {
                target.style.backgroundColor = pointerColor.out;
            }
        }
    }
}

  • Esse manipulador gerencia um evento de cancelamento de ponteiro. Adicionamos o evento ao log de eventos, removemos o ponteiro da matriz de ponteiros e atualizamos os detalhes do ponteiro.

    function onPointerCancel(e) {
    /// <summary>
    /// Occurs when a pointer is removed.
    /// The app will not receive subsequent events for that pointer, including pointerup.  
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // A pointer can be canceled as a result of one of the following:
    //    - A touch contact is canceled when a pen is detected.
    //    - More than 100ms has passed since the device reported
    //      an active contact.
    //    - The desktop is locked or the user logged off. 
    //    - The number of simultaneous contacts exceeds the number 
    //      supported by the device.
    //    - The system has determined that a pointer is unlikely to 
    //      continue to produce events (for example, due to a hardware event).
    //    - After a pointerdown event, the pointer is subsequently used to 
    //      manipulate the page viewport (for example, panning or zooming).  

    // Prevent the next handler in the hierarchy from receiving the event.
    e.cancelBubble = true;

    // Update event details.
    eventLog.innerText += "\nPointer canceled: " + e.pointerId;

    // Ensure capture is released on a pointer cancel event.
    target.releasePointerCapture(e.pointerId);

    // Update target UI.
    if (target.pointers.length === 0) {
        target.style.backgroundColor = pointerColor.cancel;
    }

    // Remove pointer from pointers dictionary.
    var targetPointers = target.pointers;
    for (var i in targetPointers) {
        if (target.pointers[i].id === e.pointerId) {
            target.pointers.splice(i, 1);
            var pointerInfoPop = document.getElementById("infoPop" + e.pointerId);
            if (pointerInfoPop === null)
                return;
            pointerInfoPop.removeNode(true);

            // Update target UI.
            if (target.pointers.length === 0) {
                target.style.backgroundColor = pointerColor.out;
            }
        }
    }
}

  • Esse manipulador gerencia um evento de captura de ponteiro perdido. Adicionamos o evento ao log de eventos, removemos o ponteiro da matriz de ponteiros e atualizamos os detalhes do ponteiro.

    Observação  lostpointercapture pode ocorrer no lugar de pointerup. A captura do ponteiro pode ser perdida devido a manipulações do usuário ou porque outro ponteiro foi capturado programaticamente, ou a captura do ponteiro atual foi propositalmente liberada.

     

    function onLostPointerCapture(e) {
    /// <summary>
    /// Occurs after pointer capture is released for the pointer.  
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // lostpointercapture can fire instead of pointerup. 

    // Pointer capture can be lost as a result of one of the following:
    //    - User interactions
    //    - Programmatic caputre of another pointer
    //    - Captured pointer was deliberately released

    // Prevent the next handler in the hierarchy from receiving the event.
    e.cancelBubble = true;

    // Update event details.
    eventLog.innerText += "\nLost pointer capture: " + e.pointerId;

    // We need the device type to handle lost pointer capture from mouse input.
    // Use the getCurrentPoint method over currentPoint property to ensure
    // the coordinate space is in relation to the target element.
    // Note: getCurrentPoint and currentPoint are only available in the 
    // local compartment, they are not available in the web compartment.
    var ptTarget = e.getCurrentPoint(e.currentTarget);
    var ptContainer = e.getCurrentPoint(document.getElementsByTagName("body")[0]);

    // If event source is mouse pointer and the pointer is still over 
    // the target, retain pointer and pointer details.
    // For this example, we assume only one mouse pointer.
    if ((ptTarget.pointerDevice.pointerDeviceType === Windows.Devices.Input.PointerDeviceType.mouse) &
        (document.elementFromPoint(ptContainer.position.x, ptContainer.position.y) === target)) {
        target.setPointerCapture(e.pointerId);
        return;
    }

    // Remove pointer from pointers dictionary.
    var targetPointers = target.pointers;
    for (var i in targetPointers) {
        if (target.pointers[i].id === e.pointerId) {
            target.pointers.splice(i, 1);
            var pointerInfoPop = document.getElementById("infoPop" + e.pointerId);
            if (pointerInfoPop === null)
                return;
            pointerInfoPop.removeNode(true);
        }
    }

    // Update target UI.
    if (target.pointers.length === 0) {
        target.style.backgroundColor = pointerColor.cancel;
    }
}

Obter as propriedades de ponteiro

A estrutura de linguagem escolhida para o seu aplicativo determina como você obtém propriedades de ponteiro. Várias propriedades são expostas diretamente por meio do objeto de evento do ponteiro. Conforme observado anteriormente, é possível obter informações adicionais do ponteiro por meio dos métodos getCurrentPoint e getIntermediatePoints ou das propriedades currentPoint e intermediatePoints de argumento do evento. Nós recomendamos o uso dos métodos getCurrentPoint e getIntermediatePoints pois você pode especificar o contexto dos dados de ponteiro.

Aqui nós consultamos diversas propriedades do ponteiro diretamente do objeto de evento e das propriedades estendidas disponíveis por meio dos objetos PointerPoint e PointerPointProperties.

function queryPointer(e) {
    /// <summary>
    /// Get extended pointer data.
    /// </summary>
    /// <param name="e" type="Event">The event argument.</param>

    // We get the extended pointer info through the getCurrentPoint method
    // of the event argument. (We recommend using getCurrentPoint 
    // to ensure the coordinate space is in relation to the target.)
    // Note: getCurrentPoint and currentPoint are only available in the 
    // local compartment, they are not available in the web compartment.

    var pt = e.getCurrentPoint(e.currentTarget);
    var ptTargetProperties = pt.properties;

    var details = "Pointer Id: " + e.pointerId;
    switch (e.pointerType) {
        case "mouse":
            details += "\nPointer type: mouse";
            details += "\nLeft button: " + ptTargetProperties.isLeftButtonPressed;
            details += "\nRight button: " + ptTargetProperties.isRightButtonPressed;
            details += "\nWheel button: " + ptTargetProperties.isMiddleButtonPressed;
            details += "\nX1 button: " + ptTargetProperties.isXButton1Pressed;
            details += "\nX2 button: " + ptTargetProperties.isXButton2Pressed;
            break;
        case "pen":
            details += "\nPointer type: pen";
            if (pt.isInContact) {
                details += "\nPressure: " + ptTargetProperties.pressure;
                details += "\nrotation: " + ptTargetProperties.rotation;
                details += "\nTilt X: " + ptTargetProperties.xtilt;
                details += "\nTilt Y: " + ptTargetProperties.ytilt;
                details += "\nBarrel button pressed: " + ptTargetProperties.isBarrelButtonPressed;
            }
            break;
        case "touch":
            details += "\nPointer type: touch";
            details += "\nPressure: " + ptTargetProperties.pressure;
            details += "\nrotation: " + ptTargetProperties.rotation;
            details += "\nTilt X: " + ptTargetProperties.xtilt;
            details += "\nTilt Y: " + ptTargetProperties.ytilt;
            break;
        default:
            details += "\nPointer type: " + "n/a";
            break;
    }
    details += "\nPointer location (target): " + e.offsetX + ", " + e.offsetY;
    details += "\nPointer location (screen): " + e.screenX + ", " + e.screenY;

    return details;
}

Confira os Tópicos relacionados no final desta página para acessar links para exemplos mais complexos.

Exemplo completo

Veja Código completo de ponteiros.

Resumo e próximas etapas

Neste Guia de início rápido, você aprendeu sobre a entrada de ponteiro em aplicativos em JavaScript.

Eventos de ponteiro são úteis para o gerenciamento de interações simples, como tocar, deslizar e outras interações específicas de dispositivo, incluindo entrada de botões secundários do mouse, roda do mouse, botão da caneta e borracha da caneta.

Para lidar com interações mais elaboradas, como os gestos descritos na linguagem de toque do Windows 8, veja Guia de Início Rápido: Gestos e Manipulações DOM, Guia de Início Rápido: Gestos Estáticos e Guia de Início Rápido: Gestos de Manipulação.

Para saber mais sobre a linguagem de toque do Windows 8, veja Design da interação por toque.

Tópicos relacionados

Desenvolvedores

Respondendo à interação do usuário

Desenvolvendo aplicativos da Windows Store (JavaScript e HTML)

Guia de início rápido: gestos e manipulações DOM

Guia de início rápido: gestos estáticos

Guia de início rápido: gestos de manipulação

Designers

Design de interação por toque