Compartilhar via


Guia de início rápido: adicionando classificações (HTML)

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

Use o controle Rating para deixar que o usuário avalie algo clicando em um ícone que representa uma classificação. Este guia de início rápido mostra como adicionar o controle de classificações ao seu aplicativo da Windows Store em JavaScript.

Pré-requisitos

Nós supomos que você possa criar um aplicativo da Windows Store básico em JavaScript que use controles WinJS. Para aprender a usar os controles WinJS, veja Guia de início rápido: adicionando controles e estilos WinJS.

Criar um controle de classificações

Para criar um controle Rating, crie um elemento div e defina a propriedade data-win-control como "WinJS.UI.Rating". Aqui está um exemplo de como criar um controle de classificações básico:

<div id="ratingControl" data-win-control="WinJS.UI.Rating"></div>

Observação  Para que o controle seja instanciado, a sua página deve incluir arquivos JavaScript WinJS, e você deve chamar a função WinJS.UI.processAll em seu code-behind. Para saber mais, veja Guia de início rápido: adicionando controles e estilos WinJs.

 

Definindo a classificação média e a classificação máxima

A propriedade averageRating especifica a classificação média do item sendo classificado. (Como você determina a classificação média para o item depende de você). Se você definir a propriedade averageRating, o controle Rating a exibe até que o usuário selecione a sua própria classificação. O exemplo a seguir define a averageRating como 3,4.

<div id="ratingControl" data-win-control="WinJS.UI.Rating"
    data-win-options="{averageRating : 3.4}"></div>

A propriedade maxRating especifica a classificação máxima possível. O valor padrão é 5. O exemplo em seguida define maxRating como 7; quando o controle é exibido, ele mostra 7 estrelas em vez de 5.

<div id="ratingControl" data-win-control="WinJS.UI.Rating"
    data-win-options="{averageRating : 3.4, maxRating : 7}"></div>

Obtendo a classificação de um usuário

Quando o usuário escolher uma classificação, ele dispara o evento change. Você pode obter a classificação do usuário com o valor da propriedade userRating.

Este exemplo usa o manipulador de evento ativado da página inicial para adicionar um manipulador de evento change ao controle Rating. (Para saber mais sobre o melhor lugar para anexar eventos, veja Guia início rápido: adicionando controles e manipulando eventos.)

(function () {
    "use strict";

    var app = WinJS.Application;

    // This function responds to all application activations.
    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            // TODO: Initialize your application here.
            WinJS.UI.processAll()
            .done(function () {

                // Get the rating control
                var ratingControl = document.getElementById("ratingControl").winControl;

                ratingControl.addEventListener("change", changeRating);
            });
        }
    };

    app.start();
})();

A função de manipulador de evento do exemplo, changeRating, recupera a classificação do usuário e a armazena.

    function changeRating(ev) {
        var ratingControl = ev.target.winControl;
        if (ratingControl) {

            if (ratingControl.userRating != 0) {

                // Put your code here to save user rating and re-calculate average rating.
                WinJS.Application.sessionState.userRating = ratingControl.userRating;

                var appData = Windows.Storage.ApplicationData.current;
                var roamingValues = appData.roamingSettings.values;

                // Write a setting
                roamingValues.insert("userRating", ratingControl.userRating);
            } else {

                // Put your code here to delete user rating.
            }
        }
    }

O exemplo a seguir modifica o manipulador de evento ativado mostrado anteriormente para que ele recupere a classificação do usuário armazenada e use-a para definir o controle Rating.

(function () {
    "use strict";

    var app = WinJS.Application;

    // This function responds to all application activations.
    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            // TODO: Initialize your application here.
            WinJS.UI.processAll()
            .done(function () {

                // Get the rating control
                var ratingControl = document.getElementById("ratingControl").winControl;

                // Retrieve stored state info 
                var appData = Windows.Storage.ApplicationData.current;
                var roamingValues = appData.roamingSettings.values;

                // Read a setting
                var currentRating = parseFloat(roamingValues.lookup("userRating"));

                if (currentRating > 0) {
                    ratingControl.userRating = currentRating;
                }

                ratingControl.addEventListener("change", changeRating);
            });
        }
    };

    function changeRating(ev) {
        var ratingControl = ev.target.winControl;
        if (ratingControl) {

            if (ratingControl.userRating != 0) {

                // Put your code here to save user rating and re-calculate average rating.
                WinJS.Application.sessionState.userRating = ratingControl.userRating;

                var appData = Windows.Storage.ApplicationData.current;
                var roamingValues = appData.roamingSettings.values;

                // Write a setting
                roamingValues.insert("userRating", ratingControl.userRating);
            } else {

                // Put your code here to delete user rating.
            }
        }
    }

    app.start();
})();

Resumo e próximas etapas

Você aprendeu como criar um controle Rating e como armazenar e recuperar o seu userRating. Em seguida, saiba como usar melhor o controle de classificações lendo Diretrizes e lista de verificação de controles de classificações.

Tópicos relacionados

WinJS.UI.Rating