Conteúdo da notificação do aplicativo

As notificações do aplicativo são notificações flexíveis com texto, imagens e botões/entradas. Este artigo descreve os elementos da interface do usuário que podem ser usados em uma notificação do aplicativo e fornece exemplos de código para gerar o formato XML para uma notificação de aplicativo.

Note

O termo "notificação de brinde" está sendo substituído por "notificação do aplicativo". Esses termos se referem ao mesmo recurso do Windows, mas, com o tempo, eliminaremos gradualmente o uso de "notificação do tipo toast" na documentação.

Como começar

As notificações do aplicativo são definidas com uma carga XML definida pelo esquema de notificação do aplicativo. Atualmente, há três maneiras de gerar o conteúdo XML para uma notificação de aplicativo. Os exemplos de código neste artigo demonstram todos os três métodos:

As APIs Microsoft.Windows.AppNotifications.Builder – Introduzidas no SDK do Aplicativo do Windows 1.2, esse namespace fornece APIs que permitem criar facilmente o conteúdo XML para uma notificação programaticamente, sem precisar se preocupar com as especificidades do formato XML. Exemplos de código usando essas APIs estão nas guias rotuladas como "SDK do Aplicativo do Windows".
A Microsoft.Toolkit.Uwp.Notifications sintaxe do construtor – essas APIs fazem parte do Kit de Ferramentas da Comunidade UWP e dão suporte a aplicativos UWP. Embora essas APIs também possam ser usadas para aplicativos do SDK de Aplicativos do Windows e continuem com suporte, recomendamos que novas implementações usem as APIs Microsoft.Windows.AppNotifications.Builder . Para usar as APIs do Kit de Ferramentas da Comunidade, adicione o pacote nuget de notificações do UWP Community Toolkit ao seu projeto. Os exemplos de C# fornecidos neste artigo usam a versão 7.0.0 do pacote NuGet. Exemplos de código usando essas APIs estão nas guias rotuladas como "Kit de Ferramentas da Comunidade do Windows".
XML bruto – se preferir, você pode criar seu próprio código personalizado para gerar cadeias de caracteres XML no formato necessário. Os exemplos de XML brutos estão nas guias rotuladas como "XML".

Instalar o Visualizador de Notificações. Este aplicativo gratuito do Windows ajuda você a criar notificações interativas do tipo 'toast' fornecendo uma visualização instantânea delas enquanto você as edita, semelhante ao editor/modo de exibição de design XAML do Visual Studio. Consulte o Visualizador de Notificações para obter mais informações ou baixe o Visualizador de Notificações naLoja.

Este artigo aborda apenas a criação do conteúdo da notificação do aplicativo. Para obter informações sobre como enviar uma notificação depois de gerar o conteúdo XML, consulte Enviar uma notificação de aplicativo local.

Estrutura de notificação do aplicativo

Alguns componentes importantes e de alto nível de uma carga XML de notificação do aplicativo incluem:

notificação: o atributo lançamento desse elemento define quais argumentos serão passados de volta para seu aplicativo quando o usuário clicar na sua notificação, permitindo que você faça um link profundo para o conteúdo correto que a notificação estava exibindo. Para saber mais, consulte Enviar uma notificação de aplicativo local.
visual: esse elemento representa a parte visual do toast, incluindo a vinculação genérica que contém texto e imagens.
ações: esse elemento representa a parte interativa do aviso de notificação, incluindo entradas e ações.
de áudio: esse elemento especifica o áudio reproduzido quando a notificação é exibida ao usuário.

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", "9813")

    .AddText("Some text")

    .AddButton(new AppNotificationButton("Archive")
        .AddArgument("action", "archive"))

    .SetAudioUri(new Uri("ms-appx:///Sound.mp3"));

var builder = new ToastContentBuilder()
    .AddArgument("conversationId", 9813)

    .AddText("Some text")

    .AddButton(new ToastButton()
        .SetContent("Archive")
        .AddArgument("action", "archive"))

    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast launch='conversationId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Some text</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
    <actions>
        <action content='Archive' arguments='action=archive'/>
    </actions>
</toast>

Aqui está uma representação visual do conteúdo da notificação do aplicativo:

Área de atribuição

A área de atribuição está na parte superior da notificação do aplicativo. A partir do Windows 11, o nome e o ícone do aplicativo são exibidos nessa área. A área de atribuição também inclui um botão de fechar que permite ao usuário descartar rapidamente a notificação e um menu de reticências que permite ao usuário desabilitar rapidamente as notificações do seu aplicativo ou acessar a página de Configurações do Windows para as notificações do seu aplicativo. A área de atribuição é configurada pelo shell e não pode ser substituída na carga XML do sistema, embora seu aplicativo possa adicionar itens ao menu de contexto da área de atribuição. Para obter mais informações , consulte as ações do menu Contexto.

Visual

Cada notificação de aplicativo deve especificar um elemento visual, onde você deve fornecer uma vinculação de toast genérica e que pode conter texto e imagens. Esses elementos serão renderizados em vários dispositivos Windows, incluindo desktop, telefones, tablets e Xbox.

Para todos os atributos com suporte na seção visual e seus elementos filho, consulte esquema de notificação de aplicativo.

Elementos de texto

Cada notificação do aplicativo deve ter pelo menos um elemento de texto e pode conter dois elementos de texto adicionais, todos do tipo AdaptiveText.

Captura de tela de uma notificação de aplicativo com três linhas de texto. A linha superior do texto é em negrito.

Desde a Atualização de Aniversário do Windows 10, você pode controlar quantas linhas de texto são exibidas usando a propriedade HintMaxLines no texto. O padrão (e máximo) é até 2 linhas de texto para o título e até 4 linhas (combinadas) para os dois elementos de descrição adicionais (o segundo e o terceiro AdaptiveText).

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", 9813)
    .AddText("Adaptive Tiles Meeting", new AppNotificationTextProperties().SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

var builder = new ToastContentBuilder()
    .AddArgument("meetingId", 9813)
    .AddText("Adaptive Tiles Meeting", hintMaxLines: 1)
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

<toast launch='meetingId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

Imagem embutida

Por padrão, as imagens são exibidas embutidas, após qualquer elemento de texto, preenchendo a largura total da área visual.

Uma captura de tela de uma notificação de aplicativo mostrando o posicionamento da imagem padrão, em linha, preenchendo a largura total da área visual.

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

AppNotificationManager.Default.Show(builder.BuildNotification());

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image src='ms-appx:///Images/InlineImage.png'/>
        </binding>
    </visual>
</toast>

Substituição do logotipo do aplicativo

Especificar um valor de posicionamento como "appLogoOverride" fará com que a imagem seja exibida em um quadrado no lado esquerdo da área visual. O nome dessa propriedade reflete o comportamento em versões anteriores do Windows, em que a imagem substituiria a imagem do logotipo do aplicativo padrão. No Windows 11, o logotipo do aplicativo é exibido na área de atribuição, portanto, ele não é substituído pelo appLogoOverride posicionamento da imagem.

As dimensões de imagem são de 48 x 48 pixels a 100% dimensionamento. Geralmente, recomendamos fornecer uma versão de cada ativo de ícone para cada fator de escala: 100%, 125%, 150%, 200%e 400%.

Uma captura de tela de uma notificação de aplicativo mostrando a imagem de substituição do logotipo do aplicativo posicionada em um quadrado no lado esquerdo da área visual da notificação.

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/AppLogo.png'/>
        </binding>
    </visual>
</toast>

Sugestão de recorte

As diretrizes de estilo da Microsoft recomendam representar imagens de perfil com uma imagem circular para fornecer uma representação consistente de pessoas entre aplicativos e o shell. Defina a propriedade HintCrop para Circle para renderizar a imagem com um recorte circular.

Uma captura de tela de uma notificação de aplicativo mostrando o logotipo do aplicativo recortado em formato circular localizado no lado esquerdo da área visual da notificação.

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), AppNotificationImageCrop.Circle);

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), ToastGenericAppLogoCrop.Circle);

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/Profile.png' hint-crop='circle'/>
        </binding>
    </visual>
</toast>

Imagem em destaque

New in Anniversary Update: as notificações de aplicativo podem exibir uma imagem de destaque, que é uma ToastGenericHeroImage exibida com destaque dentro da faixa de notificação e enquanto estiver dentro do Centro de Notificações. As dimensões da imagem são 364 x 180 pixels com escala de 100%%.

Uma captura de tela de uma notificação de aplicativo mostrando o posicionamento da imagem hero, acima da área de atribuição.

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Mary Anne</text>
            <text>Check out where we camped last night!</text>
            <image placement='hero' src='ms-appx:///Images/HeroImage.png'/>
        </binding>
    </visual>
</toast>

Restrições de tamanho de imagem

As imagens que você usa na notificação de brinde podem vir de...

http://
ms-appx:///
ms-appdata:///

Para imagens da Web remotas http e https, há limites no tamanho do arquivo de cada imagem individual. No Fall Creators Update (16299), aumentamos o limite para 3 MB em conexões normais e 1 MB em conexões limitadas. Antes disso, as imagens eram sempre limitadas a 200 KB.

Conexão normal	Conexão limitada	Antes da atualização do Fall Creators
3 MB	1 MB	200 KB

Se uma imagem exceder o tamanho do arquivo ou não baixar ou atingir o tempo limite, a imagem será descartada e o restante da notificação será exibida.

Texto de atribuição

Novo na Atualização de Aniversário: se você precisar referenciar a fonte do seu conteúdo, poderá usar o texto de referência. Esse texto é sempre exibido abaixo de qualquer elemento de texto, mas acima de imagens embutidas. O texto usa um tamanho ligeiramente menor do que os elementos de texto padrão para ajudar a distinguir dos elementos de texto regulares.

Em versões mais antigas do Windows que não dão suporte ao texto de atribuição, o texto será simplesmente exibido como outro elemento de texto (supondo que você ainda não tenha o máximo de três elementos de texto).

Uma captura de tela de uma notificação de

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetAttributionText("via SMS");
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddAttributionText("Via SMS");
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>  
  <visual>
    <binding template="ToastGeneric">
      <image src="ms-appx:///Images/HeroImage.png"/>
      <text>Mary Anne</text>
      <text>Check out where we camped last night!</text>
      <text placement="attribution">Via SMS</text>
    </binding>
  </visual>
</toast>

Carimbo de data/hora personalizado

New in Creators Update: agora você pode substituir o carimbo de data/hora fornecido pelo sistema com seu próprio carimbo de data/hora que representa com precisão quando a mensagem/informação/conteúdo foi gerada. Esse carimbo de data/hora é visível na Central de Notificações.

Captura de tela de uma notificação no Centro de Notificações com um carimbo de data/hora personalizado

Para saber mais sobre como usar um timestamp personalizado, consulte timestamps personalizados em toasts.

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddCustomTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

<toast displayTimestamp='2017-04-15T12:45:00-07:00'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
        </binding>
    </visual>
</toast>

Barra de progresso

Novidades no Creators Update: você pode fornecer uma barra de progresso na notificação do aplicativo para manter o usuário informado sobre o andamento das operações, como downloads.

Uma captura de tela de uma notificação toast mostrando uma barra de progresso.

Para saber mais sobre como usar uma barra de progresso, consulte barra de progresso do Toast.

Headers

Novidades na Atualização para Criadores: você pode agrupar notificações em cabeçalhos na Central de Notificações. Por exemplo, você pode agrupar mensagens de um chat em grupo em um cabeçalho ou agrupar notificações de um tema comum em um cabeçalho ou mais.

Uma captura de tela de uma central de ações mostrando várias notificações para o Visualizador de Notificações do aplicativo organizado em um cabeçalho rotulado como

Para mais informações sobre o uso de cabeçalhos, consulte Toast headers.

Conteúdo adaptável

Novo na Atualização de Aniversário: além do conteúdo especificado acima, você também pode exibir conteúdo adaptativo adicional que fica visível quando a notificação é expandida.

Esse conteúdo adicional é especificado usando Adaptive, sobre o qual você pode saber mais lendo a documentação de Blocos Adaptáveis.

Observe que qualquer conteúdo adaptável deve estar contido em um AdaptiveGroup. Caso contrário, ele não será renderizado usando adaptativo.

Colunas e elementos de texto

Aqui está um exemplo em que colunas e alguns elementos de texto adaptáveis avançados são usados. Como os elementos de texto estão dentro de um AdaptiveGroup, eles dão suporte a todas as propriedades de estilo ricamente adaptáveis.

Uma captura de tela de uma notificação toast mostrando grupos de elementos de texto alinhados à esquerda e à direita da área visual da notificação.

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support adaptive text elements.

new ToastContentBuilder()
    ...
    
    .AddVisualChild(new AdaptiveGroup()
    {
        Children =
        {
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "52 attendees",
                        HintStyle = AdaptiveTextStyle.Base
                    },
                    new AdaptiveText()
                    {
                        Text = "23 minute drive",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            },
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "1 Microsoft Way",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    },
                    new AdaptiveText()
                    {
                        Text = "Bellevue, WA 98008",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    }
                }
            }
        }
    });

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Reminder: Windows Launch Party</text>
      <text>4:00 PM, 10/21/2021</text>
      <group>
        <subgroup>
          <text hint-style="base">52 attendees</text>
          <text hint-style="captionSubtle">23 minute drive</text>
        </subgroup>
        <subgroup>
          <text hint-style="captionSubtle" hint-align="right">1 Microsoft Way</text>
          <text hint-style="captionSubtle" hint-align="right">Bellevue, WA 98008</text>
        </subgroup>
      </group>
    </binding>
  </visual>
</toast>

Buttons

Os botões tornam o toast interativo, permitindo que o usuário execute ações rápidas na notificação do aplicativo sem interromper o fluxo de trabalho atual. Por exemplo, os usuários podem responder a uma mensagem diretamente de uma notificação flutuante ou excluir um email sem sequer abrir o aplicativo de email. Os botões aparecem na parte expandida da notificação.

Para saber mais sobre como implementar botões de ponta a ponta, consulte Enviar notificação local.

Os botões podem ativar um aplicativo das seguintes maneiras:

O aplicativo é ativado em primeiro plano, com um argumento que pode ser usado para navegar até uma página/contexto específico.
Outro aplicativo é ativado por meio da inicialização do protocolo.
A ativação em segundo plano tem suporte explícito para aplicativos UWP. Para aplicativos do SDK de Aplicativos do Windows, o aplicativo sempre é iniciado em primeiro plano. O aplicativo pode chamar AppInstance.GetActivatedEventArgs para detectar se a ativação foi iniciada por uma notificação e determinar pelos argumentos passados se deseja iniciar totalmente o aplicativo em primeiro plano ou apenas manipular a notificação e sair.
Ações do sistema, como adiar ou ignorar a notificação, têm suporte tanto para aplicativos UWP quanto para o SDK para Aplicativos do Windows. As APIs appNotificationBuilder não dão suporte a esse cenário, mas os aplicativos do SDK de Aplicativo do Windows podem implementar esse cenário usando as APIs Microsoft.Windows.AppNotifications.Builder ou XML bruto.

Note

Você só pode ter até 5 botões (incluindo itens de menu de contexto que discutiremos mais tarde).

Uma captura de tela de uma notificação mostrando uma linha de texto seguida por uma fileira com dois botões definidos por elementos de ação

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("New product in stock!")
        .AddButton(new AppNotificationButton("See more details")
            .AddArgument("action", "viewDetails"))
            .AddArgument("contentId", "351")
        .AddButton(new AppNotificationButton("Remind me later")
            .AddArgument("action", "remindLater"))
            .AddArgument("contentId", "351");

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("See more details")
        .AddArgument("action", "viewDetails"))

    .AddButton(new ToastButton()
        .SetContent("Remind me later")
        .AddArgument("action", "remindLater"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>New product in stock!</text>
        </binding>
    </visual>
      <actions>
          <action content='See more details' arguments='action=viewDetails;contentId=351'/>
          <action content='Remind me later' arguments='action=remindLater;contentId=351'/>
      </actions>
</toast>

Botões com ícones

Você pode adicionar ícones aos botões. Esses ícones são imagens transparentes brancas de 16x16 pixels com escala de 100%, e não devem ter nenhum preenchimento na própria imagem. Se você optar por fornecer ícones em uma notificação, deverá fornecer ícones para TODOS os botões na notificação, já que isso transforma o estilo dos seus botões em botões com ícones.

Note

Para acessibilidade, inclua uma versão em branco de contraste do ícone (um ícone preto para planos de fundo brancos), para que, quando o usuário ativar o modo Branco de Alto Contraste, o ícone fique visível. Para obter mais informações, consulte suporte a notificações de bloco e toast para idioma, escala e alto contraste.

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("Return books to the library.")
        .AddButton(new AppNotificationButton("Accept")
            .AddArgument("action", "accept")
            .SetIcon(new Uri("ms-appx:///Images/Accept.png")))
        .AddButton(new AppNotificationButton("Snooze")
            .AddArgument("action", "snooze")
            .SetIcon(new Uri("ms-appx:///Images/Snooze.png")))
        .AddButton(new AppNotificationButton("Dismiss")
            .AddArgument("action", "dismiss")
            .SetIcon(new Uri("ms-appx:///Images/Dismiss.png")));

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("Accept")
        .AddArgument("action", "accept")
        .SetImageUri(new Uri("ms-appx:///Images/Accept.png")))
    .AddButton(new ToastButton()
        .SetContent("Snooze")
        .AddArgument("action", "snooze")
        .SetImageUri(new Uri("ms-appx:///Images/Snooze.png")))
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss")
        .SetImageUri(new Uri("ms-appx:///Images/Dismiss.png")));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Return books to the library.</text>
        </binding>
    </visual>
    <actions>
        <action content='Accept' arguments='action=accept' imageUri='ms-appx:///Assets/Accept.png'/>
        <action content='Snooze' arguments='action=snooze' imageUri='ms-appx:///Assets/Snooze.png'/>
        <action content='Dismiss' arguments='action=dismiss' imageUri='ms-appx:///Assets/Dismiss.png'/>
    </actions>
</toast>

Novidades na Atualização do Windows 11: você pode adicionar dicas de ferramentas aos seus ícones com a propriedade HintToolTip em XML. Isso é ideal se os botões tiverem ícones, mas nenhum conteúdo, pois isso garantirá que você possa passar o texto que o Narrador do Windows pode ler. No entanto, se o conteúdo estiver presente, o Narrador lerá o conteúdo, independentemente do que for passado na dica de ferramenta.

var button = new AppNotificationButton("Reply")
    .AddArgument("action", "reply");

if (AppNotificationButton.IsToolTipSupported())
{
    button.ToolTip = "Click to reply.";
}

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .AddButton(button);

// The Community Toolkit builder syntax does not currently support icon tooltips.

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Reply' arguments='action=reply' hint-toolTip='Click to reply'/>
    </actions>
</toast>

Botões com cores

Novo na Atualização do Windows 11: você pode adicionar cores vermelhas ou verdes aos botões adicionando o atributo useButtonStyle ao elemento toast XML e o atributo hint-buttonStyle ao elemento XML de ação, conforme visto abaixo.

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .AddText("Incoming Call - Mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///Images/Profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Video Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Video.png"))
        .AddArgument("videoId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Phone Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Call.png"))
        .AddArgument("callId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Hang Up")
        .SetButtonStyle(AppNotificationButtonStyle.Critical)
        .SetIcon(new Uri("ms-appx:///Images/HangUp.png"))
        .AddArgument("hangUpId", "123"));

// The WIndows Community Toolkit builder syntax does not currently support red and green button colors.

<toast scenario='incomingCall' useButtonStyle='true'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>Incoming Call - Mobile</text>
            <image src='ms-appx:///Images/InlineImage.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='' 
            arguments='videoId=123' 
            imageUri='ms-appx:///Images/Video.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Video Call'/>
        <action 
            content='' 
            arguments='callId=123' 
            imageUri='ms-appx:///Images/Call.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Phone Call'/>
        <action 
            content='' 
            arguments='hangUpId=123' 
            imageUri='ms-appx:///Images/HangUp.png' 
            hint-buttonStyle='Critical' 
            hint-toolTip='Hang Up'/>
    </actions>
</toast>

Novo na atualização de aniversário: você pode adicionar ações de menu de contexto adicionais ao menu de contexto existente que aparece quando o usuário clica com o botão direito do mouse na notificação do sistema ou seleciona o ícone de menu de contexto.

Note

Em dispositivos mais antigos, essas ações de menu de contexto adicionais simplesmente aparecerão como botões normais na notificação.

As ações do menu de contexto adicionais que você adicionar (como "Silenciar chat em grupo por 1 hora") aparecem acima das duas entradas padrão do sistema.

de menu de contexto

var builder = new AppNotificationBuilder()
    .AddText("Camping this weekend?")
    .SetAppLogoOverride(new Uri("ms-appx:///images/Reply.png"), AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Mute group chat for 1 hour")
        .AddArgument("action", "mute")
        .SetContextMenuPlacement());

No momento, a sintaxe do construtor do Windows Community Toolkit não dá suporte a ações de menu de contexto, portanto, é recomendável usar a sintaxe do inicializador.

ToastContent content = new ToastContent()
{
    ...
 
    Actions = new ToastActionsCustom()
    {
        ContextMenuItems =
        {
            new ToastContextMenuItem("Mute group chat for 1 hour", "action=muteId")
        }
    }
};

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Camping this weekend?</text>
            <image placement='appLogoOverride' src='ms-appx:///images/Reply.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action content='Mute group chat for 1 hour' arguments='action=mute' placement='contextMenu'/>
    </actions>
</toast>

Note

Itens adicionais no menu de contexto contribuem para o limite total de 5 botões em um toast.

A ativação de itens adicionais do menu de contexto é feita da mesma forma que os botões de notificação.

Inputs

As entradas são especificadas na região de ações Actions da notificação do aplicativo, o que significa que só ficam visíveis quando a notificação é expandida.

Caixa de texto de resposta rápida

Para habilitar uma caixa de texto de resposta rápida (por exemplo, em um aplicativo de mensagens), adicione uma entrada de texto e um botão e faça referência à ID do campo de entrada de texto para que o botão seja exibido ao lado do campo de entrada. O ícone opcional do botão, se fornecido, deve ser uma imagem de 32 x 32 pixels sem preenchimento, com pixels brancos definidos como transparentes e em escala 100%.

Uma captura de tela de uma notificação 'toast' com uma foto de perfil e algumas linhas de texto. Uma caixa de texto para digitar diretamente na notificação é incluída, bem como um botão para enviar a resposta.

var builder = new AppNotificationBuilder()
    .AddTextBox("textBox", "Type a reply", "Reply")
    .AddButton(AppNotificationButton("Send")
        .AddArguments("action", "Send")
        .SetInputId("textBox"))
    .BuildNotification();

var builder = new ToastContentBuilder()
    .AddInputTextBox("tbReply", "Type a reply")
        .AddButton(new ToastButton()
        .SetContent("Reply")
        .SetTextBoxId("tbReply") // To place button next to text box, reference text box's id
        .SetImageUri(new Uri("Assets/Reply.png", UriKind.Relative))
        .AddArgument("action", "reply"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Send"
      arguments="action=reply&amp;convId=9318"
      hint-inputId="textBox"
      imageUri="Assets/Reply.png"/>
  </actions>
</toast>

Entradas com barra de botões

Você também pode ter uma (ou muitas) entradas com botões normais exibidos abaixo das entradas.

Uma captura de tela de uma notificação do aplicativo mostrando uma linha de texto, uma caixa de texto e uma linha com dois botões rotulados como

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support quick reply text boxes.

new ToastContentBuilder()
    ...
    
    .AddInputTextBox("tbReply", "Type a reply")

    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply"))

    .AddButton(new ToastButton()
        .SetContent("Video call")
        .AddArgument("action", "videoCall"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Reply"
      arguments="action=reply&amp;threadId=9218"/>
    <action
      content="Video call"
      arguments="action=videocall&amp;threadId=9218"
      activationType="foreground"/>
  </actions>
</toast>

Entrada de seleção

Além das caixas de texto, você também pode usar um menu de seleção.

Uma captura de tela de uma notificação do aplicativo mostrando uma linha de texto, uma entrada de seleção com

var builder = new AppNotificationBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddComboBox(new AppNotificationComboBox("time")
        .SetTitle("Select an item:")
        .AddItem("breakfast", "Breakfast")
        .AddItem("lunch", "Lunch")
        .AddItem("dinner", "Dinner")
        .SetSelectedItem("lunch"))
    .AddButton(new AppNotificationButton("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement())
    .AddButton(new AppNotificationButton("Call restaurant")
        .AddArgument("action", "videocall")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement());

var builder = new ToastContentBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddToastInput(new ToastSelectionBox("time")
    {
        DefaultSelectionBoxItemId = "lunch",
        Items =
            {
                new ToastSelectionBoxItem("breakfast", "Breakfast"),
                new ToastSelectionBoxItem("lunch", "Lunch"),
                new ToastSelectionBoxItem("dinner", "Dinner")
            }
    })
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218"))
    .AddButton(new ToastButton()
        .SetContent("Call restaurant")
        .AddArgument("action", "videoCall")
        .AddArgument("threadId", "9218"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>4th coffee?</text>
            <text>When do you plan to come in tomorrow?</text>
        </binding>
    </visual>
    <actions>
        <input id='time' type='selection' title='Select an item:' defaultInput='lunch'>
            <selection id='breakfast' content='Breakfast'/><selection id='dinner' content='Dinner'/>
            <selection id='lunch' content='Lunch'/>
        </input>
        <action content='Reply' arguments='action=reply;threadId=9218' placement='contextMenu'/>
        <action content='Call Restaurant' arguments='action=videocall;threadId=9218' placement='contextMenu'/>
    </actions>
</toast>

Snooze/dismiss

Usando um menu de seleção e dois botões, podemos criar uma notificação de lembrete que utiliza as ações de adiar e descarte do sistema. Defina o cenário como "Lembrete" para que a notificação se comporte como um lembrete.

Uma captura de tela de uma notificação de aplicativo com linhas de texto que descrevem a hora e o local de uma reunião. Uma caixa de seleção tem

Vinculamos o botão de soneca à entrada do menu de seleção usando a propriedade SelectionBoxId no botão da notificação.

A sintaxe Microsoft.Windows.AppNotifications.Builder atualmente não dá suporte à ativação do sistema. Mas esse cenário tem suporte para aplicativos do SDK de Aplicativos do Windows e você pode criar notificações para esse cenário usando as Microsoft.Toolkit.Uwp.Notifications APIs ou XML bruto.

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support system activation. 
// But this scenario is supported for Windows App SDK apps, and you can build notifications for this 
// scenario using the `Microsoft.Toolkit.Uwp.Notifications` APIs or raw XML.

new ToastContentBuilder()
    .SetToastScenario(ToastScenario.Reminder)
    
    ...
    
    .AddToastInput(new ToastSelectionBox("snoozeTime")
    {
        DefaultSelectionBoxItemId = "15",
        Items =
        {
            new ToastSelectionBoxItem("5", "5 minutes"),
            new ToastSelectionBoxItem("15", "15 minutes"),
            new ToastSelectionBoxItem("60", "1 hour"),
            new ToastSelectionBoxItem("240", "4 hours"),
            new ToastSelectionBoxItem("1440", "1 day")
        }
    })

    .AddButton(new ToastButtonSnooze() { SelectionBoxId = "snoozeTime" })
    .AddButton(new ToastButtonDismiss());

<toast>
  <visual>
    <binding template="ToastGeneric">
      <text hint-maxLines="1">Adaptive Tiles Meeting</text>
      <text>Conf Room 2001 / Building 135</text>
      <text>10:00 AM - 10:30 AM</text>
    </binding>
  </visual>
  <actions>
    <input id="snoozeTime" type="selection" defaultInput="15">
      <selection id="1" content="1 minute"/>
      <selection id="15" content="15 minutes"/>
      <selection id="60" content="1 hour"/>
      <selection id="240" content="4 hours"/>
      <selection id="1440" content="1 day"/>
    </input>
    <action activationType="system" arguments="snooze" hint-inputId="snoozeTime" content="" />
    <action activationType="system" arguments="dismiss" content=""/>
  </actions>
</toast>

Para usar as ações de soneca e descaso do sistema:

Especifique um ToastButtonSnooze ou ToastButtonDismiss
Opcionalmente, especifique uma cadeia de caracteres de conteúdo personalizada:
Se você não fornecer uma cadeia de caracteres, usaremos automaticamente cadeias de caracteres localizadas para "Snooze" e "Dismiss".
Opcionalmente, especifique o SelectionBoxId:
Se você não quiser que o usuário selecione um intervalo de soneca e, em vez disso, apenas queira que sua notificação soneca apenas uma vez durante um intervalo de tempo definido pelo sistema (que seja consistente em todo o sistema operacional), não construa nenhuma entrada <>.
Se você quiser fornecer seleções de intervalo de soneca: – especifique SelectionBoxId na ação de soneca – corresponda o ID da entrada com o SelectionBoxId da ação de soneca – especifique que o valor de ToastSelectionBoxItemseja um número inteiro não negativo que represente o intervalo de soneca em minutos.

Audio

O áudio personalizado sempre foi suportado no Mobile e tem suporte na versão 1511 para desktop (build 10586) ou posterior. O áudio personalizado pode ser referenciado por meio dos seguintes caminhos:

ms-appx:///
ms-appdata:///

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioUri(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
</toast>

Como alternativa, você pode escolher da lista de ms-winsoundevents, que sempre tiveram suporte em ambas as plataformas.

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioEvent(AppNotificationSoundEvent.Alarm, AppNotificationAudioLooping.Loop);

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-winsoundevent:Notification.Looping.Alarm"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-winsoundevent:Notification.Looping.Alarm' loop='true'/>
</toast>

Consulte a página de esquema de áudio para obter informações sobre áudio em notificações do aplicativo. Para saber como enviar uma notificação de aplicativo que usa áudio personalizado, consulte áudio personalizado em toasts.

Scenarios

Para criar notificações importantes, alarmes, lembretes e notificações de chamada de entrada, basta usar uma notificação normal do aplicativo com um Cenário valor atribuído a ele. O cenário ajusta alguns comportamentos para criar uma experiência de usuário consistente e unificada. Há quatro valores possíveis dos Cenários :

Reminder
Alarm
IncomingCall
Urgent

Reminders

No cenário de lembrete, a notificação permanecerá na tela até que o usuário a descarte ou execute uma ação. No Windows Mobile, a notificação do aplicativo também será exibida já expandida. Um som de lembrete será reproduzido. Você deve fornecer pelo menos um botão na notificação do aplicativo. Caso contrário, a notificação será tratada como uma notificação normal.

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Reminder);

var builder = new ToastContentBuilder()
    .AddText("Notification text.")
    .SetToastScenario(ToastScenario.Reminder)

<toast scenario='reminder'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
</toast>

Alarms

Os alarmes se comportam da mesma forma que os lembretes, exceto que os alarmes também farão loop de áudio com um som de alarme padrão. Você deve fornecer pelo menos um botão na notificação do aplicativo. Caso contrário, a notificação será tratada como uma notificação normal.

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Alarm)
    .AddButton(new AppNotificationButton("Dismiss")
        .AddArgument("action", "dismiss"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .SetToastScenario(ToastScenario.Alarm)
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss"));

<toast scenario='alarm'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Dismiss' arguments='action=dismiss'/>
    </actions>
</toast>

Chamadas de entrada

As notificações de chamada de entrada são exibidas previamente expandidas em um formato de chamada especial e permanecem na tela do usuário até serem ignoradas. O áudio de toque será repetido por padrão. Em dispositivos Windows Mobile, eles exibem tela inteira.

Notificação pop-up de chamada recebida

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
    .AddText("incoming call - mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///images/profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Text reply")
        .SetToolTip("Text reply")
        .SetIcon(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new AppNotificationButton("Reminder")
        .SetToolTip("Reminder")
        .SetIcon(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new AppNotificationButton("Ignore")
        .SetToolTip("Ignore")
        .SetIcon(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new AppNotificationButton("Answer")
        .SetToolTip("Answer")
        .SetIcon(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

var builder = new ToastContentBuilder()
    .SetToastScenario(ToastScenario.IncomingCall)
    .AddText("Andrew Bares")
    .AddText("incoming call - mobile")
    .AddInlineImage(new Uri("ms-appx:///images/profile.png"), 
        "Andrew Bares",
        null,
        AdaptiveImageCrop.Circle)
    .AddButton(new ToastButton()
        .SetContent("Text reply")
        .SetImageUri(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Reminder")
        .SetImageUri(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Ignore")
        .SetImageUri(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Answer")
        .SetImageUri(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

<toast scenario='incomingCall'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>incoming call - mobile</text>
            <image src='ms-appx:///images/profile.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='Text reply' 
            arguments='textId=123' 
            imageUri='ms-appx:///images/reply.png' 
            hint-toolTip='Text reply'/>
        <action 
                content='Reminder' 
                arguments='reminderId=123' 
                imageUri='ms-appx:///images/reminder.png' 
                hint-toolTip='Reminder'/>
        <action 
                content='Ignore' 
                arguments='ignoreId=123' 
                imageUri='ms-appx:///images/ignore.png' 
                hint-toolTip='Ignore'/>
        <action 
            content='Answer' 
            arguments='answerId=123' 
            imageUri='ms-appx:///images/answer.png' 
            hint-toolTip='Answer'/>
    </actions>
</toast>

Notificações importantes

Important

Requer: você deve estar executando o Windows Insider Preview Build 22546 ou posterior para usar notificações importantes.

Notificações importantes permitem que os usuários tenham mais controle sobre quais aplicativos de primeiro e terceiros podem enviar notificações de aplicativos de alta prioridade (urgentes/importantes) que podem ultrapassar o Focus Assist (Não Incomodar). Isso pode ser modificado nas configurações de notificações.

Uma captura de tela de uma notificação urgente do aplicativo que tem um ponto de exclamação na área de atribuição ao lado do nome do aplicativo. A imagem também mostra a notificação de aplicativo iniciada pelo sistema que fornece botões para o usuário permitir ou não permitir notificações urgentes do aplicativo.

var builder = new AppNotificationBuilder()
    .AddText("Adaptive Tiles Meeting", 
        new AppNotificationTextProperties()
            .SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

if (AppNotificationBuilder.IsUrgentScenarioSupported())
{
    builder.SetScenario(AppNotificationScenario.Urgent);
}

// The builder syntax does not support important notifications yet.

<toast scenario='urgent'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

Localização e acessibilidade

Seus blocos e notificações de aplicativo podem carregar cadeias de caracteres e imagens personalizadas para linguagem de exibição, fator de escala de exibição, alto contraste e outros contextos de runtime. Para obter mais informações, consulte suporte à notificação de blocos e toast para linguagem, escala e alto contraste.

Gerenciamento da ativação

Para saber como lidar com ativações de aplicativo (o usuário clicando em seu toast ou nos botões do toast), consulte Enviar notificação local.

Comentários

Esta página foi útil?

Last updated on 2025-11-19

Compartilhar via

Conteúdo da notificação do aplicativo

Como começar

Estrutura de notificação do aplicativo

Área de atribuição

Visual

Elementos de texto

Imagem embutida

Substituição do logotipo do aplicativo

Sugestão de recorte

Imagem em destaque

Restrições de tamanho de imagem

Texto de atribuição

Carimbo de data/hora personalizado

Barra de progresso

Headers

Conteúdo adaptável

Colunas e elementos de texto

Buttons

Botões com ícones

Botões com cores

Ações de menu de contexto

Inputs

Caixa de texto de resposta rápida

Entradas com barra de botões

Entrada de seleção

Snooze/dismiss

Audio

Scenarios

Reminders

Alarms

Chamadas de entrada

Notificações importantes

Localização e acessibilidade

Gerenciamento da ativação

Tópicos relacionados

Comentários

Recursos adicionais