Inicio rápido: agregar estilos y controles de WinJS (HTML)

Artículo
03/04/2016

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows Runtime. Si estás desarrollando para Windows 10, consulta la documentación más reciente ]

La Biblioteca de Windows para JavaScript (WinJS) ofrece una infraestructura de gran calidad, como controles de página, compromisos y enlaces de datos, embellecida con características de interfaz de usuario como la virtualización de colecciones y controles de Windows de alto rendimiento, como ListView, FlipView y SemanticZoom.

Puedes usar WinJS en las aplicaciones de Windows en tiempo de ejecución en tus sitios web y con las tecnologías de aplicación basadas en HTML como Apache Cordova.

Puedes ver esta característica en acción en nuestra serie Características de aplicaciones, de principio a fin: Interfaz de usuario de aplicación de la Tienda Windows, de principio a fin.

Requisitos previos

Damos por hecho que sabes crear una aplicación de la Tienda Windows básica con JavaScript que use la plantilla de WinJS. Para obtener ayuda para crear tu primera aplicación, consulta Crear la primera aplicación de la Tienda Windows con JavaScript.
Se supone que sabes cómo administrar eventos en una aplicación de la Tienda Windows mediante JavaScript. Para conocer la mejor manera de administrar eventos, consulta Inicio rápido: Agregar controles HTML y administrar eventos.

¿Qué es la biblioteca de Windows para JavaScript?

WinJS es una biblioteca de archivos CSS y JavaScript que contiene objetos JavaScript, organizados en espacios de nombres, que están diseñados para facilitar la programación de aplicaciones de aspecto excelente. WinJS incluye objetos que sirven para controlar la activación, acceder al almacenamiento y definir tus propias clases y espacios de nombres.

Para obtener una lista completa de controles ofrecidos por WinJS, consulta la lista de controles.
WinJS también proporciona características de estilo en forma de clases y estilos CSS que puedes usar o invalidar (la aplicación de estilos a controles se describe en Inicio rápido: Aplicar estilos a controles).

Agregar la biblioteca de Windows para JavaScript a tu página

Para usar la versión más reciente de WinJS en tu aplicación o sitio web:

Descarga la versión más reciente de Descargar WinJS y cópiala en el directorio de la aplicación o el sitio web.
Agrega referencias de script y CSS de WinJS a cada página de la aplicación o del sitio web que use funciones de WinJS.

En este ejemplo se muestra el aspecto de estas referencias de una aplicación que tiene sus archivos de WinJS en su directorio raíz.

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

Agregar un control de WinJS en el marcado

A diferencia de los controles HTML, los controles de WinJS no tienen elementos de marcado dedicados; así, por ejemplo, no puedes agregar un elemento <rating /> para crear un control Rating. Para agregar un control de WinJS, crea un elemento div y usa el atributo data-win-control para especificar el tipo de control que quieras. Para agregar un control Rating, establece el atributo en "WinJS.UI.Rating".

También debes llamar a la función WinJS.UI.processAll en el código de JavaScript. WinJS.UI.processAll analiza el marcado y crea instancias de cualquier control que encuentre de WinJS.

En el siguiente conjunto de ejemplos se muestra cómo agregar un control de WinJS a un proyecto creado con la plantilla Aplicación vacía. El ejemplo es más fácil de seguir si creas un nuevo proyecto Aplicación vacía.

Hh465493.wedge(es-es,WIN.10).gif Para crear un nuevo proyecto mediante la plantilla Aplicación vacía

Inicia Microsoft Visual Studio.
En la pestaña Página de inicio, haz clic en Nuevo proyecto. Se abre el cuadro de diálogo Nuevo proyecto.
En el panel Instalado, expande JavaScript y haz clic en el tipo de plantilla Aplicación de la Tienda Windows. Las plantillas de proyecto instaladas para JavaScript se muestran en panel central del cuadro de diálogo.
En el panel central, selecciona la plantilla de proyecto Aplicación vacía.
En el cuadro de texto Nombre, escribe un nombre para el proyecto.
Haz clic en Aceptar para crear el proyecto. Esto puede tardar unos minutos.

Hh465493.wedge(es-es,WIN.10).gif Para agregar un control de WinJS

Crea un elemento div donde quieras colocar el control. Establece su atributo data-win-control en el nombre completo del control que quieras crear. En este ejemplo, se crea un control Rating en la página de inicio de la aplicación (el archivo 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>

El código de JavaScript debe llamar a WinJS.UI.processAll para inicializar el control Rating que creaste en el paso anterior. Si estás usando la plantilla Aplicación vacía, el archivo default.js ya incluye una llamada a 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();
})();

Si no vas a usar la plantilla Aplicación vacía o si vas a agregar el control a una página que has creado tú mismo, es posible que necesites agregar una llamada a WinJS.UI.processAll.

Si agregaste el control a la página principal de la aplicación (que suele ser el archivo default.html), agrega una llamada a WinJS.UI.processAll en el controlador de eventos onactivated, como se muestra en el ejemplo anterior.
Si agregaste el control a un control Page, no necesitas agregar una llamada a WinJS.UI.processAll porque el control Page lo hace automáticamente.
Si agregaste el control a otra página distinta de la página principal de la aplicación, controla el evento DOMContentLoaded y usa el controlador para llamar a WinJS.UI.processAll.
```
function initialize() {
    WinJS.UI.processAll();
}

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

La función WinJS.UI.processAll procesa el documento y activa cualquier control de WinJS que hayas declarado en el marcado.

Cuando ejecutas la aplicación, el control Rating aparece en el lugar donde colocaste el elemento host div.

Un control rating

Establecer las propiedades de un control de WinJS en el marcado

Cuando creas un control HTML, puedes establecer sus propiedades mediante atributos dedicados. Por ejemplo, para establecer las propiedades type, min y max de un control input, puedes establecer los atributos type, min y max en el marcado:

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

A diferencia de los controles HTML, los controles de WinJS no tienen etiquetas dedicadas de atributo o elemento; así, por ejemplo, no podrías crear un control Rating y establecer sus propiedades con este marcado:

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

En su lugar, usa el atributo data-win-options para establecer una propiedad en el marcado. Toma una cadena que contiene uno o varios pares propiedad/valor:

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

En este ejemplo se establece la maxRating de un control Rating en 10.

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

Cuando ejecutas la aplicación, el control Rating tiene este aspecto:

El control Rating muestra un sistema de clasificación de 10 estrellas.

Para establecer más de una propiedad, sepáralas con comas:

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

En el ejemplo siguiente se establecen dos propiedades del control Rating.

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

Cuando ejecutas la aplicación, el control Rating tiene ahora este aspecto:

El control Rating muestra una clasificación de 6 de 10 estrellas.

Si el valor de la propiedad es una cadena en sí, inclúyela en un tipo de comillas (' o ") que sean distintas a las usadas para establecer el atributo data-win-options. En este ejemplo se muestra cómo establecer la propiedad current del control TimePicker, que toma una cadena:

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

Un control TimePicker muestra la hora en 10:29 A.M.

Para averiguar si una propiedad es compatible con un determinado control de WinJS, consulta su página de referencia.

Recuperar un control que creaste en el marcado

También puedes establecer las propiedades de un control de WinJS mediante programación. Para acceder al control en el código, recupera el elemento host y usa su propiedad winControl para recuperar el control. En los ejemplos anteriores, el elemento host del control Rating es "ratingControlHost".


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

En algunos casos, es posible que quieras recuperar y manipular el control tan pronto como esté disponible. Asegúrate de que el método WinJS.UI.processAll es asincrónico, para que cualquier código que siga se pueda ejecutar antes de que se complete WinJS.UI.processAll. Por este motivo, no intentes manipular inmediatamente el control porque podría no estar disponible:


WinJS.UI.processAll();

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

El WinJS.UI.processAll devuelve un objeto WinJS.Promise que puedes usar para llamar a la función cuando el método WinJS.UI.processAll se complete. En este ejemplo se define la función de acabado que recupera el control y establece su averageRating en 3.


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

En la sección siguiente se describe cómo agregar escuchas de eventos a un control de WinJS.

Administrar eventos para controles de WinJS

Al igual que con los controles HTML, la mejor manera de adjuntar escuchas de eventos para los controles de WinJS es usar la función addEventListener. Sin embargo, el proceso para recuperar un control de WinJS es algo distinto que el de recuperar un control HTML.

Para administrar un evento:

En JavaScript, recupera el elemento host del control y usa su propiedad winControl para recuperar el control.
Llama a la función addEventListener del control y especifica un evento y un controlador de eventos.

En el ejemplo siguiente se muestra cómo administrar el evento change de un control Rating.

Hh465493.wedge(es-es,WIN.10).gif Para administrar el evento change de un control rating

En el archivo HTML, agrega un párrafo y asígnale el identificador "outputParagraph". Los resultados de la escucha de eventos se obtendrán en este párrafo.

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

En JavaScript, crea una función de controlador de eventos denominada ratingChanged que tome un parámetro. En el ejemplo siguiente se crea un controlador de eventos que muestra las propiedades y los valores incluidos en el objeto de eventos.


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

    }

Usa la propiedad winControl para recuperar el control de su elemento host y llama a la función addEventListener para agregar el controlador de eventos. En este ejemplo se recupera el control tan pronto como se crea y se agrega el controlador 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); 
            }));
        }
    };

Cuando ejecutes la aplicación y cambies la clasificación, se creará una lista de valores y propiedades de información del evento.

El resultado del evento change.

Agregar un control de WinJS en el código

En los ejemplos anteriores hemos explicado cómo crear y manipular un control de la biblioteca de WinJS creado en el marcado, pero también puedes crear un control de WinJS usando código de JavaScript.

Hh465493.wedge(es-es,WIN.10).gif Para crear un control de WinJS en el código

En el marcado, crea un elemento que hospede el control.
```
<div id="hostElement"></div>
```
En el código (preferiblemente en el controlador de eventos DOMContentLoaded), recupera el elemento host.
```
var hostElement = document.getElementById("hostElement");
```
Para crear tu control, llama a su constructor y pasa el elemento host al constructor. Este ejemplo crea un control Rating:
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
Cuando ejecutes el programa, se mostrará el Rating que creaste:

No es necesario llamar a WinJS.UI.processAll, basta con llamar a WinJS.UI.processAll cuando crees un control de WinJS en el marcado.

Resumen y pasos siguientes

Has aprendido a crear controles de WinJS, a configurar sus propiedades y a adjuntar controladores de eventos.

En el siguiente tema, Inicio rápido: Aplicar estilos a controles, se describe cómo usar las hojas de estilo CSS y las funcionalidades de aplicación de estilo mejoradas de las aplicaciones de la Tienda Windows con JavaScript. Para obtener más información sobre los controles específicos, consulta los temas sobre la lista de controles y los controles por función.