Inicio rápido: enviar una actualización de icono (HTML)

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

Nota  ¿No usas JavaScript? Consulta el tema de Inicio rápido: enviar una actualización de icono (XAML).

 

Los iconos comienzan como iconos predeterminados, que están definidos en el manifiesto y se muestran al instalar por primera vez la aplicación. Una vez instalada la aplicación, puedes cambiar el contenido de los iconos mediante notificaciones.Este inicio rápido te guía a través de los pasos para definir el contenido nuevo de un icono, enviarlo al icono y quitarlo una vez que ya no sea necesario. Estas acciones se demuestran mediante una notificación local, que es la notificación más simple de implementar. Abordamos los siguientes pasos:

• Especificar una plantilla para la notificación
• Recuperar el contenido XML en blanco de la plantilla
• Agregar texto a la notificación
• Agregar una imagen a la notificación
• Empaquetar distintas versiones de notificación para distintos tamaños de icono en una sola carga
• Establecer una fecha de expiración para la notificación
• Enviar la actualización al icono como una notificación local

Consulta esta característica como parte de nuestra serie Características de aplicaciones, de principio a fin: Interfaz de usuario de aplicaciones de la Tienda Windows, de principio a fin

Nota  En este inicio rápido, manipularás el contenido de la notificación directamente a través del Document Object Model (DOM) XML. Un enfoque opcional se encuentra disponible a través de la biblioteca NotificationsExtensions, que presenta el contenido XML como propiedades de objeto, incluido IntelliSense. Para obtener más información, consulta Inicio rápido: usar la biblioteca NotificationsExtensions en el código. Para ver el código de este inicio rápido expresado mediante NotificationsExtensions, consulta la muestra de distintivos e iconos de aplicación.

 

Requisitos previos

Para comprender este tema, necesitarás:

• Conocimientos prácticos sobre los términos y conceptos de iconos y notificaciones. Para más información, consulta el tema sobre iconos, distintivos y notificaciones.
• Estar familiarizado con el esquema XML del icono. Para más información, consulta el tema sobre el esquema de icono.
• Capacidad para crear una aplicación de la Tienda Windows con JavaScript básica mediante las API de Windows en tiempo de ejecución. Para obtener más información, consulta el tema sobre cómo crear tu primera aplicación de la Tienda Windows con JavaScript.
• Un icono predeterminado existente para la aplicación definido en el manifiesto de tu aplicación. Para más información, consulta el tema de inicio rápido: crear un icono predeterminado mediante el editor de manifiestos de Microsoft Visual Studio.
• Estar familiarizado con XML y su manipulación mediante API de Document Object Model (DOM).

Instrucciones

1. Opcional: declarar una variable de espacio de nombres

Este paso te proporciona un nombre corto para que lo uses en lugar del nombre completo del espacio de nombres. Es el equivalente de una instrucción "using" en C# o de la instrucción "Imports" en Visual Basic. Esto permite simplificar el código.

Nota  El resto del código de este inicio rápido supone que se ha declarado esta variable.

 

var notifications = Windows.UI.Notifications;

2. Seleccionar una plantilla para el icono y recuperar su contenido XML

Elige una plantilla del catálogo de plantillas proporcionado por el sistema que se ajuste a las necesidades de diseño de tu contenido. Para obtener la lista completa de plantillas, consulta la enumeración TileTemplateType. Ten en cuenta que cada notificación individual que envíes puede usar una plantilla diferente.

Este ejemplo usa la plantilla TileWide310x150ImageAndText01, que requiere una imagen y una cadena de texto. Aquí te mostramos un ejemplo:

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

El método GetTemplateContent devuelve un XmlDocument. El código anterior recupera el siguiente esqueleto XML, para el que proporcionarás detalles en los pasos siguientes a través de funciones estándar de Document Object Model (DOM).

Nota  Cuando se llama a getTemplateContent en un sistema Windows 8, devuelve una plantilla de la versión 1. Cuando se llama a este método en un sistema Windows 8.1, devuelve una plantilla de la versión 2 o una plantilla de la versión 3 en el caso de plantillas solo para Windows Phone. Si una aplicación especifica compatibilidad con Windows 8 en su manifiesto, este método devuelve una plantilla de la versión 1, independientemente de la versión de Windows. En este tema usaremos una plantilla de la versión 2.

 

<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>

3. Proporcionar contenido de texto para la notificación

Este código primero recupera todos los elementos de la plantilla cuyo nombre de etiqueta es "text". La plantilla TileWide310x150ImageAndText01 contiene una sola cadena de texto que el código luego asigna. Esta cadena puede ajustarse sobre un máximo de dos líneas y la longitud de la cadena debe establecerse en consecuencia para evitar que se trunque.

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

4. Proporcionar una imagen para la notificación

Este código primero recupera todos los elementos de la plantilla cuyo nombre de etiqueta es "image". La plantilla TileWide310x150ImageAndText01 contiene una sola imagen. Ten en cuenta que no todas las plantillas de icono contienen imágenes. Algunas solo contienen texto.

Importante  La imagen "redWide.png" que se usa aquí solo es un ejemplo y no se incluye en un proyecto de Microsoft Visual Studio. Tendrás que reemplazar "redWide.png" por el nombre de una imagen real de tu propiedad que hayas agregado al proyecto antes de intentar enviar esta notificación. Si no lo haces, la notificación no se entregará.

 

var tileImageAttributes = tileXml.getElementsByTagName("image");

Pueden usarse imágenes del paquete de la aplicación, del almacenamiento local de la aplicación o de la Web. Se muestran versiones de este paso para cada origen de imagen. En una notificación de icono que contiene varias imágenes, los elementos de imagen pueden usar cualquier combinación de esos tipos de origen de imagen. Las imágenes usadas en las plantillas deben tener un tamaño inferior a 200 KB y contener menos de 1024 x 1024 píxeles. Para más información, consulta el tema sobre los tamaños de las imágenes de iconos y notificaciones del sistema.

El siguiente código usa una imagen local del paquete de la aplicación. Este tipo de imagen se incluye en el archivo de solución de Visual Studio y se empaqueta como parte de la aplicación. Se accede a estas imágenes con el prefijo "ms-appx:///". Como procedimiento recomendado, también asignamos texto alternativo opcional por motivos de accesibilidad, como lectores de pantalla.

tileImageAttributes[0].setAttribute("src", "ms-appx:///images/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

El siguiente código usa una imagen local del almacenamiento local de la aplicación. La aplicación guarda este tipo de imagen en su almacenamiento local. Esta es la ubicación devuelta por Windows.Storage.ApplicationData.current.localFolder. Se accede a estas imágenes con el prefijo "ms-appdata:///local/". Como lo hicimos anteriormente, también asignamos texto alternativo opcional por motivos de accesibilidad, como lectores de pantalla.

tileImageAttributes[0].setAttribute("src", "ms-appdata:///local/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

El siguiente código usa una imagen web. Se accede a estas imágenes con el protocolo "http://" o "https://" para especificar la ruta de acceso de la imagen. Ten en cuenta que tu aplicación debe tener la funcionalidad internetClient declarada en su manifiesto para poder usar imágenes web.

tileImageAttributes[0].setAttribute("src", "https://www.contoso.com/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

Puedes usar el atributo baseUri opcional para especificar una ruta de acceso raíz, como "https://www.microsoft.com/", que esté combinada con cualquier Identificador uniforme de recursos (URI) relativo especificado en los atributos src de las imágenes. Este atributo se puede establecer en el elemento visual (para aplicarlo a toda la notificación) o en el elemento binding (para aplicarlo a ese enlace). Si baseUri se establece en ambos, el valor de binding invalida el valor de visual.

Si baseUri se estableciera en "https://www.contoso.com/", esta línea en el código de ejemplo:

tileImageAttributes[0].setAttribute("src", "https://www.contoso.com/redWide.png");

se podría acortar así:

tileImageAttributes[0].setAttribute("src", "redWide.png");

5. Incluir enlaces de notificación para varios tamaños de icono en la carga

El usuario puede cambiar el tamaño del icono en cualquier momento en la pantalla Inicio y no hay manera de saber en qué estado se encuentra el icono (pequeño, mediano, ancho o grande) cuando envías una notificación. Si el tamaño del icono no tiene un enlace de plantilla coincidente en tu notificación, esta no se mostrará. Por tanto, el procedimiento recomendado es incluir siempre versiones de la notificación en la carga para todos los tamaños de iconos dinámicos (mediano, ancho grande) para los que has suministrado una imagen de logotipo en el manifiesto.

Nota  A partir de Windows Phone 8.1, los iconos grandes no son compatibles en los teléfonos.

Este ejemplo define una notificación de tamaño mediano y solo texto mediante la misma cadena de texto que usamos en la notificación ancha.

       
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

Después, agrega el icono mediano a la carga del icono ancho. Recupera el elemento binding que define el icono mediano en la carga squareTileXml. Anexa ese elemento binding como elemento del mismo nivel del icono ancho.

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

Los pasos anteriores dan como resultado dos elementos binding debajo de un solo elemento visual en la carga XML, como se muestra a continuación:

<tile>
    <visual visual="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png"/>
            <text id="1">Hello World! My very own tile notification</text>
        </binding>

        <binding template="TileSquare150x150Text04" fallback="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>

6. Crea la notificación basada en el contenido XML que has especificado

var tileNotification = new notifications.TileNotification(tileXml);

7. Establece una fecha de expiración para la notificación

De manera predeterminada, las notificaciones de icono y distintivo locales no expiran y las notificaciones programadas, periódicas y de inserción expiran después de tres días. Es un procedimiento recomendado establecer una hora de expiración, especialmente en las notificaciones de icono y distintivo locales, que tenga sentido para tu aplicación. El contenido del icono no debe persistir por más tiempo del relevante. En este caso, la notificación expirará y se quitará del icono en diez minutos.

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

8. Envía la notificación al icono de la aplicación.

notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

9. Opcional: borrar la notificación de icono

Este ejemplo muestra cómo borrar una notificación de icono mediante una llamada local. Ten en cuenta que si el contenido está controlado por tiempo, te recomendamos que establezcas una hora de expiración en la notificación en lugar de borrarla explícitamente. La siguiente línea de código borra la notificación actual del icono de la aplicación.

notifications.TileUpdateManager.createTileUpdaterForApplication().clear();

En un icono con la cola de notificaciones habilitada y con notificaciones en cola, la cola se vacía cuando se llama al método clear.

Ten en cuenta que no puedes borrar una notificación desde la nube. Una llamada local al método clear borrará el icono independientemente del origen de sus notificaciones, pero las notificaciones periódicas o de inserción solo pueden actualizar el icono con contenido nuevo.

Resumen y siguientes pasos

En este inicio rápido, definiste y enviaste nuevo contenido al icono de tu aplicación a través de una notificación, que luego quitaste al cabo de 10 minutos. El siguiente código resume los pasos anteriores, desde la elección de una plantilla hasta el envío de la notificación. Usa una imagen del paquete de la aplicación.

Para probar este código en una muestra propia, colócalo en una función desencadenada por un botón en la interfaz de usuario de la muestra. Por ejemplo, podrías colocar el botón en el archivo default.html. Recuerda sustituir el nombre por el de una imagen real.

var notifications = Windows.UI.Notifications;

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///assets/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

var tileNotification = new notifications.TileNotification(tileXml);

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

Ahora que has realizado tu primera actualización de icono, puedes habilitar una cola de notificaciones para expandir la funcionalidad del icono.

Este inicio rápido envió la actualización de icono como una notificación local. También puedes explorar los otros métodos de entrega de notificaciones: programadas, periódicas y de inserción. Para más información, consulta el tema sobre la entrega de notificaciones.

Temas relacionados

Muestra de distintivos e iconos de aplicación

Tamaños de las imágenes de iconos y notificaciones del sistema

Introducción a los iconos y a las notificaciones de icono

Directrices y lista de comprobación de iconos

Cómo programar una notificación de icono

Inicio rápido: Configurar notificaciones periódicas

Inicio rápido: crear un icono predeterminado con el editor de manifiestos de Visual Studio

Catálogo de plantillas de icono

Esquema XML de un icono

Windows.UI.Notifications