Agrupando notificações toast com coleções

Use coleções para organizar as alertas do seu aplicativo na Central de Ações. As coleções ajudam os usuários a localizar informações na Central de Ações com mais facilidade e permitem que os desenvolvedores gerenciem melhor suas notificações. As APIs abaixo permitem remover, criar e atualizar coleções de notificação.

Você pode ver o exemplo abaixo com um aplicativo de mensagens que separa as notificações com base no grupo de chat; cada título (Comp Sci 160A Project Chat, Direct Messages, Lacrosse Team Chat) é uma coleção separada. Observe como as notificações são agrupadas distintamente como se fossem de um aplicativo separado, mesmo que todas sejam notificações do mesmo aplicativo. Se você estiver procurando uma maneira mais sutil de organizar suas notificações, confira os cabeçalhos de toast.

Criando coleções

Ao criar cada coleção, você precisa fornecer um nome de exibição e um ícone, que são exibidos dentro da Central de Ações como parte do título da coleção, conforme mostrado na imagem acima. As coleções também exigem um argumento de inicialização para ajudar o aplicativo a navegar até o local certo dentro do aplicativo quando o título da coleção é clicado pelo usuário.

Criar uma coleção

// Create a toast collection
public async void CreateToastCollection()
{
	string displayName = "Work Email"; 
	string launchArg = "NavigateToWorkEmailInbox"; 
	Uri icon = new Windows.Foundation.Uri("ms-appx:///Assets/workEmail.png");

	// Constructor
	ToastCollection workEmailToastCollection = new ToastCollection(
		"MyToastCollection", 
		displayName,
 		launchArg, 
		icon);

	// Calls the platform to create the collection
	await ToastNotificationManager.GetDefault().GetToastCollectionManager().SaveToastCollectionAsync(workEmailToastCollection);  								
}

Enviar notificações para uma coleção

Abordaremos o envio de notificações a partir de três pipelines de toast diferentes: local, agendado e push. Para cada um desses exemplos, criaremos um brinde de exemplo para enviar com o código imediatamente abaixo e, em seguida, nos concentraremos em como adicionar o brinde a uma coleção por meio de cada pipeline.

Construa o conteúdo do aviso.

// Construct the content
var content = new ToastContentBuilder()
	.AddText("Adam sent a message to the group")
	.GetToastContent();

Enviar um brinde para uma coleção

// Create the toast
ToastNotification toast = new ToastNotification(content.GetXml());

// Get the collection notifier
var notifier = await ToastNotificationManager.GetDefault().GetToastNotifierForToastCollectionIdAsync("MyToastCollection");

// And show the toast
notifier.Show(toast);

Adicionar um toast agendado a uma coleção

// Create scheduled toast from XML above
ScheduledToastNotification scheduledToast = new ScheduledToastNotification(content.GetXml(), DateTimeOffset.Now.AddSeconds(10));

// Get notifier
var notifier = await ToastNotificationManager.GetDefault().GetToastNotifierForToastCollectionIdAsync("MyToastCollection");
    
// Add to schedule
notifier.AddToSchedule(scheduledToast);

Enviar uma notificação por push para uma coleção

Para notificações por push, você precisa adicionar o cabeçalho X-WNS-CollectionId à mensagem POST.

// Add header to HTTP request
request.Headers.Add("X-WNS-CollectionId", collectionId); 

Gerenciando coleções

Criar o gerenciador de coleções de notificações tipo toast

Para o restante dos snippets de código nesta seção "Gerenciando coleções", usaremos a coleçãoManager abaixo.

ToastCollectionManger collectionManager = ToastNotificationManager.GetDefault().GetToastCollectionManager();

Obter todas as coleções

IReadOnlyList<ToastCollection> collections = await collectionManager.FindAllToastCollectionsAsync();

Obter o número de coleções criadas

int toastCollectionCount = (await collectionManager.FindAllToastCollectionsAsync()).Count;

Remover uma coleção

await collectionManager.RemoveToastCollectionAsync("MyToastCollection");

Atualizar uma coleção

Você pode atualizar coleções criando uma nova coleção com a mesma ID e salvando a nova instância da coleção.

string displayName = "Updated Display Name"; 
string launchArg = "UpdatedLaunchArgs"; 
Uri icon = new Windows.Foundation.Uri("ms-appx:///Assets/updatedPicture.png");

// Construct a new toast collection with the same collection id
ToastCollection updatedToastCollection = new ToastCollection(
	"MyToastCollection", 
	displayName,
	launchArg, 
	icon);

// Calls the platform to update the collection by saving the new instance
await collectionManager.SaveToastCollectionAsync(updatedToastCollection);  								

Gerenciamento de toasts em uma coleção

Propriedades de grupo e etiqueta

As propriedades de grupo e etiqueta juntas identificam exclusivamente uma notificação em uma coleção. O grupo (e a tag) servem como uma chave primária composta (mais de um identificador) para identificar uma notificação. Por exemplo, se você quiser remover ou substituir uma notificação, deverá ser capaz de especificar qual notificação deseja remover/substituir; você faz isso especificando a Marca e o Grupo. Um exemplo é um aplicativo de mensagens. O desenvolvedor pode usar a ID da Conversa como o Grupo, e a ID da Mensagem como a Etiqueta.

Remover um brinde de uma coleção

Você pode remover toasts individuais usando IDs de tag e de grupo ou limpar todas as toasts em uma coleção.

// Get the history
var collectionHistory = await ToastNotificationManager.GetDefault().GetHistoryForToastCollectionAsync("MyToastCollection");

// Remove toast
collectionHistory.Remove(tag, group); 

Limpar todas as notificações em uma coleção

// Get the history
var collectionHistory = await ToastNotificationManager.GetDefault().GetHistoryForToastCollectionAsync("MyToastCollection");

// Remove toast
collectionHistory.Clear();

Coleções no Visualizador de Notificações

Você pode usar a ferramenta Visualizador de Notificações para ajudar a projetar suas coleções. Siga as etapas abaixo:

• Clique no ícone de engrenagem no canto inferior direito.
• Selecione 'Coleções do Toast'.
• Acima da visualização da notificação toast, há um menu suspenso 'Coleção de notificação toast'. Selecione gerenciar coleções.
• Clique em 'Adicionar coleção', preencha os detalhes da coleção e salve.
• Você pode adicionar mais coleções ou clicar fora da caixa de gerenciamento de coleções para retornar à tela principal.
• Selecione a coleção onde deseja adicionar o toast no menu suspenso 'Coleção de Toasts'.
• Quando você ativar a notificação, ela será adicionada à coleção apropriada na Central de Ações.

Outros detalhes

As coleções de toast que você cria também serão refletidas nas configurações de notificação do usuário. Os usuários podem alternar as configurações de cada coleção individual para ativar ou desativar esses subgrupos. Se as notificações estiverem desativadas no nível superior do aplicativo, todas as notificações de coleções também serão desativadas. Além disso, cada coleção mostrará por padrão três notificações na Central de Ações e o usuário poderá expandi-la para mostrar até 20 notificações.

Tópicos relacionados

• Conteúdo do sistema
• Cabeçalhos de notificações
• Biblioteca de notificações no GitHub (parte do Windows Community Toolkit)