Início rápido: enviando uma notificação do sistema (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]

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:

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.

Tópicos relacionados

Exemplos

Exemplo de notificações do sistema

Exemplo de envio de notificações do sistema a partir de aplicativos da área de trabalho

Cenários de recursos do Reversi: notificações do sistema

Conceitual

Visão geral da notificação de caixa de informações

O catálogo de modelos de notificação do sistema

O catálogo de opções de áudio para notificações do sistema

Instrutivo

Guia de início rápido: enviando uma notificação por push

Como manipular a ativação a partir de uma notificação do sistema

Como aceitar notificações de caixa de informações

Como agendar uma notificação de caixa de informações

Guia de início rápido: enviando uma notificação de caixa de informações a partir da área de trabalho

Como habilitar notificações de caixa de informações na área de trabalho com uma AppUserModelID

Práticas recomendadas

Diretrizes e lista de verificação de notificações de caixa de informações

Referência

Esquema XML de caixa de informações

ToastNotification

ToastNotificationManager

ToastNotifier