Início rápido: enviando uma atualização de bloco (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 atualização de bloco (XAML).

O bloco começa como um bloco padrão, definido no manifesto e exibido quando o seu aplicativo é instalado pela primeira vez. Após a instalação do aplicativo, você pode mudar o conteúdo do bloco através de notificações.Este Guia de início rápido orienta você ao longo das etapas para definir um novo conteúdo de bloco, enviar esse conteúdo ao bloco e removê-lo quando ele não for mais necessário. 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
Empacotando diferentes versões de notificação para diferentes tamanhos de bloco em uma única carga
Definindo um tempo de expiração para a sua notificação
Enviando a atualização para o bloco como uma notificação local

Veja esse recurso em ação como parte da nossa série Recursos do aplicativo, do começo ao fim.: Interface do usuário de aplicativo da Windows Store, do início ao fim

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 Amostra de blocos e notificações de aplicativo.

Pré-requisitos

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

Um conhecimento prático dos termos e conceitos de bloco e notificação. Para saber mais, veja Blocos, selos e notificações.
Familiaridade com o esquema XML de bloco. Para saber mais, veja Esquema de blocos.
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.
Um bloco padrão existente para o seu aplicativo, definido no manifesto do aplicativo. Para saber mais, veja Guia de início rápido: criando um bloco padrão usando o Editor de Manifesto do Microsoft Visual Studio.
Familiaridade com o XML e sua manipulação por meio de APIs DOM (Document Object Model).

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 o bloco e recuperar seu conteúdo XML

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

Este exemplo usa o modelo TileWide310x150ImageAndText01, que precisa de uma imagem e uma cadeia de caracteres de texto. Um exemplo é mostrado aqui:

TileWide310x150ImageAndText01


var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.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.

Observação Quando o getTemplateContent é chamado em um sistema Windows 8, ele retorna uma versão do modelo 1. Quando esse método é chamado em um sistema Windows 8.1, ele retorna uma versão do modelo 2 ou uma versão do modelo 3 para modelos só de Windows Phone. Se um aplicativo especifica a compatibilidade do Windows 8 em seu manifesto, esse método retorna uma versão do modelo 1, independentemente da versão do Windows. Neste tópico, nós vamos usar a versão do modelo 2.


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

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

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


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

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". O modelo TileWide310x150ImageAndText01 inclui uma única imagem. Observe que nem todos os modelos de bloco contêm imagens; alguns deles são somente texto.

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. Se você não fizer isso, a notificação não será entregue.


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

Imagens podem ser usadas a partir do pacote do aplicativo, do armazenamento local do aplicativo ou da Web. Versões desta etapa são mostradas para cada fonte de imagem. Em uma notificação de bloco que contém várias imagens, os elementos de imagem podem usar qualquer combinação desses tipos de fonte de imagem. As imagens usadas em modelos devem ter menos de 200 KB de tamanho e serem menor 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.


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


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

O código a seguir usa uma imagem da Web. Essas imagens são acessadas usando o protocolo "http://" ou "https://" para especificar o caminho da imagem. Observe que o aplicativo deve ter a funcionalidade internetClient declarada em seu manifesto para usar imagens da Web.


tileImageAttributes[0].setAttribute("src", "https://www.contoso.com/redWide.png");
tileImageAttributes[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.contoso.com/", esta linha no código de exemplo:


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

poderá ser encurtada para:


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

5. Incluir associações de notificação para vários tamanhos de bloco na carga

O usuário pode redimensionar seu bloco na tela inicial a qualquer momento, e não é possível saber em que estado (pequeno, médio, largo ou grande) o bloco se encontra quando você envia uma notificação. Se o seu bloco estiver dimensionado de tal forma que não exista uma associação de modelo correspondente na sua notificação, esta última não será exibida. Portanto, é uma prática recomendada sempre incluir versões da notificação em sua carga para todos os tamanhos de Live Tile (médio, largo, grande) para os quais você forneceu uma imagem de logotipo em seu manifesto.

Observação A partir do Windows Phone 8.1, blocos grandes não são suportados no telefone.

Este exemplo define uma notificação média somente texto usando a mesma cadeia de caracteres de texto que usamos na notificação larga.

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

Em seguida, adicione o bloco médio à carga do bloco largo. Recupere o elemento binding que define o bloco médio na carga squareTileXml. Acrescente esse elemento binding como irmão do bloco largo.


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

As etapas anteriores resultam em dois elementos binding em um único elemento visual na carga XML, conforme mostrado aqui:


<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. Criar a notificação com base no conteúdo XML que você especificou


var tileNotification = new notifications.TileNotification(tileXml);

7. Definir um tempo de expiração para a notificação

Por padrão, as notificações locais de bloco e selo não expiram, e as notificações por push, periódicas e agendadas expiram após três dias. Uma prática recomendada é definir um tempo de expiração, principalmente nas notificações locais de bloco e selo, usando um tempo que faça sentido para o seu aplicativo. O conteúdo do bloco só deve persistir enquanto for relevante. Neste caso, a notificação vai expirar e ser removida do bloco em dez minutos.


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

8. Envie a notificação para o bloco do aplicativo.


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

9. Opcional: limpar sua notificação de bloco

Este exemplo mostra como limpar uma notificação de bloco através de uma chamada local. Se o conteúdo estiver associado a um tempo, observe que nós recomendamos que você defina um tempo de expiração na notificação, em vez de limpá-la explicitamente. A linha de código a seguir limpa a notificação atual do bloco do aplicativo.


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

Para um bloco cuja fila de notificações esteja habilitada e com notificações na fila, limpar o método clear esvazia essa fila.

Observe que você não pode limpar uma notificação da nuvem. Uma chamada local para o método clear limpa o bloco independentemente da origem de suas notificações, mas as notificações periódicas ou por push só podem atualizar o bloco para um novo conteúdo.

Resumo e próximas etapas

Neste Guia de início rápido, você definiu e enviou um novo conteúdo para o bloco do seu aplicativo por meio de uma notificação, que depois foi removida após 10 minutos. O código a seguir resume as etapas acima, desde a escolha de um modelo até o envio da notificação. Ele usa uma imagem do pacote do aplicativo.

Para testar esse código em um exemplo de sua preferência, coloque-o em uma função que é acionada por um botão na interface do usuário do exemplo. Por exemplo, você pode colocar o botão no arquivo default.html. Lembre-se de substituir o nome de uma imagem 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);

Agora que você atualizou o seu bloco pela primeira vez, é possível expandir sua funcionalidade habilitando uma fila de notificação.

Este Guia de início rápido enviou a atualização de bloco como uma notificação local. Você também pode explorar os outros métodos de distribuição de notificações: agendada, periódica e por push. Para saber mais, veja Distribuindo notificações.