Idioma: HTML | XAML

Inicio rápido: enviar una notificación del sistema (HTML)

Applies to Windows and Windows Phone

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

Una notificación del sistema es una interfaz de usuario emergente que aparece en la pantalla y que permite que la aplicación se comunique con el usuario cuando este se encuentra en otra aplicación, en la pantalla Inicio o, en el caso de Windows, en el escritorio. Este inicio rápido te guía por los pasos para definir y mostrar una notificación del sistema. 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
  • Configurar una duración para la notificación
  • Especificar audio para anexarlo a la notificación
  • Proporcionar la información contextual que se usa cuando la notificación activa la aplicación
  • Enviar la notificación del sistema como una notificación local
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 notificaciones del sistema.
Nota  Cuando pruebes la funcionalidad del código de las notificaciones del sistema con Microsoft Visual Studio, debes usar la opción de depuración Equipo local o Equipo remoto en un equipo con Windows x86, x64 o Windows en tiempo de ejecución. No puedes usar la opción de función de depuración del simulador de Visual Studio porque tu código se compilará y se ejecutará en el simulador, pero la notificación del sistema no aparecerá.

Requisitos previos

Para comprender este tema, necesitarás:

  • Conocimientos prácticos sobre los términos y conceptos relacionados con las notificaciones del sistema. Para más información, consulta el tema de introducción a las notificaciones del sistema.
  • La opción Compatibilidad con notificaciones del sistema debe establecerse en "true" en el manifiesto de la aplicación ("Sí" en el editor de manifiestos de Visual Studio) para poder enviar o recibir notificaciones del sistema. Para más información, consulta Cómo elegir recibir notificaciones del sistema.
  • Estar familiarizado con XML y su manipulación mediante API de Document Object Model (DOM).
  • Estar familiarizado con el esquema XML de la notificación del sistema. Para más información, consulta el tema sobre el esquema de notificaciones del sistema.
  • 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.

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 la notificación del sistema y recuperar su contenido XML

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

  • Applies to Windows Phone

Windows Phone 8.1 admite únicamente una variante de la plantilla toastText02. Acepta dos cadenas de texto, con la primera mostrada como texto en negrita, pero ambas están en la misma línea, con lo cual conviene usar solo una cadena corta o dos muy cortas para evitar las concatenaciones.

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

ToastImageAndText01



var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.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):



<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. Proporcionar contenido de texto para la notificación

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


   
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));

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". Una plantilla de notificación del sistema, como toastImageAndText01, contiene una imagen como máximo. Ten en cuenta que no todas las plantillas de notificación del sistema contienen imágenes, sino que algunas solo contienen texto.



var toastImageElements = toastXml.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. Las imágenes 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.

Importante  La imagen "redWide.png" usada aquí es solo un ejemplo y no está incluida en ningún proyecto de Microsoft Visual Studio. Deberás reemplazar "redWide.png" por el nombre de una imagen real tuya que hayas agregado al proyecto antes de intentar enviar esta notificación del sistema.


toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[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.



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

El siguiente código usa una imagen web. Se accede a estas imágenes con el protocolo "http://" para especificar la ruta de acceso de la imagen. También puedes usar el protocolo "https://".



toastImageElements[0].setAttribute("src", "http://www.microsoft.com/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

Puedes usar el atributo baseUri opcional para especificar una ruta de acceso raíz, como "http://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 "http://www.microsoft.com/", esta línea en el código de ejemplo:


toastImageElements[0].setAttribute("src", "http://www.microsoft.com/redWide.png");

se podría acortar así:


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

5. Opcional: especificar la duración de una notificación del sistema

De forma opcional, puedes establecer una duración para mostrar la notificación del sistema. Hay dos valores: "short" (valor predeterminado) y "long". Usa "long" solo si tu notificación forma parte de un escenario tal como una llamada entrante o un aviso de cita. Para más información, consulta el tema de introducción a las notificaciones del sistema.

  • Applies to Windows Phone

En Windows Phone 8.1 no se admiten varias duraciones: todas las notificaciones del sistema deben durar lo mismo. Si este atributo se incluye en una notificación del sistema del teléfono, se omitirá.

Nota  La duración predeterminada es "short", de modo que normalmente agregarías este atributo solamente para establecer la duración en "long".


var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");

6. Opcional: especificar el audio de la notificación del sistema

De manera predeterminada, Windows reproduce un breve sonido cuando se muestra la notificación del sistema. Tienes la opción de especificar otro sonido de un conjunto de sonidos proporcionados por el sistema, o bien puedes optar por no usar ninguno. En Windows Phone 8.1, puedes especificar un sonido personalizado. Para obtener más información, consulta el Catálogo de opciones de audio de notificaciones del sistema.

Una pantalla recuperada por medio de getTemplateContent no contiene un elemento audio, por lo que debes definirlo y agregarlo a la carga útil XML. El archivo de sonido se especifica mediante el prefijo "ms-winsoundevent:", o bien, en Windows Phone 8.1, una ruta de acceso que usa el prefijo "ms-appx:///" o "ms-appdata:///". En este ejemplo se crea un elemento audio y se selecciona el elemento toast que será su elemento primario.



var toastNode = toastXml.selectSingleNode("/toast");                        
var audio = toastXml.createElement("audio");

Este ejemplo especifica un sonido no predeterminado.


audio.setAttribute("src", "ms-winsoundevent:Notification.IM");

Este ejemplo especifica que no debe reproducirse ningún sonido.


audio.setAttribute("silent", "true");

En el caso de una notificación del sistema de larga duración, el sonido puede repetirse en bucle en lugar de reproducirse solo una vez. Ten en cuenta que el audio en bucle solo es válido para las notificaciones del sistema de larga duración. En el conjunto de sonidos definidos por el sistema se incluyen los sonidos específicos que pueden usarse en bucle. Este ejemplo especifica un bucle de sonido.

  • Applies to Windows Phone

Como no admite notificaciones del sistema de larga duración, Windows Phone 8.1 no admite audio en bucle.



toastNode.setAttribute("duration", "long");

var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.setAttribute("loop", "true");

Una vez definido tu elemento de audio, debes anexarlo a la carga XML de tu notificación del sistema como elemento secundario de toast, como se muestra aquí.


toastNode.appendChild(audio);

7. Especifica los parámetros de inicio de la aplicación

Cuando el usuario hace clic en la notificación del sistema, espera que la aplicación se inicie, con una vista relacionada con el contenido de la notificación. Para realizar esto, usa el atributo de launch del elemento de la notificación del sistema, el cual proporciona una cadena que pasa de la notificación del sistema a la aplicación cuando la aplicación se inicia a través de la notificación del sistema. La cadena no tiene una forma específica y está definida por la aplicación. La aplicación debe comprobar esa cadena como un argumento cada vez que se activa, ajusta la vista u operación en consecuencia.



toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

  • Applies to Windows Phone

En Windows Phone Silverlight 8.1, el valor de la cadena de inicio se anexa al URI de la página de inicio predeterminada. Por ejemplo, si proporcionas la cadena de inicio "?conversation= 71", da como resultado un URI como /MainPage.xaml?conversation=71. Por lo tanto, la cadena de inicio también debe ser una cadena de consulta válida; de lo contrario, se emite una excepción.

8. Crea la notificación del sistema basada en el contenido XML que has especificado.


var toast = new notifications.ToastNotification(toastXml);

9. Envía la notificación del sistema.


 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

  • Applies to Windows Phone

En Windows Phone Silverlight 8.1, no se muestra una notificación del sistema si la aplicación en primer plano actual es el autor de la llamada del método ToastNotifier.Show. En ese caso, la notificación del sistema debe usarse principalmente por un agente en segundo plano.

  • Applies to Windows

Nota:  El color de fondo que se aplica a la notificación del sistema es el color de fondo declarado por el icono de la aplicación en el manifiesto de la aplicación. Si quieres obtener más información, consulta Inicio rápido: crear un icono predeterminado con el editor de manifiestos de Visual Studio.

Resumen y siguientes pasos

En este inicio rápido, enviaste la notificación del sistema local al usuario.

Este inicio rápido envió la notificación del sistema como una notificación local, lo que hace que sea el tipo de notificación más simple de implementar y te permite ver los resultados rápidamente. También deberías explorar los otros métodos de entrega de notificaciones del sistema: programadas y de inserción. Para más información, consulta el tema sobre la entrega de notificaciones.

Temas relacionados

Muestras
Muestra de notificaciones del sistema
Ejemplo de envío de notificaciones del sistema de aplicaciones de escritorio
Escenarios de características de muestra de Reversi: notificaciones del sistema
Conceptos
Introducción a las notificaciones del sistema
El catálogo de plantillas de notificaciones del sistema
El catálogo de opciones de audio de notificaciones del sistema
Instrucciones
Inicio rápido: envío de una notificación de inserción
Cómo gestionar la activación desde una notificación del sistema
Cómo optar por recibir notificaciones del sistema
Cómo programar una notificación del sistema
Inicio rápido: envío de una notificación del sistema del escritorio
Cómo habilitar notificaciones del sistema de escritorio a través de AppUserModelID
Procedimientos recomendados
Directrices y lista de comprobación de notificaciones del sistema
Referencia
Esquema de notificaciones del sistema XML
ToastNotification
ToastNotificationManager
ToastNotifier

 

 

Mostrar:
© 2015 Microsoft