Início rápido: enviando uma notificação do sistema (HTML)

Artigo
12/12/2015

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

Observação Não está usando JavaScript? Consulte Início rápido: enviando uma notificação do sistema (XAML).

Notificação do sistema é uma interface do usuário pop-up que aparece na tela para permitir que seu aplicativo se comunique com o usuário quando o usuário está em outro aplicativo, na tela inicial ou, no caso do Windows, na área de trabalho. Este Guia de início rápido orienta você pelas etapas para definir e exibir o conteúdo da notificação do sistema. Estas ações são demonstradas por meio de uma notificação local, que é a notificação mais simples para implementação. Discutiremos as seguintes etapas:

Especificando um modelo para a sua notificação
Recuperando o conteúdo XML em branco do modelo
Adicionando texto à notificação
Adicionando uma imagem à notificação
Definindo a duração da sua notificação
Especificando áudio para acompanhar a notificação
Inserindo informações contextuais usadas quando o aplicativo é ativado pela notificação
Enviando sua notificação do sistema como uma notificação local

Observação Neste Guia de início rápido, você vai manipular o conteúdo de notificações diretamente pelo DOM (Document Object Model) XML. Uma abordagem opcional está disponível por meio da biblioteca NotificationsExtensions, que apresenta o conteúdo XML como propriedades de objetos, incluindo o Intellisense. Para saber mais, veja Guia de início rápido: usando a biblioteca NotificationsExtensions em seu código. Para ver o código expresso com o uso de NotificationsExtensions neste Guia de início rápido, veja a Exemplo de notificações do sistema.

Observação Quando testar a funcionalidade do código de notificação do sistema por meio do Microsoft Visual Studio, você deve usar a configuração de depuração da Máquina Local ou Máquina Remota em uma máquina Windows x86, x64 ou Tempo de Execução do Windows. Não é possível usar a opção da função de depuração do Visual Studio Simulator—seu código compilará e executará no Simulador, mas a notificação do sistema não aparecerá.

Pré-requisitos

Para compreender este tópico, você precisa de:

Um conhecimento prático dos termos e conceitos de notificações do sistema. Para saber mais, confira a Visão geral das notificações do sistema.
A opção Toast Capable (Capacidade de Notificação do Sistema) deve ser definida como "true" (verdadeira) no manifesto do aplicativo ("Yes" (Sim) no editor de manifesto do Visual Studio) para enviar ou receber notificações do sistema. Para saber mais, veja Como aceitar notificações do sistema.
Familiaridade com o XML e sua manipulação por meio de APIs DOM (Document Object Model).
Familiaridade com o esquema XML de notificação do sistema. Para saber mais, veja Esquema de notificações do sistema.
A capacidade de criar um aplicativo da Windows Store básico com JavaScript usando as APIs do Tempo de Execução do Windows. Para saber mais, veja Criar o seu primeiro aplicativo da Windows Store em JavaScript.

Instruções

1. Opcional: declarar uma variável de namespace

Esta etapa fornece a você um nome abreviado para uso no lugar do nome completo do namespace. Isso equivale à instrução "using" em C# ou à instrução "Imports" no Visual Basic. Permite simplificar seu código.

Observação O restante do código neste Guia de início rápido presume que essa variável tenha sido declarada.


var notifications = Windows.UI.Notifications;

2. Escolher um modelo para a notificação do sistema e recuperar seu conteúdo XML

Escolha um modelo no catálogo de modelos fornecido pelo sistema que corresponda às necessidades do seu conteúdo. Para ver a lista completa de modelos, confira a enumeração ToastTemplateType. Observe que cada notificação separada que você envia pode usar um modelo diferente.

Observação Apenas uma variação do modelo toastText02 é suportada no Windows Phone 8.1. Ele aceita duas cadeias de caracteres de texto, com a primeira renderizada em texto em negrito; no entanto, as duas estão na mesma linha, portanto somente uma cadeia de caracteres curta ou duas cadeias de caracteres muito curtas devem ser usadas para evitar concatenação.

Este exemplo, para uso com o Windows, usa o modelo toastImageAndText01, que precisa de uma imagem e uma cadeia de caracteres de texto. Um exemplo é mostrado aqui:

ToastImageAndText01


var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

O método getTemplateContent retorna XmlDocument. O código acima recupera o esqueleto XML a seguir, cujos detalhes você especificará nas etapas subsequentes usando as funções DOM padrão:


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

3. Fornecer conteúdo de texto para a sua notificação

Este exemplo recupera primeiro todos os elementos no modelo com um nome de marca "text". O modelo toastImageAndText01 inclui apenas uma cadeia de caracteres de texto, que o código atribui. Essa cadeia de caracteres pode ser quebrada em no máximo duas linhas, portanto, o comprimento da cadeia de caracteres tem que ser definido de acordo para evitar truncamentos.

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

4. Fornecer uma imagem para a sua notificação

Este código recupera primeiro todos os elementos no modelo com um nome de marca "image". Um modelo de notificação do sistema, como toastImageAndText01, inclui no máximo uma imagem. Observe que nem todos os modelos de notificação do sistema contêm imagens; alguns deles são somente texto.


var toastImageElements = toastXml.getElementsByTagName("image");

As imagens podem ser usadas do pacote do aplicativo, do armazenamento local do aplicativo ou da Web. Versões desta etapa são mostradas para cada fonte de imagem. As imagens precisam ser inferiores a 200 KB de tamanho e menores que 1024 x 1024 pixels. Para saber mais, veja Tamanhos de imagens de bloco e notificação do sistema.

O código a seguir usa uma imagem local do pacote do aplicativo. Esse tipo de imagem está incluído no arquivo da solução do Visual Studio e é empacotado como parte do seu aplicativo. Essas imagens são acessadas usando o prefixo "ms-appx:///". Como prática recomendada, também atribuímos um texto alternativo opcional para fins de acessibilidade, como leitores de tela.

Importante A imagem "redWide.png" utilizada aqui é apenas um exemplo e não está incluída em um projeto do Microsoft Visual Studio. Você terá que substituir "redWide.png" pelo nome de uma imagem real própria adicionada por você ao projeto antes de tentar enviar esta notificação de sistema.


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

O código a seguir usa uma imagem local do armazenamento local do aplicativo. Esse tipo de imagem foi salvo pelo aplicativo no armazenamento local. Este é o local que o Windows.Storage.ApplicationData.current.localFolder retorna. Essas imagens são acessadas com o uso do prefixo "ms-appdata:///local/". Mais uma vez, também atribuímos um texto alternativo opcional para fins de acessibilidade, como leitores de tela.


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

O código a seguir usa uma imagem da Web. Essas imagens são acessadas com o uso do protocolo "http://" para especificar o caminho da imagem. Você também pode usar o protocolo "https://".


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

Você pode usar o atributo opcional baseUri para especificar um caminho raiz, como "https://www.microsoft.com/", que é combinado com qualquer URI (Uniform Resource Identifier) relativo especificado nos atributos src de qualquer imagem. Esse atributo pode ser definido no elemento visual (a ser aplicado à notificação inteira) ou no elemento binding (a ser aplicado a essa associação). Se baseUri estiver definido nos dois, o valor em binding substituirá o valor em visual.

Se baseUri foi definido como "https://www.microsoft.com/", esta linha no código de exemplo:

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

poderá ser encurtada para:

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

5. Opcional: especificar a duração da notificação do sistema

Você pode definir uma duração para a exibição da notificação do sistema. Há dois valores: "short" (curto, o padrão) e "long" (longo). Use "short" apenas se a notificação fizer parte de um cenário, como recebimento de chamada ou lembrete de compromisso. Para saber mais, confira a Visão geral das notificações do sistema.

Observação Durações diferentes não são suportadas no Windows Phone 8.1; todas as notificações têm a mesma duração. Se este atributo é incluído em uma notificação do sistema do telefone, ele é ignorado.

Observação A duração padrão é "short", de maneira que, normalmente, esse atributo só precisa ser adicionado quando você quer definir o valor como "long".


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

6. Opcional: especificar áudio da notificação do sistema

Para saber mais sobre áudio de notificação do sistema, consulte Catálogo de opções de áudio de notificação do sistema.

Por padrão, o Windows toca um som breve quando a notificação do sistema é exibida. Você pode especificar outro som de um conjunto de sons fornecidos pelo sistema, ou nenhum som. No Windows Phone 8.1, você pode especificar um som personalizado. Para saber mais, consulte Catálogo de opções de áudio de notificação do sistema.

Um modelo recuperado através de getTemplateContent não inclui um elemento audio, por isso, defina e adicione-o ao conteúdo XML. O arquivo de som é especificado usando o prefixo "ms-winsoundevent:" ou, no Windows Phone 8.1, um caminho que usa o prefixo "ms-appx: / / /" ou "ms-appdata: / / /". Este exemplo cria um elemento audio e seleciona o elemento toast que vai ser o seu pai.


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

Este exemplo especifica um som não padrão.

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

Este exemplo especifica que nenhum som vai ser tocado.

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

No caso de uma notificação do sistema de longa duração, o som pode ser repetido ao invés de tocar apenas uma vez. Observe que repetir o áudio só é válido para notificações do sistema de longa duração. Sons específicos para usar em repetições estão incluídos no conjunto de sons fornecidos pelo sistema. Este exemplo especifica um som repetido.

Observação Como não suporta notificações de longa duração, o Windows Phone 8.1 não suporta áudio em loop.


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

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

Após definir seu elemento de áudio, anexe-o à carga XML da notificação do sistema como filho do elemento toast, como mostrado aqui.

toastNode.appendChild(audio);

7. Especifique os parâmetros de inicialização do aplicativo

Quando o usuário clica na sua notificação de caixa de informações, a expectativa é que o seu aplicativo seja inicializado com uma exibição relacionada ao conteúdo da notificação. Para tanto, use o atributo launch do elemento de caixa de informações, que fornece uma cadeia de caracteres que é passada da caixa de informações para o aplicativo quando o aplicativo é lançado por meio de uma caixa de informações. Esta cadeia de caracteres não possui uma forma específica e é definida pelo aplicativo. O seu aplicativo deve verificar essa cadeia de caracteres como um argumento a cada vez que é ativado para ajustar a sua exibição ou operação de acordo.


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

Observação No Windows Phone Silverlight 8.1, o valor da cadeia de caracteres de inicialização é acrescentado ao URI da sua página de inicialização padrão. Por exemplo, se você fornecer a cadeia de caracteres de inicialização "?conversation=71", ela resultará em um URI como /MainPage.xaml?conversation=71. Portanto, a cadeia de caracteres de inicialização também deve ser uma cadeia de caracteres de consulta válida; Caso contrário, uma exceção é gerada.

8. Crie a notificação de caixa de informações com base no conteúdo XML que você especificou.

var toast = new notifications.ToastNotification(toastXml);

9. Envie a sua notificação de caixa de informações.

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

Observação No Windows Phone Silverlight 8.1, uma notificação do sistema não será exibida se o aplicativo em primeiro plano atual for o chamador do método ToastNotifier.Show. Nesse caso, a notificação do sistema deve ser usada principalmente por um agente em segundo plano.

Observação: A cor da tela de fundo aplicada à sua notificação do sistema é a cor da tela de fundo declarada para o bloco do seu aplicativo no manifesto do seu aplicativo. Para obter mais informações, consulte Guia de início rápido: Criando um bloco padrão usando o editor de manifestos do Visual Studio.

Resumo e próximas etapas

Neste Guia de início rápido, você enviou a sua notificação local do sistema para o usuário.

Este Guia de início rápido enviou a notificação do sistema como uma notificação local, já que é o tipo de notificação mais simples para implementação que permite ver rapidamente os resultados. Em seguida, explore outros métodos de entrega de notificação do sistema: agendada e por push. Para saber mais, veja Entregando notificações.